mirror of
https://github.com/jrnl-org/jrnl.git
synced 2025-07-03 23:16:14 +02:00
Merge branch 'develop' into docs-reference-1300
# Conflicts: # mkdocs.yml
This commit is contained in:
Micah Jerome Ellison
commit
f8f44d4d27
131 changed files with 1133 additions and 5136 deletions
|
|
@ -85,6 +85,25 @@ jrnl --config-override display_format fancy --config-override linewrap 20 \
|
|||
|
||||
```
|
||||
|
||||
### Using an alternate config
|
||||
|
||||
You can specify an alternate configuration file for the current instance of `jrnl` using `--config-file CONFIG_FILE_PATH` where
|
||||
`CONFIG_FILE_PATH` is a path to an alternate `jrnl` configuration file.
|
||||
|
||||
#### Examples:
|
||||
|
||||
```
|
||||
# Use personalised configuration file for personal journal entries
|
||||
jrnl --config-file ~/foo/jrnl/personal-config.yaml
|
||||
|
||||
# Use alternate configuration file for work-related entries
|
||||
jrnl --config-file ~/foo/jrnl/work-config.yaml
|
||||
|
||||
# Use default configuration file (created on installation)
|
||||
jrnl
|
||||
```
|
||||
|
||||
|
||||
## Multiple journal files
|
||||
|
||||
You can configure `jrnl`to use with multiple journals (eg.
|
||||
|
|
|
|||
127
docs/contributing.md
Normal file
127
docs/contributing.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
<!-- Copyright (C) 2012-2021 jrnl contributors
|
||||
License: https://www.gnu.org/licenses/gpl-3.0.html -->
|
||||
# Contributing to jrnl
|
||||
|
||||
We welcome contributions to jrnl, whether it's through reporting bugs, improving the documentation, testing releases, engaging in discussion on features and bugs, or writing code.
|
||||
|
||||
## Table of Contents
|
||||
* [Code of Conduct](#code-of-conduct)
|
||||
* [Reporting Bugs](#reporting-bugs)
|
||||
* [Editing Documentation](#editing-documentation)
|
||||
* [Testing](#testing)
|
||||
* [Submitting feature requests and ideas](#submitting-feature-requests-and-ideas)
|
||||
* [Developing jrnl](#developing)
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Before starting, please read the [Code of Conduct](https://github.com/jrnl-org/jrnl/blob/develop/CODE_OF_CONDUCT.md).
|
||||
|
||||
## Reporting Bugs
|
||||
|
||||
Please report bugs by [opening a new issue](https://github.com/jrnl-org/jrnl/issues/new/choose) and describing it as well as possible. Many bugs are specific to a particular operating system and Python version, so please include that information!
|
||||
|
||||
## Editing Documentation
|
||||
|
||||
If you find a typo or a mistake in the docs, please fix it right away and send a pull request. If you're unsure what to change but still see a problem, you can [open a new issue](https://github.com/jrnl-org/jrnl/issues/new/choose) with the "Documentation change" type.
|
||||
|
||||
To edit the documentation, edit the `docs/*.md` files on the **develop** branch. You can see the result by running `make html` (or `poetry run mkdocs serve` if on Windows) inside the project's root directory, then navigating your browser to [localhost:8000](http://localhost:8000).
|
||||
|
||||
The `gh-pages` branch is automatically maintained and generated after your changes are merged. You should never have to edit that branch.
|
||||
|
||||
### Recipes and external editors
|
||||
|
||||
If you'd like to share a jrnl command line trick that you find useful, or advice on how to integrate a particular external editor, you may find it worthwhile to add it to the ["Recipes" section](recipes.md).
|
||||
|
||||
## Testing
|
||||
|
||||
Much of the work of maintaining jrnl involves testing rather than coding.
|
||||
|
||||
The nature of jrnl means we deal with extremely sensitive data, and can't risk data loss. While jrnl does have a comprehensive automated testing suite, user testing is crucial to mitigating this risk.
|
||||
|
||||
### Prereleases
|
||||
|
||||
[Prereleases are deployed through PyPi much like normal releases](https://pypi.org/project/jrnl/#history). You can use [pipx](https://pypi.org/project/pipx/) to fetch them and test them. See the [changelog](https://github.com/jrnl-org/jrnl/blob/develop/CHANGELOG.md) for information on what has changed with each release.
|
||||
|
||||
### Pull requests
|
||||
|
||||
If you are comfortable enough with git, feel free to fetch particular [pull requests](https://github.com/jrnl-org/jrnl/pulls), test them yourself, and report back your findings. Bonus points if you can add a screencast of how the new feature works.
|
||||
|
||||
### Confirm bug reports
|
||||
|
||||
There are always [open bugs among our GitHub issues](https://github.com/jrnl-org/jrnl/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and many are specific to a particular OS, Python version, or jrnl version. A simple comment like "Confirmed on jrnl v2.2, MacOS 10.15, Python 3.8.1" would be extremely helpful in tracking down bugs.
|
||||
|
||||
### Automate tests
|
||||
|
||||
See the develop section below for information on how to contribute new automated tests.
|
||||
|
||||
## Submitting feature requests and ideas
|
||||
|
||||
If you have a feature request or idea for jrnl, please [open a new issue](https://github.com/jrnl-org/jrnl/issues/new/choose) and describe the goal of the feature, and any relevant use cases. We'll discuss the issue with you, and decide if it's a good fit for the project.
|
||||
|
||||
When discussing new features, please keep in mind our design goals. jrnl strives to
|
||||
[do one thing well](https://en.wikipedia.org/wiki/Unix_philosophy). To us, that means:
|
||||
|
||||
* being _nimble_
|
||||
* having a simple interface
|
||||
* avoiding duplicating functionality
|
||||
|
||||
## Developing
|
||||
|
||||
### Getting your environment set up
|
||||
|
||||
You will need to install [poetry](https://python-poetry.org/) to develop jrnl. It will take care of all of the project's other dependencies.
|
||||
|
||||
### Understanding the branches
|
||||
|
||||
jrnl uses two primary branches:
|
||||
|
||||
* `develop` - for ongoing development
|
||||
* `release` - for releases
|
||||
|
||||
In general, pull requests should be made on the `develop` branch.
|
||||
|
||||
### Common development commands
|
||||
|
||||
You can find an inventory of commands in the `makefile`. \*nix users can run the commands by typing `make` followed by the name of the command; however, Windows users will need to type out the commands directly, or install a third-party make tool such as [GNU Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm).
|
||||
|
||||
A typical development workflow includes:
|
||||
|
||||
* Installing dependencies: `poetry install`
|
||||
* Running tests: `make test`
|
||||
* Running the source in a virtual environment:
|
||||
* `poetry shell`
|
||||
* `jrnl` (with or without arguments as necessary)
|
||||
* Linting the code to standardize its style: `make lint`
|
||||
|
||||
### Updating automated tests
|
||||
|
||||
When resolving bugs or adding new functionality, please add tests to prevent that functionality from breaking in the future. If you notice any functionality that isn't covered in the tests, feel free to submit a test-only pull request as well.
|
||||
|
||||
For testing, jrnl uses [pytest](https://docs.pytest.org) for unit tests, and [pytest-bdd](https://pytest-bdd.readthedocs.io/) for integration testing. All tests are in the `tests` folder.
|
||||
|
||||
Many tests can be created by only editing `*.feature` files with the same format as other tests. For more complicated functionality, you may need to implement steps in `tests/lib/` which are then executed by your tests in the `feature` files.
|
||||
|
||||
### Submitting pull requests
|
||||
|
||||
When you're ready, feel free to submit a pull request (PR). The jrnl maintainers generally review the pull requests every two weeks, but the continuous integration pipeline will run on automated tests on it within a matter of minutes and will report back any issues it has found with your code across a variety of environments.
|
||||
|
||||
The pull request template contains a checklist full of housekeeping items. Please fill them out as necessary when you submit.
|
||||
|
||||
If a pull request contains failing tests, it probably will not be reviewed, and it definitely will not be approved. However, if you need help resolving a failing test, please mention that in your PR.
|
||||
|
||||
### Finding things to work on
|
||||
|
||||
You can search the [jrnl GitHub issues](https://github.com/jrnl-org/jrnl/issues) by [label](https://github.com/jrnl-org/jrnl/labels) for things to work on. Here are some labels worth searching:
|
||||
|
||||
* [critical](https://github.com/jrnl-org/jrnl/labels/critical)
|
||||
* [help wanted](https://github.com/jrnl-org/jrnl/labels/help%20wanted)
|
||||
* [bug](https://github.com/jrnl-org/jrnl/labels/bug)
|
||||
* [enhancement](https://github.com/jrnl-org/jrnl/labels/enhancement)
|
||||
|
||||
You can also get a feel for the project's priorities by reviewing the [milestones](https://github.com/jrnl-org/jrnl/milestones).
|
||||
|
||||
### A note for new programmers and programmers new to python
|
||||
|
||||
Although jrnl has grown quite a bit since its inception, the overall complexity (for an end-user program) is fairly low, and we hope you'll find the code easy enough to understand.
|
||||
|
||||
If you have a question, please don't hesitate to ask! Python is known for its welcoming community and openness to novice programmers, so feel free to fork the code and play around with it! If you create something you want to share with us, please create a pull request. We never expect pull requests to be perfect, idiomatic, instantly mergeable code. We can work through it together!
|
||||
61
docs/journal-types.md
Normal file
61
docs/journal-types.md
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
<!-- Copyright (C) 2012-2021 jrnl contributors
|
||||
License: https://www.gnu.org/licenses/gpl-3.0.html -->
|
||||
# Journal Types
|
||||
`jrnl` can store your journal in a few different ways:
|
||||
|
||||
- a single text file (encrypted or otherwise)
|
||||
- a folder structure organized by date containing unencrypted text files
|
||||
- the DayOne Classic format
|
||||
|
||||
There is no need to specify what type of journal you'd like to use. Instead,
|
||||
`jrnl` will automatically detect the journal type based on whether you're
|
||||
referencing a file or a folder in your [config file](advanced.md),
|
||||
and if it's a folder, whether or not DayOne Classic content exists in it.
|
||||
|
||||
## Single File
|
||||
The single file format is the most flexible, as it can be [encrypted](encryption.md).
|
||||
To use it, enter any path that is a file or does not already exist. You can
|
||||
use any extension. `jrnl` will automatically create the file when you save
|
||||
your first entry.
|
||||
|
||||
## Folder
|
||||
The folder journal format organizes your entries into subfolders for the year
|
||||
and month and `.txt` files for each day. If there are multiple entries in a day,
|
||||
they all appear in the same `.txt` file.
|
||||
|
||||
The directory tree structure is in this format: `YYYY/MM/DD.txt`. For instance, if
|
||||
you have an entry on May 5th, 2021 in a folder journal at `~/folderjournal`, it will
|
||||
be located in: `~/folderjournal/2021/05/05.txt`
|
||||
|
||||
!!! note
|
||||
When creating a new folder journal, you will need to create the folder before running
|
||||
`jrnl`. Otherwise, when you run `jrnl` for the first time, it will assume that you
|
||||
are creating a single file journal instead, and it will create a file at that path.
|
||||
|
||||
!!! note
|
||||
Folder journals can't be encrypted.
|
||||
|
||||
## Day One Classic
|
||||
`jrnl` supports the original data format used by DayOne. It's similar to the folder
|
||||
journal format, except it's identified by either of these characteristics:
|
||||
|
||||
* the folder has a `.dayone` extension
|
||||
* the folder has a subfolder named `entries`
|
||||
|
||||
This is not to be confused with the DayOne 2.0 format, [which is very different](https://help.dayoneapp.com/en/articles/1187337-day-one-classic-is-retired).
|
||||
|
||||
!!! note
|
||||
DayOne Classic journals can't be encrypted.
|
||||
|
||||
## Changing your journal type
|
||||
You can't simply modify a journal's configuration to change its type. Instead,
|
||||
define a new journal as the type you'd like, and use
|
||||
[piping](https://en.wikipedia.org/wiki/Redirection_(computing)#Piping)
|
||||
to export your old journal as `txt` to an import command on your new journal.
|
||||
|
||||
For instance, if you have a `projects` journal you would like to import into
|
||||
a `new` journal, you would run the following after setting up the configuration
|
||||
for your `new` journal:
|
||||
```
|
||||
jrnl projects --format txt | jrnl new --import
|
||||
```
|
||||
|
|
@ -28,7 +28,7 @@ You can do things like
|
|||
jrnl @fixed -starred -n 10 -to "jan 2013" --short
|
||||
```
|
||||
|
||||
To get a short summary of the 10 most recent, favourited entries before
|
||||
To get a short summary of the 10 most recent, favourite entries before
|
||||
January 1, 2013 that are tagged with `@fixed`.
|
||||
|
||||
### Statistics
|
||||
|
|
@ -52,8 +52,8 @@ print exactly one line per entry).
|
|||
|
||||
### Importing older files
|
||||
|
||||
If you want to import a file as an entry to jrnl, you can just do `jrnl < entry.ext`. But what if you want the modification date of the file to
|
||||
be the date of the entry in jrnl? Try this
|
||||
If you want to import a file as an entry to `jrnl`, you can just do `jrnl < entry.ext`. But what if you want the modification date of the file to
|
||||
be the date of the entry in `jrnl`? Try this
|
||||
|
||||
```sh
|
||||
echo `stat -f %Sm -t '%d %b %Y at %H:%M: ' entry.txt` `cat entry.txt` | jrnl
|
||||
|
|
@ -73,11 +73,11 @@ jrnlimport () {
|
|||
### Using templates
|
||||
|
||||
!!! note
|
||||
Templates require an [external editor](./advanced.md) be configured.
|
||||
Templates require an [external editor](./advanced.md) be configured.
|
||||
|
||||
A template is a code snippet that makes it easier to use repeated text
|
||||
A template is a code snippet that makes it easier to use repeated text
|
||||
each time a new journal entry is started. There are two ways you can utilize
|
||||
templates in your entries.
|
||||
templates in your entries.
|
||||
|
||||
#### 1. Command line arguments
|
||||
|
||||
|
|
@ -85,17 +85,17 @@ If you had a `template.txt` file with the following contents:
|
|||
|
||||
```sh
|
||||
My Personal Journal
|
||||
Title:
|
||||
Title:
|
||||
|
||||
Body:
|
||||
```
|
||||
|
||||
The `template.txt` file could be used to create a new entry with these
|
||||
command line arguements:
|
||||
The `template.txt` file could be used to create a new entry with these
|
||||
command line arguments:
|
||||
|
||||
```sh
|
||||
jrnl < template.txt # Imports template.txt as the most recent entry
|
||||
jrnl -1 --edit # Opens the most recent entry in the editor
|
||||
jrnl -1 --edit # Opens the most recent entry in the editor
|
||||
```
|
||||
|
||||
#### 2. Include the template file in `jrnl.yaml`
|
||||
|
|
@ -113,8 +113,8 @@ template: "/path/to/template.txt"
|
|||
Changes can be saved as you continue writing the journal entry and will be
|
||||
logged as a new entry in the journal you specified in the original argument.
|
||||
|
||||
!!! tip
|
||||
To read your journal entry or to verify the entry saved, you can use this
|
||||
!!! tip
|
||||
To read your journal entry or to verify the entry saved, you can use this
|
||||
command: `jrnl -n 1` (Check out [Formats](./formats.md) for more options).
|
||||
|
||||
```sh
|
||||
|
|
@ -137,9 +137,9 @@ log_question 'What did I achieve today?'
|
|||
log_question 'What did I make progress with?'
|
||||
```
|
||||
|
||||
Whenever your shell is reloaded, you will be prompted to answer each of the
|
||||
questions in the example above. Each answer will be logged as a separate
|
||||
journal entry at the `default_hour` and `default_minute` listed in your
|
||||
Whenever your shell is reloaded, you will be prompted to answer each of the
|
||||
questions in the example above. Each answer will be logged as a separate
|
||||
journal entry at the `default_hour` and `default_minute` listed in your
|
||||
`jrnl.yaml` [config file](../advanced/#configuration-file).
|
||||
|
||||
### Display random entry
|
||||
|
|
@ -155,36 +155,62 @@ jrnl -on "$(jrnl --short | shuf -n 1 | cut -d' ' -f1,2)"
|
|||
```
|
||||
|
||||
|
||||
### Launch a terminal for rapid logging
|
||||
You can use this to launch a terminal that is the `jrnl` stdin prompt so you can start typing away immediately.
|
||||
### Launch a terminal for rapid logging
|
||||
You can use this to launch a terminal that is the `jrnl` stdin prompt so you can start typing away immediately.
|
||||
|
||||
```bash
|
||||
jrnl now --config-override editor:""
|
||||
jrnl --config-override editor ""
|
||||
```
|
||||
|
||||
Bind this to a keyboard shortcut.
|
||||
Bind this to a keyboard shortcut.
|
||||
|
||||
Map `Super+Alt+J` to launch the terminal with jrnl prompt
|
||||
Map `Super+Alt+J` to launch the terminal with `jrnl` prompt
|
||||
|
||||
- **xbindkeys**
|
||||
In your `.xbindkeysrc`
|
||||
|
||||
```ini
|
||||
Mod4+Mod1+j
|
||||
alacritty -t floating-jrnl -e jrnl now --config-override editor:"",
|
||||
alacritty -t floating-jrnl -e jrnl --config-override editor "",
|
||||
```
|
||||
|
||||
- **I3 WM** Launch a floating terminal with the `jrnl` prompt
|
||||
|
||||
```ini
|
||||
bindsym Mod4+Mod1+j exec --no-startup-id alacritty -t floating-jrnl -e jrnl --config-override editor:""
|
||||
bindsym Mod4+Mod1+j exec --no-startup-id alacritty -t floating-jrnl -e jrnl --config-override editor ""
|
||||
for_window[title="floating *"] floating enable
|
||||
```
|
||||
### Visualize Formatted Markdown in the CLI
|
||||
|
||||
Out of the box, `jrnl` can output journal entries in Markdown. To visualize it, you can pipe to [mdless](https://github.com/ttscoff/mdless), which is a [less](https://en.wikipedia.org/wiki/Less_(Unix))-like tool that allows you to visualize your Markdown text with formatting and syntax highlighting from the CLI. You can use this in any shell that supports piping.
|
||||
|
||||
The simplest way to visualize your Markdown output with `mdless` is as follows:
|
||||
```sh
|
||||
jrnl --export md | mdless
|
||||
```
|
||||
|
||||
This will render your Markdown output in the whole screen.
|
||||
|
||||
Fortunately, `mdless` has an option that allows you to adjust the screen width by using the `-w` option as follows:
|
||||
|
||||
```sh
|
||||
jrnl --export md | mdless -w 70
|
||||
```
|
||||
|
||||
If you want Markdown to be your default display format, you can define this in your config file as follows:
|
||||
|
||||
```yaml
|
||||
display_format: md
|
||||
# or
|
||||
display_format: markdown
|
||||
```
|
||||
|
||||
For more information on how `jrnl` outputs your entries in Markdown, please visit the [Formats](./formats.md) section.
|
||||
|
||||
## External editors
|
||||
|
||||
Configure your preferred external editor by updating the `editor` option
|
||||
in your `jrnl.yaml` file. (See [advanced usage](./advanced.md) for details).
|
||||
Configure your preferred external editor by updating the `editor` option
|
||||
in your `jrnl.yaml` file. (See [advanced usage](./advanced.md) for details).
|
||||
|
||||
!!! note
|
||||
To save and log any entry edits, save and close the file.
|
||||
|
|
@ -201,7 +227,7 @@ tools for Sublime Text and configure your `jrnl.yaml` like this:
|
|||
editor: "subl -w"
|
||||
```
|
||||
|
||||
Note the `-w` flag to make sure jrnl waits for Sublime Text to close the
|
||||
Note the `-w` flag to make sure `jrnl` waits for Sublime Text to close the
|
||||
file before writing into the journal.
|
||||
|
||||
### Visual Studio Code
|
||||
|
|
@ -252,20 +278,20 @@ grep -A 1 CFBundleIdentifier /Applications/iA\ Writer.app/Contents/Info.plist
|
|||
### Notepad++ on Windows
|
||||
|
||||
To set [Notepad++](http://notepad-plus-plus.org/) as your editor, edit
|
||||
the jrnl config file (`jrnl.yaml`) like this:
|
||||
the `jrnl` config file (`jrnl.yaml`) like this:
|
||||
|
||||
```yaml
|
||||
editor: "C:\\Program Files (x86)\\Notepad++\\notepad++.exe -multiInst -nosession"
|
||||
```
|
||||
|
||||
The double backslashes are needed so jrnl can read the file path
|
||||
correctly. The `-multiInst -nosession` options will cause jrnl to open
|
||||
The double backslashes are needed so `jrnl` can read the file path
|
||||
correctly. The `-multiInst -nosession` options will cause `jrnl` to open
|
||||
its own Notepad++ window.
|
||||
|
||||
|
||||
### emacs
|
||||
|
||||
To use `emacs` as your editor, edit the jrnl config file (`jrnl.yaml`) like this:
|
||||
To use `emacs` as your editor, edit the `jrnl` config file (`jrnl.yaml`) like this:
|
||||
|
||||
```yaml
|
||||
editor: emacsclient -a "" -c
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue