mirror of
https://github.com/jrnl-org/jrnl.git
synced 2025-05-21 05:28:31 +02:00
Cleaned up usage.md for clarity, formatting, and grammar.
While working on it, I hard-wrapped the lines to 80 characters. Hope that doesn't complicate things. Note: I changed the Steve Buscemi quote to maintain compliance with the Code of Conduct.
This commit is contained in:
parent
732831695f
commit
6179ea43e1
1 changed files with 67 additions and 58 deletions
125
docs/usage.md
125
docs/usage.md
|
@ -1,46 +1,45 @@
|
|||
# Basic Usage
|
||||
|
||||
`jrnl` has two modes: **composing** and **viewing**. Basically, whenever
|
||||
you _don't_ supply any arguments that start
|
||||
with a dash or double-dash, you're in composing mode, meaning you can
|
||||
write your entry on the command line or an editor of your choice.
|
||||
`jrnl` has two modes: **composing** and **viewing**. Whenever you don't enter
|
||||
any arguments that start with a dash (`-`) or double-dash (`--`), you're in
|
||||
composing mode, meaning that you can write your entry on the command line.
|
||||
|
||||
We intentionally break a convention on command line arguments: all
|
||||
arguments starting with a _single dash_
|
||||
will _filter_ your journal before viewing
|
||||
it, and can be combined arbitrarily. Arguments with a
|
||||
_double dash_ will control how your journal
|
||||
is displayed or exported and are mutually exclusive (ie. you can only
|
||||
specify one way to display or export your journal at a time).
|
||||
We intentionally break a convention on command line arguments: all arguments
|
||||
starting with a _single dash_ (`-`) will _filter_ your journal before viewing
|
||||
it. Filter arguments can be combined arbitrarily. Arguments with a _double dash_
|
||||
(`--`) will _control_ how your journal is displayed or exported. Control
|
||||
arguments are mutually exclusive (i.e., you can only specify one way to display
|
||||
or export your journal at a time).
|
||||
|
||||
## Listing Journals
|
||||
|
||||
You can list the journals accessible by jrnl
|
||||
You can list the journals accessible by `jrnl`:
|
||||
|
||||
```sh
|
||||
jrnl -ls
|
||||
```
|
||||
|
||||
The journals displayed correspond to those specified in the jrnl
|
||||
configuration file.
|
||||
The journals displayed correspond to those specified in the `jrnl` configuration
|
||||
file.
|
||||
|
||||
## Composing Entries
|
||||
|
||||
Composing mode is entered by either starting `jrnl` without any
|
||||
arguments -- which will prompt you to write an entry or launch your
|
||||
editor -- or by just writing an entry on the prompt, such as
|
||||
Composing mode is entered by either starting `jrnl` without any arguments --
|
||||
which will prompt you to write an entry or launch your editor -- or by just
|
||||
writing an entry on the prompt, such as
|
||||
|
||||
```sh
|
||||
jrnl today at 3am: I just met Steve Buscemi in a bar! He looked funny.
|
||||
jrnl today at 3am: I just met Steve Buscemi in a bar! He was on fire.
|
||||
```
|
||||
|
||||
!!! note
|
||||
Most shell contains a certain number of reserved characters, such as `#`
|
||||
and `*`. Unbalanced quotes, parenthesis, and so on will also get into
|
||||
the way of your editing.
|
||||
For writing longer entries, just enter `jrnl`
|
||||
and hit `return`. Only then enter the text of your journal entry.
|
||||
Alternatively, `use an external editor <advanced>`).
|
||||
Most shells contain a certain number of reserved characters, such as `#` and
|
||||
`*`. These characters, as well as unbalanced single or double quotation
|
||||
marks, parentheses, and others, likely will cause problems. Although
|
||||
reserved characters can be escaped using `\`, this is not ideal for
|
||||
long-form writing. The solution: first enter `jrnl` and hit `return`. You
|
||||
can then enter the text of your journal entry. Alternatively, you can `use
|
||||
an external editor <advanced>`).
|
||||
|
||||
You can also import an entry directly from a file
|
||||
|
||||
|
@ -62,23 +61,23 @@ Timestamps that work:
|
|||
|
||||
### Starring entries
|
||||
|
||||
To mark an entry as a favourite, simply "star" it
|
||||
To mark an entry as a favorite, simply "star" it
|
||||
|
||||
```sh
|
||||
jrnl last sunday *: Best day of my life.
|
||||
```
|
||||
|
||||
If you don't want to add a date (ie. your entry will be dated as now),
|
||||
The following options are equivalent:
|
||||
If you don't want to add a date (i.e., you want the date to be entered as
|
||||
_now_), the following options are equivalent:
|
||||
|
||||
- `jrnl *: Best day of my life.`
|
||||
- `jrnl *Best day of my life.`
|
||||
- `jrnl Best day of my life.*`
|
||||
|
||||
!!! note
|
||||
Just make sure that the asterisk sign is **not** surrounded by
|
||||
whitespaces, e.g. `jrnl Best day of my life! *` will **not** work (the
|
||||
reason being that the `*` sign has a special meaning on most shells).
|
||||
Make sure that the asterisk sign is **not** surrounded by whitespaces. `jrnl
|
||||
Best day of my life! *` will not work because the `*` sign has a special
|
||||
meaning in most shells).
|
||||
|
||||
## Viewing
|
||||
|
||||
|
@ -86,15 +85,15 @@ The following options are equivalent:
|
|||
jrnl -n 10
|
||||
```
|
||||
|
||||
will list you the ten latest entries (if you're lazy, `jrnl -10` will do
|
||||
the same),
|
||||
lists the ten most recent entries (`jrnl -10` works the same way).
|
||||
|
||||
```sh
|
||||
jrnl -from "last year" -until march
|
||||
```
|
||||
|
||||
everything that happened from the start of last year to the start of
|
||||
last march. To only see your favourite entries, use
|
||||
displays everything that happened from the beginning of last year until the
|
||||
beginning of the past March. To display only your favorite (starred) entries,
|
||||
use
|
||||
|
||||
```sh
|
||||
jrnl -starred
|
||||
|
@ -103,58 +102,68 @@ jrnl -starred
|
|||
## Using Tags
|
||||
|
||||
Keep track of people, projects or locations, by tagging them with an `@`
|
||||
in your entries
|
||||
in your entries:
|
||||
|
||||
```sh
|
||||
jrnl Had a wonderful day on the @beach with @Tom and @Anna.
|
||||
jrnl Had a wonderful day at the @beach with @Tom and @Anna.
|
||||
```
|
||||
|
||||
You can filter your journal entries just like this:
|
||||
You can filter your journal entries by tag. For example,
|
||||
|
||||
```sh
|
||||
jrnl @pinkie @WorldDomination
|
||||
```
|
||||
|
||||
Will print all entries in which either `@pinkie` or `@WorldDomination`
|
||||
displays all entries in which either `@pinkie` or `@WorldDomination`
|
||||
occurred.
|
||||
|
||||
```sh
|
||||
jrnl -n 5 -and @pinkie @WorldDomination
|
||||
```
|
||||
|
||||
the last five entries containing both `@pinkie` **and** `@worldDomination`.
|
||||
You can change which symbols you'd like to use for tagging in the
|
||||
configuration.
|
||||
displays the last five entries containing both `@pinkie` **and**
|
||||
`@worldDomination`. You can change which symbols you'd like to use for tagging
|
||||
in the configuration.
|
||||
|
||||
!!! note
|
||||
`jrnl @pinkie @WorldDomination` will switch to viewing mode because
|
||||
although **no** command line arguments are given, all the input strings
|
||||
look like tags - _jrnl_ will assume you want to filter by tag.
|
||||
Entering `jrnl @pinkie @WorldDomination` will display entries in which both
|
||||
tags are present because, although no command line arguments are given, all
|
||||
of the input strings look like tags. `jrnl` will assume you want to filter
|
||||
by tag, rather than create a new entry that consists only of tags.
|
||||
|
||||
## Editing older entries
|
||||
|
||||
You can edit selected entries after you wrote them. This is particularly
|
||||
useful when your journal file is encrypted. To use this feature, you need
|
||||
to have an editor configured in your journal configuration file (see
|
||||
`advanced usage <advanced>`)
|
||||
## Editing Existing Entries
|
||||
|
||||
You can edit entries after writing them. This is particularly useful when your
|
||||
journal file is encrypted. To use this feature, you need to have an external
|
||||
editor configured in your configuration file (see `advanced usage <advanced>`).
|
||||
You can also edit only the entries that match specific search criteria. For
|
||||
example,
|
||||
|
||||
```sh
|
||||
jrnl -until 1950 @texas -and @history --edit
|
||||
```
|
||||
|
||||
Will open your editor with all entries tagged with `@texas` and
|
||||
`@history` before 1950. You can make any changes to them you want; after
|
||||
you save the file and close the editor, your journal will be updated.
|
||||
opens your external editor displaying all entries tagged with `@texas` and
|
||||
`@history` that were written before 1950. After making changes, save and close
|
||||
the file, and only those entries will be modified (and encrypted, if
|
||||
applicable).
|
||||
|
||||
Of course, if you are using multiple journals, you can also edit e.g.
|
||||
the latest entry of your work journal with `jrnl work -n 1 --edit`. In
|
||||
any case, this will bring up your editor and save (and, if applicable,
|
||||
encrypt) your edited journal after you save and exit the editor.
|
||||
If you are using multiple journals, it's easy to edit specific entries from
|
||||
specific journals. Simply prefix the filter string with the name of the journal.
|
||||
For example,
|
||||
|
||||
You can also use this feature for deleting entries from your journal
|
||||
```sh
|
||||
jrnl work -n 1 --edit
|
||||
```
|
||||
|
||||
opens the most recent entry in the 'work' journal in your external editor.
|
||||
|
||||
You can also use this feature for deleting entries from your journal. Open an external editor with the entries you want to delete...
|
||||
|
||||
```sh
|
||||
jrnl @texas -until 'june 2012' --edit
|
||||
```
|
||||
|
||||
Just select all text, press delete, and everything is gone...
|
||||
...select all text, delete it, save and close, and all of those entries are
|
||||
removed from the journal.
|
||||
|
|
Loading…
Add table
Reference in a new issue