1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
<!-- Copyright (C) 2012-2021 jrnl contributors
License: https://www.gnu.org/licenses/gpl-3.0.html -->
# Formats
`jrnl` supports a variety of alternate formats. These can be used to display your
journal in a different manner than the `jrnl` default, and can even be used to pipe data
from your journal for use in another program to create reports, or do whatever you want
with your `jrnl` data.
Any of these formats can be used with a search (e.g. `jrnl -contains "lorem ipsum"
--format json`) to display the results of that search in the given format, or can be
used alone (e.g. `jrnl --format json`) to display all entries from the selected journal.
This page shows examples of all the built-in formats, but since `jrnl` supports adding
more formats through plugins, you may have more available on your system. Please see
`jrnl --help` for a list of which formats are available on your system.
Any of these formats can be used interchangeably, and are only grouped into "display",
"data", and "report" formats below for convenience.
## Display Formats
These formats are mainly intended for displaying your journal in the terminal. Even so,
they can still be used in the same way as any other format (like written to a file, if
you choose).
### Pretty
``` sh
jrnl --format pretty
# or
jrnl -1 # any search
```
This is the default format in `jrnl`. If no `--format` is given, `pretty` will be used.
It displays the timestamp of each entry formatted to by the user config followed by the
title on the same line. Then the body of the entry is shown below.
This format is configurable through these values from your config file (see
[Advanced Usage](./advanced.md) for more details):
- `colors`
- `body`
- `date`
- `tags`
- `title`
- `indent_character`
- `linewrap`
- `timeformat`
**Example output**:
``` sh
2020-06-28 18:22 This is the first sample entry
| This is the sample body text of the first sample entry.
2020-07-01 20:00 This is the second sample entry
| This is the sample body text of the second sample entry, but
| this one has a @tag.
2020-07-02 09:00 This is the third sample entry
| This is the sample body text of the third sample entry.
```
### Short
``` sh
jrnl --format short
# or
jrnl --short
```
This will shorten entries to display only the date and title. It is essentially the
`pretty` format but without the body of each entry. This can be useful if you have long
journal entries and only want to see a list of entries that match your search.
**Example output**:
``` sh
2020-06-28 18:22 This is the first sample entry
2020-07-01 20:00 This is the second sample entry
2020-07-02 09:00 This is the third sample entry
```
### Fancy (or Boxed)
``` sh
jrnl --format fancy
# or
jrnl --format boxed
```
This format outlines each entry with a border. This makes it much easier to tell where
each entry starts and ends. It's an example of how free-form the formats can be, and also
just looks kinda ~*~fancy~*~, if you're into that kind of thing.
**Example output**:
``` sh
┎──────────────────────────────────────────────────────────────────────╮2020-06-28 18:22
┃ This is the first sample entry ╘═══════════════╕
┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
┃ This is the sample body text of the first sample entry. │
┖──────────────────────────────────────────────────────────────────────────────────────┘
┎──────────────────────────────────────────────────────────────────────╮2020-07-01 20:00
┃ This is the second sample entry ╘═══════════════╕
┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
┃ This is the sample body text of the second sample entry, but this one has a @tag. │
┖──────────────────────────────────────────────────────────────────────────────────────┘
┎──────────────────────────────────────────────────────────────────────╮2020-07-02 09:00
┃ This is the third sample entry ╘═══════════════╕
┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
┃ This is the sample body text of the third sample entry. │
┖──────────────────────────────────────────────────────────────────────────────────────┘
```
## Data Formats
These formats are mainly intended for piping or exporting your journal to other
programs. Even so, they can still be used in the same way as any other format (like
written to a file, or displayed in your terminal, if you want).
### JSON
``` sh
jrnl --format json
```
JSON is a very handy format used by many programs and has support in nearly every
programming language. There are many things you could do with JSON data. Maybe you could
use `jq` ([project page](https://github.com/stedolan/jq)) to filter through the fields in your journal.
Like this:
``` sh
$ j -3 --format json | jq '.entries[].date' jrnl-GFqVlfgP-py3.8
"2020-06-28"
"2020-07-01"
"2020-07-02"
```
Or why not create a [beautiful timeline](http://timeline.knightlab.com/) of your journal?
**Example output**:
``` json
{
"tags": {
"@tag": 1
},
"entries": [
{
"title": "This is the first sample entry",
"body": "This is the sample body text of the first sample entry.",
"date": "2020-06-28",
"time": "18:22",
"tags": [],
"starred": false
},
{
"title": "This is the second sample entry",
"body": "This is the sample body text of the second sample entry, but this one has a @tag.",
"date": "2020-07-01",
"time": "20:00",
"tags": [
"@tag"
],
"starred": false
},
{
"title": "This is the third sample entry",
"body": "This is the sample body text of the third sample entry.",
"date": "2020-07-02",
"time": "09:00",
"tags": [],
"starred": false
}
]
}
```
### Markdown
``` sh
jrnl --format markdown
# or
jrnl --format md
```
Markdown is a simple markup language that is human readable and can be used to be
rendered to other formats (html, pdf). `jrnl`'s
[README](https://github.com/jrnl-org/jrnl/blob/develop/README.md) for example is
formatted in markdown, then Github adds some formatting to make it look nice.
The markdown format groups entries by date (first by year, then by month), and adds
header markings as needed (e.g. `#`, `##`, etc). If you already have markdown header
markings in your journal, they will be incremented as necessary to make them fit under
these new headers (i.e. `#` will become `##`).
This format can be very useful, for example, to export a journal to a program that
converts markdown to html to make a website or a blog from your journal.
**Example output**:
``` markdown
# 2020
## June
### 2020-06-28 18:22 This is the first sample entry
This is the sample body text of the first sample entry.
## July
### 2020-07-01 20:00 This is the second sample entry
This is the sample body text of the second sample entry, but this one has a @tag.
### 2020-07-02 09:00 This is the third sample entry
This is the sample body text of the third sample entry.
```
### Plain Text
``` sh
jrnl --format text
# or
jrnl --format txt
```
This outputs your journal in the same plain-text format that `jrnl` uses to store your
journal on disk. This format is particularly useful for importing and exporting journals
within `jrnl`.
You can use it, for example, to move entries from one journal to another, or to create a
new journal with search results from another journal.
**Example output**:
``` sh
[2020-06-28 18:22] This is the first sample entry
This is the sample body text of the first sample entry.
[2020-07-01 20:00] This is the second sample entry
This is the sample body text of the second sample entry, but this one has a @tag.
[2020-07-02 09:00] This is the third sample entry
This is the sample body text of the third sample entry.
```
### XML
``` sh
jrnl --format xml
```
This outputs your journal into XML format. XML is a commonly used data format and is
supported by many programs and programming languages.
**Example output**:
``` xml
<?xml version="1.0" ?>
<journal>
<entries>
<entry date="2020-06-28T18:22:00" starred="">This is the first sample entry This is the sample body text of the first sample entry.</entry>
<entry date="2020-07-01T20:00:00" starred="">
<tag name="@tag"/>
This is the second sample entry This is the sample body text of the second sample entry, but this one has a @tag.
</entry>
<entry date="2020-07-02T09:00:00" starred="">*This is the third sample entry, and is starred This is the sample body text of the third sample entry.</entry>
</entries>
<tags>
<tag name="@tag">1</tag>
</tags>
</journal>
```
### YAML
``` sh
jrnl --format yaml
```
This outputs your journal into YAML format. YAML is a commonly used data format and is
supported by many programs and programming languages.
**Example output**:
``` yaml
title: This is the second sample entry
date: 2020-07-01 20:00
starred: False
tags: tag
This is the sample body text of the second sample entry, but this one has a @tag.
```
## Report formats
Since formats use your journal data and display it in different ways, they can also be
used to create reports.
### Tags
``` sh
jrnl --format tags
# or
jrnl --tags
```
This format is a simple example of how formats can be used to create reports. It
displays each tag, and a count of how many entries in which tag appears in your journal
(or in the search results), sorted by most frequent.
Example output:
``` sh
@one : 32
@two : 17
@three : 4
```
## Options
### Exporting with `--file`
Example: `jrnl --format json --file /some/path/to/a/file.txt`
By default, `jrnl` will output entries to your terminal. But if you provide `--file`
along with a filename, the same output that would have been to your terminal will be
written to the file instead. This is the same as piping the output to a file.
So, in bash for example, the following two statements are equivalent:
``` sh
jrnl --format json --file myjournal.json
```
``` sh
jrnl --format json > myjournal.json
```
#### Exporting to directories
If the `--file` argument is a directory, jrnl will export each entry into an individual file:
``` sh
jrnl --format json --file my_entries/
```
The contents of `my_entries/` will then look like this:
``` output
my_entries/
|- 2013_06_03_a-beautiful-day.json
|- 2013_06_07_dinner-with-gabriel.json
|- ...
```
|