# Jour
This repository contains the Jour tool, an utility for a high-level machine maintenance journal. The final purpose of this tool is to write and handle a journal in which the user or some automated process can write and tag the performed actions related with the machine configuration, maintenance, and other relevant information. This way, the user can keep track of the changes and the performed actions, and also can obtain a high-level overview of the machine status over time.
Some examples of the usage of this tool could be:
1. Write a journal entry to register an OS update. Just run the following command in the terminal:
```sh
jour --write 'OS update to 24.5.2'
```
Output:
```
0014. 2024-03-16 17:04:50,123 - test_username - OS update to 24.5.2.
```
2. Write a journal entry about a backup of the machine. Use a Jour tag.
```sh
jour --write 'General system backup' && jour --tag 'BUP'
```
Output:
```
0015. 2024-03-16 17:06:08,630 - test_username - General system backup. #BUP1
```
3. Register other backup some time later. Use the same tag. Take into account that the tag index is automatically incremented, like the entry index.
```sh
jour --write 'General system backup' && jour --tag 'BUP'
```
Output:
```
0016. 2024-03-16 17:09:14,123 - test_username - General system backup. #BUP2
```
You could then use these same tags `BUP1`, `BUP2`, etc. to also tag a commit in a Git repository with your machine config or dotfiles. This way your Jour journal and your machine config are paired.
### The journal file
Basically, each new journal entry is a new line in the journal file, with an index and a date. The index is useful to cross-reference the journal entries. The entries are appended to the journal file sequentially. The journal file location is defined in the environment variable `$JOURNAL` (or, by default in `~/journal.md`). If the tool cannot reach the file, the incoming entries are stored in an emergency journal file, which location is `$JOURNAL_EMERGENCY`, if defined, or `~/journal_emergency.md`, otherwise. This is useful if, for example, the journal file is located in a remote file system or cloud provider and the connection is lost. The user can then manually arrange the journal entries merging the emergency journal.
In addition to the entries, like explained before, the tool also handle tags, like `#BUP1`, to an easier navigation of the journal file. This is specially useful to link the journal entries with tags in a configuration Git repository, for example, because a journal tag can be also set in the repo.
Journal format is Markdown, so the user can also export all the history to a more readable format, like a PDF, using a Markdown to PDF converter.
After some time, the user can obtain with Jour a high-level traceability of the machine changes and fixes, helping even to debug some issues or roll back to a previous state.
## Installation
### Homebrew
First add Jour author's public [tap](https://github.com/bglezseoane/homebrew-tap):
```sh
brew tap bglezseoane/tap
```
Then install Jour with:
```sh
brew install jour
```
### PyPI
This tool is [publicly available in PyPI](https://pypi.org/project/jour), so you could use any method that consumes this registry to install it (like `pip`). As a recommendation, you could use PipX:
```
pipx install jour
# Or...
pip install jour
```
Raw data
{
"_id": null,
"home_page": "https://github.com/bglezseoane/jour",
"name": "jour",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "configuration, journal, journaling, machine-administration, machine-maintenance, markdown",
"author": "Borja Gonz\u00e1lez Seoane",
"author_email": "borja@glezseoane.es",
"download_url": "https://files.pythonhosted.org/packages/b5/e9/8cadbb9571129c85bd4a52c4bd65aa1f4f21a5810697725eced65c86f2f8/jour-2.0.2.tar.gz",
"platform": null,
"description": "# Jour\n\nThis repository contains the Jour tool, an utility for a high-level machine maintenance journal. The final purpose of this tool is to write and handle a journal in which the user or some automated process can write and tag the performed actions related with the machine configuration, maintenance, and other relevant information. This way, the user can keep track of the changes and the performed actions, and also can obtain a high-level overview of the machine status over time.\n\nSome examples of the usage of this tool could be:\n\n1. Write a journal entry to register an OS update. Just run the following command in the terminal:\n\n```sh\njour --write 'OS update to 24.5.2'\n```\n\nOutput:\n\n```\n0014. 2024-03-16 17:04:50,123 - test_username - OS update to 24.5.2.\n```\n\n2. Write a journal entry about a backup of the machine. Use a Jour tag.\n\n```sh\njour --write 'General system backup' && jour --tag 'BUP'\n```\n\nOutput:\n\n```\n0015. 2024-03-16 17:06:08,630 - test_username - General system backup. #BUP1\n```\n\n3. Register other backup some time later. Use the same tag. Take into account that the tag index is automatically incremented, like the entry index.\n\n```sh\njour --write 'General system backup' && jour --tag 'BUP'\n```\n\nOutput:\n\n```\n0016. 2024-03-16 17:09:14,123 - test_username - General system backup. #BUP2\n```\n\nYou could then use these same tags `BUP1`, `BUP2`, etc. to also tag a commit in a Git repository with your machine config or dotfiles. This way your Jour journal and your machine config are paired.\n\n### The journal file\n\nBasically, each new journal entry is a new line in the journal file, with an index and a date. The index is useful to cross-reference the journal entries. The entries are appended to the journal file sequentially. The journal file location is defined in the environment variable `$JOURNAL` (or, by default in `~/journal.md`). If the tool cannot reach the file, the incoming entries are stored in an emergency journal file, which location is `$JOURNAL_EMERGENCY`, if defined, or `~/journal_emergency.md`, otherwise. This is useful if, for example, the journal file is located in a remote file system or cloud provider and the connection is lost. The user can then manually arrange the journal entries merging the emergency journal.\n\nIn addition to the entries, like explained before, the tool also handle tags, like `#BUP1`, to an easier navigation of the journal file. This is specially useful to link the journal entries with tags in a configuration Git repository, for example, because a journal tag can be also set in the repo.\n\nJournal format is Markdown, so the user can also export all the history to a more readable format, like a PDF, using a Markdown to PDF converter.\n\nAfter some time, the user can obtain with Jour a high-level traceability of the machine changes and fixes, helping even to debug some issues or roll back to a previous state.\n\n## Installation\n\n### Homebrew\n\nFirst add Jour author's public [tap](https://github.com/bglezseoane/homebrew-tap):\n\n```sh\nbrew tap bglezseoane/tap\n```\n\nThen install Jour with:\n\n```sh\nbrew install jour\n```\n\n### PyPI\n\nThis tool is [publicly available in PyPI](https://pypi.org/project/jour), so you could use any method that consumes this registry to install it (like `pip`). As a recommendation, you could use PipX:\n\n```\npipx install jour\n\n# Or...\npip install jour\n```\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "An utility for a high-level machine maintenance journal",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/bglezseoane/jour",
"Repository": "https://github.com/bglezseoane/jour"
},
"split_keywords": [
"configuration",
" journal",
" journaling",
" machine-administration",
" machine-maintenance",
" markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "01156b2e740c439913a5dc6695613e35fcaba7ddd20fbbc2321c78bcaa87d06c",
"md5": "84ddd8a0550fae95fe7721553aa410b6",
"sha256": "f44a11247a67ff5951815c3385c6d434aadb6ef2db4a955d496d477666f39e95"
},
"downloads": -1,
"filename": "jour-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84ddd8a0550fae95fe7721553aa410b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 20104,
"upload_time": "2024-06-03T13:53:11",
"upload_time_iso_8601": "2024-06-03T13:53:11.139051Z",
"url": "https://files.pythonhosted.org/packages/01/15/6b2e740c439913a5dc6695613e35fcaba7ddd20fbbc2321c78bcaa87d06c/jour-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b5e98cadbb9571129c85bd4a52c4bd65aa1f4f21a5810697725eced65c86f2f8",
"md5": "de956be68a1c1de58a7ed66075dbc547",
"sha256": "7a0869b0ee0f39f26bc967be45f36049c30d47356e0279ef5ef12e072f68fa85"
},
"downloads": -1,
"filename": "jour-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "de956be68a1c1de58a7ed66075dbc547",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 19313,
"upload_time": "2024-06-03T13:53:12",
"upload_time_iso_8601": "2024-06-03T13:53:12.495992Z",
"url": "https://files.pythonhosted.org/packages/b5/e9/8cadbb9571129c85bd4a52c4bd65aa1f4f21a5810697725eced65c86f2f8/jour-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-03 13:53:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bglezseoane",
"github_project": "jour",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jour"
}
JSON
