jrnl Documentation

Collect your thoughts and notes without leaving the command line.

7,349 stars Python Python 14 files · ~42,673 tokens #cli#command-line#encrypted#journal#journal-application#jrnl#note-taking#notes
RAW Doc

File: README.md

jrnl [](https://github.com/jrnl-org/jrnl/actions?query=workflow%3ATesting) [](https://pepy.tech/project/jrnl) [](https://pypi.python.org/pypi/jrnl/) [](https://formulae.brew.sh/formula/jrnl) [](https://gitter.im/jrnl-org/jrnl) [](https://github.com/jrnl-org/jrnl/blob/main/CHANGELOG.md)

To get help, submit an issue on
GitHub.

jrnl is a simple journal application for the command line.

You can use it to easily create, search, and view journal entries. Journals are
stored as human-readable plain text, and can also be encrypted using AES
encryption.

In a Nutshell

To make a new entry, just enter

sh
jrnl yesterday: Called in sick. Used the time to clean the house and write my
book.

yesterday: is interpreted by jrnl as a timestamp. Everything until the
first sentence ending (either ., ?, or !) is interpreted as the title, and
the rest as the body. In your journal file, the result will look like this:

text
[2012-03-29 09:00] Called in sick.
Used the time to clean the house and write my book.

If you just call jrnl, you will be prompted to compose your entry - but you
can also configure jrnl to use your external editor.

For more information, please read the
documentation.

Contributors

Maintainers

Our maintainers help keep the lights on for the project:

Please thank them if you like jrnl!

Code Contributors

This project is made with love by the many fabulous people who have contributed.
jrnl couldn't exist without each and every one of you!

If you'd also like to help make jrnl better, please see our contributing
documentation.

Financial Backers

Another way show support is through direct financial contributions. These funds
go to covering our costs, and are a quick way to show your appreciation for
jrnl.

Become a financial contributor
and help us sustain our community.

File: CLAUDE.md

CLAUDE.md

IMPORTANT: ALWAYS prefer contributing to the main branch with a PR.

Project Overview

jrnl is a command-line journal application written in Python. It supports plain text and encrypted (AES) journals, multiple journal types, and various export formats. The main branch for development is main

Development Setup

bash
pipx install poetry
poetry install
poetry shell  # activate virtualenv

Common Commands

bash
# Run full lint + test suite
poetry run poe test

# Run tests only (no linting)
poetry run poe test-run

# Run a single test file
poetry run pytest tests/unit/test_config_file.py

# Run a single BDD scenario by name (all BDD tests are in test_features.py)
poetry run pytest tests/bdd/test_features.py -k "test_scenario_name"

# Run a single test by name
poetry run pytest -k "test_name" -x

# Linting only
poetry run poe lint

# Auto-format code
poetry run poe format

# Serve docs locally at localhost:8000
poetry run poe docs-run

Tests run in parallel by default (-n=auto via pytest-xdist). To disable for debugging: poetry run pytest -n0 -x.

Architecture

Control Flow

Entry point: jrnl/main.py:run() → jrnl/controller.py:run()

The controller has a two-phase command model:

  1. Preconfig commands (no config needed): --help, --version, --diagnostic
  2. Postconfig commands (need config): --encrypt, --decrypt, --import, --list
  3. Then either append mode (writing entries) or search mode (querying/filtering)
  4. Search results can have actions applied: --edit, --delete, --change-time

CLI argument parsing is in jrnl/args.py (argparse-based).

Journal Types (`jrnl/journals/`)

  • Journal — base class, single-file storage, supports encryption
  • FolderJournal — entries stored as individual files in year/month/day structure
  • DayOneJournal — reads macOS Day One .doentry plist files

Factory: open_journal() in jrnl/journals/__init__.py selects type from config.

Encryption (`jrnl/encryption/`)

  • BaseEncryption (abstract) → NoEncryption, BasePasswordEncryption
  • BasePasswordEncryption → Jrnlv1Encryption (legacy), Jrnlv2Encryption (current)
  • determine_encryption_method() factory maps config values to classes

Plugins (`jrnl/plugins/`)

Exporters: Text, Markdown, JSON, YAML, XML, Fancy, Tags, Dates, Calendar Heatmap. One importer: JRNL (native format). Plugin lookup via get_exporter(format) / get_importer(format).

Git Integration (`jrnl/git.py`)

Auto-commit, auto-pull, and auto-push are configurable per journal. git_auto_commit() initializes repos, stages changes, and commits. git_pull() uses fetch + fast-forward.

Config (`jrnl/config.py`)

YAML-based config with per-journal overrides. Journals can be a string (path) or dict (path + overrides). CLI args override config via apply_overrides().

Testing

  • BDD tests: tests/bdd/features/*.feature files using pytest-bdd. Step implementations in tests/lib/ (given_steps.py, when_steps.py, then_steps.py, fixtures.py).
  • Unit tests: tests/unit/test_*.py
  • OS-specific markers: @skip_win, @skip_posix, @on_win, @on_posix
  • CI tests across Python 3.11–3.14 on Linux, macOS, and Windows

Never Touch Real User Config/Journals

jrnl.config.save_config() (and anything that calls it, e.g. install.upgrade_config()) writes to the real ~/.config/jrnl/jrnl.yaml by default when no alt_config_path is given. Do not run ad-hoc reproduction snippets (python -c "...", scratch scripts) against functions in this codebase that touch config/journal paths — they can silently overwrite the user's actual jrnl config or journal files. Always reproduce bugs through the existing test infrastructure instead:

  • BDD: add/run a scenario in tests/bdd/features/*.feature against a fixture config in tests/data/configs/
  • Unit: use tmp_path / existing fixtures in tests/unit/, never a bare path that resolves to get_config_path()

If a one-off script is unavoidable, pass an explicit alt_config_path pointed at a file under the scratchpad/tmp directory, never leave it to default.

Code Style

  • Formatter: black (line length 88)
  • Linter: ruff (target Python 3.11)
  • Import sorting: ruff with isort rules, force single-line imports
  • Build system: poetry-core

File: CODE_OF_CONDUCT.md

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

  • Demonstrating empathy and kindness toward other people
  • Being respectful of differing opinions, viewpoints, and experiences
  • Giving and gracefully accepting constructive feedback
  • Accepting responsibility and apologizing to those affected by our mistakes,
    and learning from the experience
  • Focusing on what is best not just for us as individuals, but for the
    overall community

Examples of unacceptable behavior include:

  • The use of sexualized language or imagery, and sexual attention or
    advances of any kind
  • Trolling, insulting or derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or email
    address, without their explicit permission
  • Other conduct which could reasonably be considered inappropriate in a
    professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by emailing the maintainers.
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series
of actions.

Consequence: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including
sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within
the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant,
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct
enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

File: CONTRIBUTING.md

Contributing

See "Contributing" in the docs directory.

File: issue_template.md

Stop

Please don't file a blank issue.

Fill out one of the templates from the link below and we'll be better able to
help you.

https://github.com/jrnl-org/jrnl/issues/new/choose

File: LICENSE.md

GNU GENERAL PUBLIC LICENSE

Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc.
https://fsf.org/

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Preamble

The GNU General Public License is a free, copyleft license for
software and other kinds of works.

The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom
to share and change all versions of a program--to make sure it remains
free software for all its users. We, the Free Software Foundation, use
the GNU General Public License for most of our software; it applies
also to any other work released this way by its authors. You can apply
it to your programs, too.

When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.

To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you
have certain responsibilities if you distribute copies of the
software, or if you modify it: responsibilities to respect the freedom
of others.

For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.

Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.

For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.

Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the
manufacturer can do so. This is fundamentally incompatible with the
aim of protecting users' freedom to change the software. The
systematic pattern of such abuse occurs in the area of products for
individuals to use, which is precisely where it is most unacceptable.
Therefore, we have designed this version of the GPL to prohibit the
practice for those products. If such problems arise substantially in
other domains, we stand ready to extend this provision to those
domains in future versions of the GPL, as needed to protect the
freedom of users.

Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish
to avoid the special danger that patents applied to a free program
could make it effectively proprietary. To prevent this, the GPL
assures that patents cannot be used to render the program non-free.

The precise terms and conditions for copying, distribution and
modification follow.

TERMS AND CONDITIONS

0. Definitions.

"This License" refers to version 3 of the GNU General Public License.

"Copyright" also means copyright-like laws that apply to other kinds
of works, such as semiconductor masks.

"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.

To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of
an exact copy. The resulting work is called a "modified version" of
the earlier work or a work "based on" the earlier work.

A "covered work" means either the unmodified Program or a work based
on the Program.

To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.

To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user
through a computer network, with no transfer of a copy, is not
conveying.

An interactive user interface displays "Appropriate Legal Notices" to
the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.

1. Source Code.

The "source code" for a work means the preferred form of the work for
making modifications to it. "Object code" means any non-source form of
a work.

A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.

The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.

The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.

The Corresponding Source need not include anything that users can
regenerate automatically from other parts of the Corresponding Source.

The Corresponding Source for a work in source code form is that same
work.

2. Basic Permissions.

All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.

You may make, run and propagate covered works that you do not convey,
without conditions so long as your license otherwise remains in force.
You may convey covered works to others for the sole purpose of having
them make modifications exclusively for you, or provide you with
facilities for running those works, provided that you comply with the
terms of this License in conveying all material for which you do not
control copyright. Those thus making or running the covered works for
you must do so exclusively on your behalf, under your direction and
control, on terms that prohibit them from making any copies of your
copyrighted material outside their relationship with you.

Conveying under any other circumstances is permitted solely under the
conditions stated below. Sublicensing is not allowed; section 10 makes
it unnecessary.

No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.

When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such
circumvention is effected by exercising rights under this License with
respect to the covered work, and you disclaim any intention to limit
operation or modification of the work as a means of enforcing, against
the work's users, your or third parties' legal rights to forbid
circumvention of technological measures.

4. Conveying Verbatim Copies.

You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.

You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.

5. Conveying Modified Source Versions.

You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these
conditions:

  • a) The work must carry prominent notices stating that you modified
    it, and giving a relevant date.
  • b) The work must carry prominent notices stating that it is
    released under this License and any conditions added under
    section 7. This requirement modifies the requirement in section 4
    to "keep intact all notices".
  • c) You must license the entire work, as a whole, under this
    License to anyone who comes into possession of a copy. This
    License will therefore apply, along with any applicable section 7
    additional terms, to the whole of the work, and all its parts,
    regardless of how they are packaged. This License gives no
    permission to license the work in any other way, but it does not
    invalidate such permission if you have separately received it.
  • d) If the work has interactive user interfaces, each must display
    Appropriate Legal Notices; however, if the Program has interactive
    interfaces that do not display Appropriate Legal Notices, your
    work need not make them do so.

A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.

6. Conveying Non-Source Forms.

You may convey a covered work in object code form under the terms of
sections 4 and 5, provided that you also convey the machine-readable
Corresponding Source under the terms of this License, in one of these
ways:

  • a) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by the
    Corresponding Source fixed on a durable physical medium
    customarily used for software interchange.
  • b) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by a
    written offer, valid for at least three years and valid for as
    long as you offer spare parts or customer support for that product
    model, to give anyone who possesses the object code either (1) a
    copy of the Corresponding Source for all the software in the
    product that is covered by this License, on a durable physical
    medium customarily used for software interchange, for a price no
    more than your reasonable cost of physically performing this
    conveying of source, or (2) access to copy the Corresponding
    Source from a network server at no charge.
  • c) Convey individual copies of the object code with a copy of the
    written offer to provide the Corresponding Source. This
    alternative is allowed only occasionally and noncommercially, and
    only if you received the object code with such an offer, in accord
    with subsection 6b.
  • d) Convey the object code by offering access from a designated
    place (gratis or for a charge), and offer equivalent access to the
    Corresponding Source in the same way through the same place at no
    further charge. You need not require recipients to copy the
    Corresponding Source along with the object code. If the place to
    copy the object code is a network server, the Corresponding Source
    may be on a different server (operated by you or a third party)
    that supports equivalent copying facilities, provided you maintain
    clear directions next to the object code saying where to find the
    Corresponding Source. Regardless of what server hosts the
    Corresponding Source, you remain obligated to ensure that it is
    available for as long as needed to satisfy these requirements.
  • e) Convey the object code using peer-to-peer transmission,
    provided you inform other peers where the object code and
    Corresponding Source of the work are being offered to the general
    public at no charge under subsection 6d.

A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.

A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal,
family, or household purposes, or (2) anything designed or sold for
incorporation into a dwelling. In determining whether a product is a
consumer product, doubtful cases shall be resolved in favor of
coverage. For a particular product received by a particular user,
"normally used" refers to a typical or common use of that class of
product, regardless of the status of the particular user or of the way
in which the particular user actually uses, or expects or is expected
to use, the product. A product is a consumer product regardless of
whether the product has substantial commercial, industrial or
non-consumer uses, unless such uses represent the only significant
mode of use of the product.

"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to
install and execute modified versions of a covered work in that User
Product from a modified version of its Corresponding Source. The
information must suffice to ensure that the continued functioning of
the modified object code is in no case prevented or interfered with
solely because modification has been made.

If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).

The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or
updates for a work that has been modified or installed by the
recipient, or for the User Product in which it has been modified or
installed. Access to a network may be denied when the modification
itself materially and adversely affects the operation of the network
or violates the rules and protocols for communication across the
network.

Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.

7. Additional Terms.

"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.

When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.

Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders
of that material) supplement the terms of this License with terms:

  • a) Disclaiming warranty or limiting liability differently from the
    terms of sections 15 and 16 of this License; or
  • b) Requiring preservation of specified reasonable legal notices or
    author attributions in that material or in the Appropriate Legal
    Notices displayed by works containing it; or
  • c) Prohibiting misrepresentation of the origin of that material,
    or requiring that modified versions of such material be marked in
    reasonable ways as different from the original version; or
  • d) Limiting the use for publicity purposes of names of licensors
    or authors of the material; or
  • e) Declining to grant rights under trademark law for use of some
    trade names, trademarks, or service marks; or
  • f) Requiring indemnification of licensors and authors of that
    material by anyone who conveys the material (or modified versions
    of it) with contractual assumptions of liability to the recipient,
    for any liability that these contractual assumptions directly
    impose on those licensors and authors.

All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.

If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.

Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions; the
above requirements apply either way.

8. Termination.

You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).

However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.

Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.

Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.

9. Acceptance Not Required for Having Copies.

You are not required to accept this License in order to receive or run
a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.

10. Automatic Licensing of Downstream Recipients.

Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.

An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.

You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.

11. Patents.

A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".

A contributor's "essential patent claims" are all patent claims owned
or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.

Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.

In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.

If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.

If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.

A patent license is "discriminatory" if it does not include within the
scope of its coverage, prohibits the exercise of, or is conditioned on
the non-exercise of one or more of the rights that are specifically
granted under this License. You may not convey a covered work if you
are a party to an arrangement with a third party that is in the
business of distributing software, under which you make payment to the
third party based on the extent of your activity of conveying the
work, and under which the third party grants, to any of the parties
who would receive the covered work from you, a discriminatory patent
license (a) in connection with copies of the covered work conveyed by
you (or copies made from those copies), or (b) primarily for and in
connection with specific products or compilations that contain the
covered work, unless you entered into that arrangement, or that patent
license was granted, prior to 28 March 2007.

Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.

12. No Surrender of Others' Freedom.

If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under
this License and any other pertinent obligations, then as a
consequence you may not convey it at all. For example, if you agree to
terms that obligate you to collect a royalty for further conveying
from those to whom you convey the Program, the only way you could
satisfy both those terms and this License would be to refrain entirely
from conveying the Program.

13. Use with the GNU Affero General Public License.

Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.

14. Revised Versions of this License.

The Free Software Foundation may publish revised and/or new versions
of the GNU General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in
detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program
specifies that a certain numbered version of the GNU General Public
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that numbered version or
of any later version published by the Free Software Foundation. If the
Program does not specify a version number of the GNU General Public
License, you may choose any version ever published by the Free
Software Foundation.

If the Program specifies that a proxy can decide which future versions
of the GNU General Public License can be used, that proxy's public
statement of acceptance of a version permanently authorizes you to
choose that version for the Program.

Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.

15. Disclaimer of Warranty.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.

16. Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

17. Interpretation of Sections 15 and 16.

If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

To do so, attach the following notices to the program. It is safest to
attach them to the start of each source file to most effectively state
the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.

text
<one line to give the program's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.

Also add information on how to contact you by electronic and paper
mail.

If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:

text
Copyright (C) <year>  <name of author>
    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License. Of course, your
program's commands might be different; for a GUI interface, you would
use an "about box".

You should also get your employer (if you work as a programmer) or
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. For more information on this, and how to apply and follow
the GNU GPL, see https://www.gnu.org/licenses/.

The GNU General Public License does not permit incorporating your
program into proprietary programs. If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use the
GNU Lesser General Public License instead of this License. But first,
please read https://www.gnu.org/licenses/why-not-lgpl.html.

File: mkdocs.yml

site_name: jrnl
site_url: https://jrnl.sh
theme:
name: readthedocs
custom_dir: docs_theme
static_templates:
- index.html
watch:

  • docs
  • docs_theme
    extra_css:
  • admonition
    repo_url: https://github.com/jrnl-org/jrnl/
    edit_uri: edit/main/docs/
    site_author: jrnl contributors
    site_description: Collect your thoughts and notes without leaving the command line.
    nav:
  • Overview: overview.md
  • 'User Guide':
    • Quickstart: installation.md
    • Basic Usage: usage.md
    • Encryption: encryption.md
    • Journal Types: journal-types.md
    • Privacy and Security: privacy-and-security.md
    • Formats: formats.md
    • Advanced Usage: advanced.md
    • 'External Editors': external-editors.md
    • 'Tips and Tricks': tips-and-tricks.md
  • 'Reference':
    • Command Line: reference-command-line.md
    • Configuration File: reference-config-file.md
  • 'Contributing':
    • Contributing to jrnl: contributing.md

File: package.json

{
"devDependencies": {
"pa11y-ci": "4.0.0"
}
}

File: SECURITY.md

Security

If you've discovered a potential security issue in jrnl, please contact the maintainers at [email protected].

You can also feel free to open an issue (but please don't disclose the vulnerability) in case the email goes to spam.

You can find known privacy and security issues in our documentation.

File: .readthedocs.yaml

readthedocs.yml

Read the Docs configuration file

See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

Required

version: 2

Set the OS

build:
os: ubuntu-22.04
tools:
python: "3"

Build documentation in the docs/ directory

mkdocs:
configuration: mkdocs.yml
fail_on_warning: false

Optionally build your docs in additional formats such as PDF

formats:

  • pdf
  • epub

Optionally set the version of Python and requirements required to build your docs

python:
install:
- requirements: docs_theme/requirements.txt

File: docs/advanced.md

Advanced Usage

Configuration File

jrnl has a wide variety of options that can be customized through the config file,
including templates, formats, multiple journals, and more. See
the configuration file reference for details
or read on for some common use cases.

Multiple journal files

You can configure jrnlto use with multiple journals (eg.
private and work) by defining more journals in your config file,
for example:

yaml
journals:
  default: ~/journal.txt
  work: ~/work.txt

The default journal gets created the first time you start jrnl
Now you can access the work journal by using jrnl work instead of
jrnl, eg.

sh
jrnl work at 10am: Meeting with @Steve
jrnl work -n 3

will both use ~/work.txt, while jrnl -n 3 will display the last
three entries from ~/journal.txt (and so does jrnl default -n 3).

You can also override the default options for each individual journal.
If your jrnl.yaml looks like this:

yaml
encrypt: false
journals:
  default: ~/journal.txt
  work:
    journal: ~/work.txt
    encrypt: true
  food: ~/my_recipes.txt

Your default and your food journals won't be encrypted, however your
work journal will!

You can override all options that are present at
the top level of jrnl.yaml, just make sure that at the very least
you specify a journal: ... key that points to the journal file of
that journal.

Consider the following example configuration

yaml
editor: vi -c startinsert 
journals: 
  default: ~/journal.txt 
  work: 
    journal: ~/work.txt 
    encrypt: true 
    display_format: json 
    editor: code -rw 
  food:
    display_format: markdown 
    journal: ~/recipes.txt

The work journal is encrypted, prints to json by default, and is edited using an existing window of VSCode. Similarly, the food journal prints to markdown by default, but uses all the other defaults.

Modifying Configurations from the Command line

You can override a configuration field for the current instance of jrnl using --config-override CONFIG_KEY CONFIG_VALUE where CONFIG_KEY is a valid configuration field, specified in dot notation and CONFIG_VALUE is the (valid) desired override value. The dot notation can be used to change config keys within other keys, such as colors.title for the title key within the colors key.

You can specify multiple overrides as multiple calls to --config-override.

!!! note
These overrides allow you to modify any field of your jrnl configuration. We trust that you know what you are doing.

Examples:

sh
# Create an entry using the `stdin` prompt, for rapid logging
jrnl --config-override editor ""

# Populate a project's log
jrnl --config-override journals.todo "$(git rev-parse --show-toplevel)/todo.txt" todo find my towel 

# Pass multiple overrides 
jrnl --config-override display_format fancy --config-override linewrap 20 \
--config-override colors.title green

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:

sh
# 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 first run)
jrnl

File: docs/contributing.md

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

Before starting, please read the Code of Conduct.

Reporting Bugs

Please report bugs by opening a new issue 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 with the "Documentation change" type.

To edit the documentation, edit the docs/*.md files on the main branch. You can see the result by running poe docs-run inside the project's root directory, then navigating your browser to localhost:8000.

External editors and tips and tricks

If you'd like to share a jrnl command line trick that you find useful, you may find it worthwhile to add it to the "Tips and Tricks" section. For advice on how to integrate a particular external editor, you can add to the "External Editors" section.

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. You can use pipx to fetch them and test them. See the changelog 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, 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 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 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. 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 to develop jrnl. It will take care of all of the project's other dependencies.

Understanding the branches

jrnl uses two primary branches:

  • main - for ongoing development
  • release - for releases

In general, pull requests should be made on the main branch.

Updating an existing clone after the `develop` → `main` rename

If you have a clone from before the default branch was renamed from develop to main, update it with:

bash
git checkout develop
git branch -m develop main
git fetch origin
git remote prune origin
git branch -u origin/main main
git remote set-head origin -a

If you have other local branches based on develop, rebase them onto main:

bash
git rebase --onto main develop <your-branch>

Common development commands

You can find an inventory of commands in the pyproject.toml. Users can run the commands by typing poe followed by the name of the command (Poe the Poet can be installed on its own, or as part of poetry install).

A typical development workflow includes:

  • Installing dependencies:
    • poetry install
  • Activate virtual environment:
    • poetry shell
  • Running the source in a virtual environment:
    • jrnl (with or without arguments as necessary)
  • Running tests:
    • poe test
  • Formatting the code to standardize its style:
    • poe format

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 for unit tests, and pytest-bdd 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 by label for things to work on. Here are some labels worth searching:

You can also get a feel for the project's priorities by reviewing the 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!

File: docs/encryption.md

Encryption

A Note on Security

While jrnl follows best practices, total security is never possible in the
real world. There are a number of ways that people can at least partially
compromise your jrnl data. See the Privacy and Security page
for more information.

There is one relevant security advisory for encryption-related security issues: GHSA-rhx6-37mm-5q9r.

Encryption Behavior Overview

  • Encrypted journals are now written in the jrnl v3 format.
  • jrnl v1 and v2 encrypted files are read-only formats. They can still be opened and decrypted, but new encrypted writes are always v3.

jrnl v3 Encrypted File Format

jrnl v3 uses a random 16-byte salt per encrypted write, stored in a JSON
header after a magic prefix. This avoids the static-salt weakness from v2.

File layout:

Field Size Description
JRNLv3 6 bytes Magic prefix
header_len 2 bytes (uint16 BE) Length of the header field, max 64KB
header header_len bytes Base64-encoded JSON, includes salt (base64url-encoded 16-byte salt)
Fernet token Remaining bytes Ciphertext

Additional header fields may be added in future without changing the format version.

!!! note
Journals encrypted with v3 before this format was base64-encoded store
raw JSON in the header field instead. These are still read correctly;
the base64-encoded format is written on the next save.

Encrypting and Decrypting from the CLI

To encrypt a journal, run:

sh
jrnl --encrypt [FILENAME]

You can then enter a new password, and the unencrypted file will replaced with
the new encrypted file.

This command also works to change the password for a journal file that is
already encrypted. jrnl will prompt you for the current password and then new
password.

Conversely, run this to decrypt a journal:

sh
jrnl --decrypt [FILENAME]

replaces the encrypted journal file with a plain text file. You can also specify
a filename, e.g., jrnl --decrypt plain_text_copy.txt, to leave the original
encrypted file untouched and create a new plain text file next to it.

!!! note
Changing encrypt in your config file to
a different value will not encrypt or decrypt your
journal file. It merely says whether or not your journal
is encrypted. Hence manually changing
this option will most likely result in your journal file being
impossible to load. This is why the above commands are necessary.

Storing Passwords in Your Keychain

Nobody can recover or reset your jrnl password. If you lose it,
your data will be inaccessible forever.

For this reason, when encrypting a journal, jrnl asks whether you would like
to store the password in your system's keychain. An added benefit is that you
will not need to enter the password when interacting with the journal file.

If you don't initially store the password in your keychain but decide to do so
later---or if you want to store it in one computer's keychain but not in another
computer's---you can run jrnl --encrypt on an encrypted journal and use the
same password again. This will trigger the keychain storage prompt.

Manual Decryption

The easiest way to decrypt your journal is with jrnl --decrypt, but you could
also decrypt your journal manually if needed. To do this, you can use any
program that supports the AES algorithm (specifically AES-CBC), and you'll need
the following relevant information for decryption:

  • Key: The key used for encryption is the
    SHA-256 hash of your password.
  • Initialization vector (IV): The IV is stored in the first 16 bytes of
    your encrypted journal file.
  • The actual text of the journal (everything after the first 16 bytes in
    the encrypted journal file) is encoded in
    UTF-8 and padded according to
    PKCS#7 before being encrypted.

If you'd like an example of what this might look like in script form, please
see below for some examples of Python scripts that you could use to manually
decrypt your journal.

!!! note
These are only examples, and are only here to illustrate that your journal files
will still be recoverable even if jrnl isn't around anymore. Please use
jrnl --decrypt if available.

Example for jrnl v2 files:

python
#!/usr/bin/env python3
"""
Decrypt a jrnl v2 encrypted journal.

Note: the `cryptography` module must be installed (you can do this with
something like `pip3 install crytography`)
"""

import base64
import getpass
from pathlib import Path

from cryptography.fernet import Fernet
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC

filepath = input("journal file path: ")
password = getpass.getpass("Password: ")

with open(Path(filepath), "rb") as f:
    ciphertext = f.read()

password = password.encode("utf-8")
kdf = PBKDF2HMAC(
    algorithm=hashes.SHA256(),
    length=32,
    salt=b"\xf2\xd5q\x0e\xc1\x8d.\xde\xdc\x8e6t\x89\x04\xce\xf8",
    iterations=100_000,
    backend=default_backend(),
)

key = base64.urlsafe_b64encode(kdf.derive(password))

print(Fernet(key).decrypt(ciphertext).decode("utf-8"))

Example for jrnl v1 files:

python
#!/usr/bin/env python3
"""
Decrypt a jrnl v1 encrypted journal.

Note: the `pycrypto` module must be installed (you can do this with something
like `pip3 install pycrypto`)
"""

import argparse
import getpass
import hashlib

from Crypto.Cipher import AES

parser = argparse.ArgumentParser()
parser.add_argument("filepath", help="journal file to decrypt")
args = parser.parse_args()

pwd = getpass.getpass()
key = hashlib.sha256(pwd.encode("utf-8")).digest()

with open(args.filepath, "rb") as f:
    ciphertext = f.read()

crypto = AES.new(key, AES.MODE_CBC, ciphertext[:16])
plain = crypto.decrypt(ciphertext[16:])
plain = plain.strip(plain[-1:])
plain = plain.decode("utf-8")
print(plain)

File: docs/external-editors.md

External editors

Configure your preferred external editor by updating the editor option
in your configuration file. If your editor is not
in your operating system's PATH environment variable, then you will have to
enter the full path of your editor.

Once it's configured, you can create an entry as a new document in your editor using the jrnl
command by itself:

text
jrnl

You can specify the time and title of the entry as usual on the first line of the document.

If you want, you can skip the editor by including a quick entry with the jrnl command:

text
jrnl yesterday: All my troubles seemed so far away.

If you want to start the entry on the command line and continue writing in your chosen editor,
use the --edit flag. For example:

text
jrnl yesterday: All my troubles seemed so far away. --edit

!!! note
To save and log any entry edits, save and close the file.

All editors must be blocking processes to work with jrnl. Some editors, such as micro, are blocking by default, though others can be made to block with additional arguments, such as many of those documented below. If jrnl opens your editor but finishes running immediately, then your editor is not a blocking process, and you may be able to correct that with one of the suggestions below.

Please see this section about how
your editor might leak sensitive information and how to mitigate that risk.

Sublime Text

To use Sublime Text, install the command line
tools for Sublime Text and configure your jrnl.yaml like this:

yaml
editor: "subl -w"

Note the -w flag to make sure jrnl waits for Sublime Text to close the
file before writing into the journal.

Visual Studio Code

Visual Studio Code also requires a flag
that tells the process to wait until the file is closed before exiting:

yaml
editor: "code --wait"

On Windows, code is not added to the path by default, so you'll need to
enter the full path to your code.exe file, or add it to the PATH variable.

MacVim

Also similar to Sublime Text, MacVim must be started with a flag that tells
the the process to wait until the file is closed before passing control
back to journal. In the case of MacVim, this is -f:

yaml
editor: "mvim -f"

Vim/Neovim

To use any of the Vim derivatives as editor in Linux, simply set the editor
to the executable:

yaml
editor: "vim"
# or
editor: "nvim"

iA Writer

On OS X, you can use the fabulous iA
Writer to write entries. Configure your
jrnl.yaml like this:

yaml
editor: "open -b pro.writer.mac -Wn"

What does this do? open -b ... opens a file using the application
identified by the bundle identifier (a unique string for every app out
there). -Wn tells the application to wait until it's closed before
passing back control, and to use a new instance of the application.

If the pro.writer.mac bundle identifier is not found on your system,
you can find the right string to use by inspecting iA Writer's
Info.plist file in your shell:

sh
grep -A 1 CFBundleIdentifier /Applications/iA\ Writer.app/Contents/Info.plist

Notepad++ on Windows

To set Notepad++ as your editor, edit
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
its own Notepad++ window.

emacs

To use emacs as your editor, edit the jrnl config file (jrnl.yaml) like this:

yaml
editor: emacsclient -a "" -c

When you're done editing the message, save and C-x # to close the buffer and stop the emacsclient process.

gedit

To use gedit as your editor, edit the jrnl config
file (jrnl.yaml) like this:

yaml
editor: "gedit -w"

The -w (--wait) flag tells gedit to wait until the file is closed before
passing control back to jrnl.

Other editors

If you're using another editor and would like to share, feel free to contribute documentation on it.

File: docs/formats.md

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 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).

!!! note
You may see boxed messages like "2 entries found" when using these formats, but
those messages are written to stderr instead of stdout, and won't be piped when
using the | operator.

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) 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 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 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 --file 'my_directory/'

This outputs your journal into YAML format. YAML is a commonly used data format and is
supported by many programs and programming languages. Exporting to directories is the
only supported YAML export option and each entry will be written to a separate file.

Example file:

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 yaml --file my_entries/

The contents of my_entries/ will then look like this:

output
my_entries/
|- 2013_06_03_a-beautiful-day.yaml
|- 2013_06_07_dinner-with-gabriel.yaml
|- ...

File: docs/installation.md

Getting started

Installation

The easiest way to install jrnl is using
pipx
with Python 3.11+:

sh
pipx install jrnl

!!! tip
Do not use sudo while installing jrnl. This may lead to path issues.

The first time you run jrnl you will be asked where your journal file
should be created and whether you wish to encrypt it.

Quickstart

To make a new entry, just type

text
jrnl yesterday: Called in sick. Used the time to clean, and spent 4h on writing my book.

and hit return. yesterday: will be interpreted as a time stamp.
Everything until the first sentence mark (.?!:) will be interpreted as
the title, the rest as the body. In your journal file, the result will
look like this:

output
2012-03-29 09:00 Called in sick.
Used the time to clean the house and spent 4h on writing my book.

If you just call jrnl, you will be prompted to compose your entry -
but you can also configure jrnl to use your external editor.

File: docs/journal-types.md

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,
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.
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
Creating a new folder journal can be done in two ways:

  • Create a folder with the name of the journal 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.
  • Create a new journal in your config_file and end the path with a / (on a POSIX system like Linux or MacOSX) or a \ (on a Windows system). The folder will be created automatically if it doesn't exist.

!!! 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.

!!! 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
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:

text
jrnl projects --format txt | jrnl new --import

File: docs/overview.md

Overview

jrnl is a simple journal application for the command line.

You can use it to easily create, search, and view journal entries. Journals are
stored as human-readable plain text, and can also be encrypted using AES
encryption.

jrnl has most of the features you need, and few of the ones you don't.

Plain Text

jrnl stores each journal in plain text. You can store jrnl files anywhere,
including in shared folders to keep them synchronized between devices. Journal
files are compact (thousands of entries take up less than 1 MiB) and can be read
by almost any electronic device, now and for the foreseeable future.

Tags

To make it easier to find entries later, jrnl includes support for inline tags
(the default tag symbol is @). You can find and filter entries by using tags
along with other search criteria.

Support for Multiple Journals

jrnl includes support for the creation of multiple journals, each of which
can be stored as a single file or as a set of files. Entries are automatically
timestamped in a human-readable format that makes it easy to view multiple
entries at a time. jrnl can easily find the entries you want so that you can
read them or edit them.

Support for External Editors

jrnl plays nicely with your favorite text editor. You may prefer to write
journal entries in an editor. Or you may want to make changes that require a
more comprehensive application. jrnl can filter specific entries and pass them
to the external editor of your choice.

Encryption

jrnl includes support for AES
encryption. See the
encryption page for more information.

Import and Export

jrnl makes it easy to import entries from other sources. Existing entries can
be exported in a variety of formats.

Multi-Platform Support

jrnl is compatible with most operating systems. You can download it using one
of a variety of package managers, or you can build from source.

Open-Source

jrnl is written in Python and maintained by a
friendly community of open-source software
enthusiasts.

File: docs/privacy-and-security.md

Privacy and Security

jrnl is designed with privacy and security in mind, but like any other
program there are some limitations to be aware of.

Password strength

jrnl doesn't enforce password strength requirements. Short or commonly-used
passwords can be easily circumvented by someone with basic security skills
to access to your encrypted jrnl file.

Plausible deniability

You may be able to hide the contents of your journal behind a layer of encryption,
but if someone has access to your configuration file, then they can figure out that
you have a journal, where that journal file is, and when you last edited it.
With a sufficient power imbalance, someone may be able to force you to unencrypt
it through non-technical means.

Spying

While jrnl can protect against unauthorized access to your journal entries while
it isn't open, it cannot protect you against an unsafe computer/location.
For example:

  • Someone installs a keylogger, tracking what you type into your journal.
  • Someone watches your screen while you write your entry.
  • Someone installs a backdoor into jrnl or poisons your journal into revealing your entries.

Saved Passwords

When creating an encrypted journal, you'll be prompted as to whether or not you
want to "store the password in your keychain." This keychain is accessed using
the Python keyring library, which has different
behavior depending on your operating system.

In Windows, the keychain is the Windows Credential Manager (WCM), which can't be locked
and can be accessed by any other application running under your username. If this is
a concern for you, you may not want to store your password.

Shell history

Since you can enter entries from the command line, any tool that logs command
line actions is a potential security risk. See below for how to deal with this
problem in various shells.

bash

You can disable history logging for jrnl by adding this line into your
~/.bashrc file:

sh
HISTIGNORE="$HISTIGNORE:jrnl *"

To delete existing jrnl commands from bash history, simply delete them from
your bash history file. The default location of this file is ~/.bash_history,
but you can run echo "$HISTFILE" to find it if needed. Also, you can run
history -c to delete all commands from your history.

zsh

You can disable history logging for jrnl by adding this to your ~/.zshrc
file:

sh
setopt HIST_IGNORE_SPACE
alias jrnl=" jrnl"

To delete existing jrnl commands from zsh history, simply remove them from
your zsh history file. The default location of this file is ~/.zsh_history,
but you can run echo "$HISTFILE" to find it if needed. Also, you can run
history -c to delete all commands from your history.

fish

By default fish will not log any command that starts with a space. If you
want to always run jrnl with a space before it, then you can add this to your
~/.config/fish/config.fish file:

sh
abbr --add jrnl " jrnl"

To delete existing jrnl commands from fish history, run history delete --prefix 'jrnl '.

Windows Command Prompt

Windows doesn't log history to disk, but it does keep it in your command prompt
session. Close the command prompt or press Alt+F7 to clear your history
after journaling.

Files in transit from editor to jrnl

When creating or editing an entry, jrnl uses a unencrypted temporary file on
disk in order to give your editor access to your journal. After you close your
editor, jrnl then deletes this temporary file.

So, if you have saved a journal entry but haven't closed your editor yet, the
unencrypted temporary remains on your disk. If your computer were to shut off
during this time, or the jrnl process were killed unexpectedly, then the
unencrypted temporary file will remain on your disk. You can mitigate this
issue by only saving with your editor right before closing it. You can also
manually delete these files from your temporary folder. By default, they
are named jrnl*.jrnl, but if you use a
template, they will have the same
extension as the template.

Editor history

Some editors keep usage history stored on disk for future use. This can be a
security risk in the sense that sensitive information can leak via recent
search patterns or editor commands.

Visual Studio Code

Visual Studio Code stores the contents of saved files to allow you to restore or
review the contents later. You can disable this feature for all files by unchecking
the workbench.localHistory.enabled setting in the
Settings editor.

Alternatively, you can disable this feature for specific files by configuring a
pattern
in the workbench.localHistory.exclude setting. To exclude unencrypted temporary files generated
by jrnl, you can set the **/jrnl*.jrnl (unless you are using a
template) pattern for the workbench.localHistory.exclude setting
in the Settings editor.

!!! note
On Windows, the history location is typically found at
%APPDATA%\Code\User\History.

Visual Studio Code also creates a copy of all unsaved files that are open.
It stores these copies in a backup location that's automatically cleaned when
you save the file. However, if your computer shuts off before you save the file,
or the Visual Studio Code process stops unexpectedly, then an unencrypted
temporary file may remain on your disk. You can manually delete these files
from the backup location.

!!! note
On Windows, the backup location is typically found at
%APPDATA%\Code\Backups.

Vim

Vim stores progress data in a so called Viminfo file located at ~/.viminfo
which contains all sorts of user data including command line history, search
string history, search/substitute patterns, contents of register etc. Also to
be able to recover opened files after an unexpected application close Vim uses
swap files.

These options as well as other leaky features can be disabled by setting the
editor key in the Jrnl settings like this:

yaml
editor: "vim -c 'set viminfo= noswapfile noundofile nobackup nowritebackup noshelltemp history=0 nomodeline secure'"

To disable all plugins and custom configurations and start Vim with the default
configuration -u NONE can be passed on the command line as well. This will
ensure that any rogue plugins or other difficult to catch information leaks are
eliminated. The downside to this is that the editor experience will decrease
quite a bit.

To instead let Vim automatically detect when a Jrnl file is being edited an
autocommand can be used. Place this in your ~/.vimrc:

vim
autocmd BufNewFile,BufReadPre *.jrnl setlocal viminfo= noswapfile noundofile nobackup nowritebackup noshelltemp history=0 nomodeline secure

!!! note
If you're using a template, you will
have to use the template's file extension instead of .jrnl.

See :h <option> in Vim for more information about the options mentioned.

Neovim

Neovim strives to be mostly compatible with Vim and has therefore similar
functionality as Vim. One difference in Neovim is that the Viminfo file is
instead called the ShaDa ("shared data") file which resides in
~/.local/state/nvim (~/.local/share/nvim pre Neovim v0.8.0). The ShaDa file
can be disabled in the same way as for Vim.

yaml
editor: "nvim -c 'set shada= noswapfile noundofile nobackup nowritebackup noshelltemp history=0 nomodeline secure'"

-u NONE can be passed here as well to start a session with the default configs.

As for Vim above we can create an autocommand in Vimscript:

vim
autocmd BufNewFile,BufReadPre *.jrnl setlocal shada= noswapfile noundofile nobackup nowritebackup noshelltemp history=0 nomodeline secure

or the same but in Lua:

lua
vim.api.nvim_create_autocmd( {"BufNewFile","BufReadPre" }, {
  group = vim.api.nvim_create_augroup("PrivateJrnl", {}),
  pattern = "*.jrnl",
  callback = function()
    vim.o.shada = ""
    vim.o.swapfile = false
    vim.o.undofile = false
    vim.o.backup = false
    vim.o.writebackup = false
    vim.o.shelltemp = false
    vim.o.history = 0
    vim.o.modeline = false
    vim.o.secure = true
  end,
})

!!! note
If you're using a template, you will
have to use the template's file extension instead of .jrnl.

Please see :h <option> in Neovim for more information about the options mentioned.

Notice any other risks?

Please let the maintainers know by filing an issue on GitHub.

File: docs/reference-command-line.md

Command Line Reference

Synopsis

text
usage: jrnl [--debug] [--help] [--version] [--list] [--encrypt] [--decrypt]
            [--import] [-on DATE] [-today-in-history] [-month DATE]
            [-day DATE] [-year DATE] [-from DATE] [-to DATE] [-contains TEXT]
            [-and] [-starred] [-n [NUMBER]] [-not [TAG]] [--edit] [--delete]
            [--format TYPE] [--tags] [--short]
            [--config-override CONFIG_KEY CONFIG_VALUE]
            [--config-file CONFIG_FILE_PATH]
            [[...]]

Standalone Commands

These commands will exit after they complete. You may only run one at a time.

--help

Show a help message.

--version

Print version and license information.

--list

List the config file location, all configured journals, and their locations.

--encrypt

Encrypt a journal. See encryption for more information.

--decrypt

Decrypt a journal. See encryption for more information.

--import

Import entries from another journal. If any entries have the exact same content
and timestamp, they will be deduplicated.

Optional parameters:

sh
--file FILENAME

Specify a file to import. If not provided, jrnl will use STDIN as the data source.

sh
--format TYPE

Specify the format of the file that is being imported. Defaults to the same data
storage method that jrnl uses. See formats for more information.

Writing new entries

See Basic Usage.

Searching

To find entries from your journal, use any combination of the below filters.
Only entries that match all the filters will be displayed.

When specifying dates, you can use the same kinds of dates you use for new
entries, such as yesterday, today, Tuesday, or 2021-08-01.

Search Argument Description
-on DATE Show entries on this date
-today-in-history Show entries of today over the years
-month DATE Show entries on this month of any year
-day DATE Show entries on this day of any month
-year DATE Show entries of a specific year
-from DATE Show entries after, or on, this date
-to DATE Show entries before, or on, this date (alias: -until)
-contains TEXT Show entries containing specific text (put quotes around text with spaces)
-and Show only entries that match all conditions, like saying "x AND y" (default: OR)
-starred Show only starred entries (marked with *)
-tagged Show only tagged entries (marked with the configured tagsymbols)
-n [NUMBER] Show a maximum of NUMBER entries (note: '-n 3' and '-3' have the same effect)
-not [TAG] Exclude entries with this tag
-not -starred Exclude entries that are starred
-not -tagged Exclude entries that are tagged

Searching Options

These help you do various tasks with the selected entries from your search.
If used on their own (with no search), they will act on your entire journal.

--edit

Opens the selected entries in your configured editor. It will fail if the
editor key is not set in your config file.

Once you begin editing, you can add multiple entries and delete entries
by modifying the text in your editor. When your editor closes, jrnl reads
the temporary file you were editing and makes the changes to your journal.

--delete

Interactively deletes selected entries. You'll be asked to confirm deletion of
each entry.

--change-time DATE

Interactively changes the time of the selected entries to the date specified,
or to right now if no date is specified. You'll be asked to confirm each entry,
unless you are using this with --edit on a single entry.

--format TYPE

Display selected entries in an alternate format. See formats.

Optional parameters

sh
--file FILENAME

Write output to file instead of STDOUT. In most shells, the
same effect can be achieved using >.

--tags

Alias for '--format tags'. Returns a list of all tags and the number of times
they occur within the searched entries. If there are no tags found, jrnl will output a message saying so.

--short

Only shows the date and titles of the searched entries.

Configuration arguments

--config-override CONFIG_KEY CONFIG_VALUE

Override configured key-value pair with CONFIG_KV_PAIR for this command invocation only. To access config keys that aren't at the top level, separate the keys with a dot, such as colors.title to access the title key within the colors key. Read advanced usage for examples.

--config-file CONFIG_FILE_PATH

Use the config file at CONFIG_FILE_PATH for this command invocation only.
Read advanced usage for examples.

Other Arguments

--debug

Prints information useful for troubleshooting while jrnl executes.

--diagnostic

Prints diagnostic information useful for reporting issues.

File: docs/reference-config-file.md

Configuration File Reference

jrnl stores its information in a YAML configuration file.

!!! note
Backup your journal and config file before editing. Changes to the config file
can have destructive effects on your journal!

Config location

You can find your configuration file location by running:
jrnl --list

By default, the configuration file is ~/.config/jrnl/jrnl.yaml.
If you have the XDG_CONFIG_HOME variable set, the configuration
file will be saved as $XDG_CONFIG_HOME/jrnl/jrnl.yaml.

!!! note
On Windows, the configuration file is typically found at
%USERPROFILE%\.config\jrnl\jrnl.yaml.

Config format

The configuration file is a YAML file and can be edited with
a text editor.

Config keys

journals

Describes each journal used by jrnl. Each indented key after this key is
the name of a journal.

If a journal key has a value, that value will be interpreted as the path
to the journal. Otherwise, the journal needs the additional indented key
journal to specify its path.

Example:

yaml
journals:
  default:
    journal: /home/user/journals

All keys below can be specified for each journal at the same level as the
journal key. If a key conflicts with a top-level key, the journal-specific
key will be used instead.

editor

If set, executes this command to launch an external editor for
writing and editing your entries. The path to a temporary file
is passed after it, and jrnl processes the file once
the editor returns control to jrnl.

Some editors require special options to work properly, since they must be
blocking processes to work with jrnl. See External Editors
for details.

encrypt

If true, encrypts your journal using AES. Do not change this
value for journals that already have data in them.

template

The path to a text file to use as a template for new entries. Only works when you
have the editor field configured. If you use a template, the editor's
temporary files
will have the same extension as the template.

tagsymbols

Symbols to be interpreted as tags.

!!! note
Although it seems intuitive to use the #
character for tags, there's a drawback: on most shells, this is
interpreted as a meta-character starting a comment. This means that if
you type

text
> `jrnl Implemented endless scrolling on the #frontend of our website.`

your bash will chop off everything after the `#` before passing it to
  `jrnl`. To avoid this, wrap your input into quotation marks like
  this:

> `jrnl "Implemented endless scrolling on the #frontend of our website."`

Or use the built-in prompt or an external editor to compose your
entries.

default_hour and default_minute

Entries will be created at this time if you supply a date but no specific time (for example, last thursday).

timeformat

Defines how to format the timestamps as they are stored in your journal.
See the python docs for reference.

Do not change this for an existing journal, since that might lead
to data loss.

!!! note
jrnl doesn't support the %z or %Z time zone identifiers.

highlight

If true, tags will be highlighted in cyan.

linewrap

Controls the width of the output. Set to false if you don't want to
wrap long lines. Set to auto to let jrnl automatically determine
the terminal width.

colors

A dictionary that controls the colors used to display journal entries.
It has four subkeys, which are: body, date, tags, and title.

Current valid values are: BLACK, RED, GREEN, YELLOW, BLUE,
MAGENTA, CYAN, WHITE, and NONE.

colorama.Fore is used for colorization, and you can find the docs here.

To disable colored output, set the value to NONE.

display_format

Specifies formatter to use by default. See formats.

version

jrnl automatically updates this field to the version that it is running.
There is no need to change this field manually.

File: docs/tips-and-tricks.md

Tips and Tricks

This page contains tips and tricks for using jrnl, often in conjunction
with other tools, including external editors.

Co-occurrence of tags

If I want to find out how often I mentioned my flatmates Alberto and
Melo in the same entry, I run

sh
jrnl @alberto --tags | grep @melo

And will get something like @melo: 9, meaning there are 9 entries
where both @alberto and @melo are tagged. How does this work? First,
jrnl @alberto will filter the journal to only entries containing the
tag @alberto, and then the --tags option will print out how often
each tag occurred in this filtered journal. Finally, we pipe this to
grep which will only display the line containing @melo.

Combining filters

You can do things like

sh
jrnl @fixed -starred -n 10 -to "jan 2013" --short

To get a short summary of the 10 most recent, favourite entries before
January 1, 2013 that are tagged with @fixed.

Statistics

How much did I write last year?

sh
jrnl -from "jan 1 2013" -to "dec 31 2013" | wc -w

Will give you the number of words you wrote in 2013. How long is my
average entry?

sh
expr $(jrnl --export text | wc -w) / $(jrnl --short | wc -l)

This will first get the total number of words in the journal and divide
it by the number of entries (this works because jrnl --short will
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

sh
echo `stat -f %Sm -t '%d %b %Y at %H:%M: ' entry.txt` `cat entry.txt` | jrnl

The first part will format the modification date of entry.txt, and
then combine it with the contents of the file before piping it to jrnl.
If you do that often, consider creating a function in your .bashrc or
.bash_profile

sh
jrnlimport () {
  echo `stat -f %Sm -t '%d %b %Y at %H:%M: ' $1` `cat $1` | jrnl
}

Using Templates

!!! note
Templates require an external editor be configured.

Templates are text files that are used for creating structured journals.
There are three ways you can use templates:

1. Use the `--template` command line argument and the default $XDG_DATA_HOME/jrnl/templates directory

$XDG_DATA_HOME/jrnl/templates is created by default to store your templates! Create a template (like default.md) in this directory and pass --template FILE_IN_DIR.

sh
jrnl --template default.md

2. Use the `--template` command line argument with a local / absolute path

You can create a template file with any text. Here is an example:

sh
# /tmp/template.txt
My Personal Journal
Title:

Body:

Then, pass the absolute or relative path to the template file as an argument, and your external
editor will open and have your template pre-populated.

sh
jrnl --template /tmp/template.md

3. Set a default template file in `jrnl.yaml`

If you want a template by default, change the value of template in the config file
from false to the template file's path, wrapped in double quotes:

sh
...
template: "/path/to/template.txt"
...

!!! tip
To read your journal entry or to verify the entry saved, you can use this
command: jrnl -n 1 (Check out Formats for more options).

sh
jrnl -n 1

Prompts on shell reload

If you'd like to be prompted each time you refresh your shell, you can include
this in your .bash_profile:

sh
function log_question()
{
   echo $1
   read
   jrnl today: ${1}. $REPLY
}
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
jrnl.yaml config file.

Display random entry

You can use this to select one title at random and then display the whole
entry. The invocation of cut needs to match the format of the timestamp.
For timestamps that have a space between data and time components, select
fields 1 and 2 as shown. For timestamps that have no whitespace, select
only field 1.

sh
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.

bash
jrnl --config-override editor ""

Bind this to a keyboard shortcut.

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 --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 ""
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, which is a less-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 section.

Jump to end of buffer (with vi)

To cause vi to jump to the end of the last line of the entry you edit, in your config file set:

yaml
editor: vi + -c "call cursor('.',strwidth(getline('.')))"

File: docs/usage.md

Basic Usage

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. 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).

For a list of commands, enter jrnl --help.

Composing Entries

Composing mode is entered by either starting jrnl without any arguments --
which will launch an external editor -- or by just writing an entry on the
command line:

text
jrnl today at 3am: I just met Steve Buscemi in a bar! What a nice guy.

!!! note
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.

You can also import an entry directly from a file:

sh
jrnl < my_entry.txt

Specifying Date and Time

If you don't specify a date and time (e.g., jrnl finished writing letter to brother), jrnl will create an entry using the current date and time. For retrospective entries, you can use a timestamp to tell jrnl where to put the entry. Timestamps can be entered using a variety of formats. Here are some that work:

  • at 6am
  • yesterday
  • last monday
  • sunday at noon
  • 2 march 2012
  • 7 apr
  • 5/20/1998 at 23:42
  • 2020-05-22T15:55-04:00

If you don't use a timestamp, jrnl will create an entry using the current
time. If you use a date only (no time), jrnl will use the default time
specified in your configuration file.
Behind the scenes, jrnl reorganizes entries in chronological order.

Using Tags

jrnl supports tags. The default tag symbol is @ (largely because # is a
reserved character). You can specify your own tag symbol in the
configuration file. To use tags, preface the
desired tag with the symbol:

sh
jrnl Had a wonderful day at the @beach with @Tom and @Anna.

Although you can use capitals while tagging an entry, searches by tag are
case-insensitive.

There is no limit to how many tags you can use in an entry.

Similar Tag Warning

When you write an entry, jrnl checks whether any of its tags closely resemble
tags you've used before. If so, it prints a warning:

text
The tag '@works' is similar to: @work

Was this intentional? If not, re-open the entry with 'jrnl --edit' to fix it.

This is just a warning — jrnl will not ask for confirmation or block the
entry from being saved. This is intentional: some similar-looking tags are
perfectly meaningful to keep separate. For example:

  • @health and @wealth — related topics, but distinct goals
  • @friend and @fiend — very different meanings
  • @hiking and @biking — different activities worth tracking separately
  • @learn and @lean — different intentions entirely

If the warning appears and you did make a typo, run jrnl --edit to fix it.

Starring Entries

To mark an entry as a favorite, simply "star" it using an asterisk (*):

sh
jrnl last sunday *: Best day of my life.

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
Make sure that the asterisk (*) is not surrounded by whitespaces.
jrnl Best day of my life! * will not work because the * character has a
special meaning in most shells.

Viewing and Searching Entries

jrnl can display entries in a variety of ways.

To view all entries, enter:

sh
jrnl -to today

jrnl provides several filtering commands, prefaced by a single dash (-), that
allow you to find a more specific range of entries. For example,

sh
jrnl -n 10

lists the ten most recent entries. jrnl -10 is even more concise and works the
same way. If you want to see all of the entries you wrote from the beginning of
last year until the end of this past March, you would enter

sh
jrnl -from "last year" -to march

Filter criteria that use more than one word require surrounding quotes ("").

To see entries on a particular date, use -on:

sh
jrnl -on yesterday

Text Search

The -contains command displays all entries containing the text you enter after it.
This may be helpful when you're searching for entries and you can't remember if you
tagged any words when you wrote them.

You may realize that you use a word a lot and want to turn it into a tag in all
of your previous entries.

sh
jrnl -contains "dogs" --edit

opens your external editor so that you can add a tag symbol (@ by default) to
all instances of the word "dogs."

Filtering by Tag

You can filter your journal entries by tag. For example,

sh
jrnl @pinkie @WorldDomination

displays all entries in which either @pinkie or @WorldDomination
occurred. Tag filters can be combined with other filters:

sh
jrnl -n 5 @pinkie -and @WorldDomination

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 file.

!!! note
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.

To view a list of all tags in the journal, enter:

sh
jrnl --tags

Viewing Starred Entries

To display only your favorite (starred) entries, enter

sh
jrnl -starred

Editing 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. You
can also edit only the entries that match specific search criteria. For example,

sh
jrnl -to 1950 @texas -and @history --edit

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).

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,

sh
jrnl work -n 1 --edit

opens the most recent entry in the 'work' journal in your external editor.

Deleting Entries

The --delete command opens an interactive interface for deleting entries. The
date and title of each entry in the journal are presented one at a time, and you
can choose whether to keep or delete each entry.

If no filters are specified, jrnl will ask you to keep or delete each entry in
the entire journal, one by one. If there are a lot of entries in the journal, it
may be more efficient to filter entries before passing the --delete command.

Here's an example. Say you have a journal into which you've imported the last 12
years of blog posts. You use the @book tag a lot, and for some reason you want
to delete some, but not all, of the entries in which you used that tag, but only
the ones you wrote at some point in 2004 or earlier. You're not sure which
entries you want to keep, and you want to look through them before deciding.
This is what you might enter:

sh
jrnl -to 2004 @book --delete

jrnl will show you only the relevant entries, and you can choose the ones you
want to delete.

You may want to delete all of the entries containing @book that you wrote in
2004 or earlier. If there are dozens or hundreds, the easiest way would be to
use an external editor. Open an editor with the entries you want to delete...

sh
jrnl -to 2004 @book --edit

...select everything, delete it, save and close, and all of those entries are
removed from the journal.

Listing Journals

To list all of your journals:

sh
jrnl --list

The journals displayed correspond to those specified in the jrnl
configuration file.

File: docs_theme/requirements.txt

mkdocs>=1.4
jinja2==3.1.6

File: tests/data/configs/basic_dayone.yaml

colors:
date: none
title: none
body: none
tags: none
default_hour: 9
default_minute: 0
editor: noop
encrypt: false
highlight: true
journals:
default: features/journals/basic_dayone.dayone
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/basic_encrypted.yaml

colors:
date: none
title: none
body: none
tags: none
default_hour: 9
default_minute: 0
editor: noop
encrypt: true
highlight: true
journals:
default: features/journals/basic_encrypted.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/basic_folder.yaml

colors:
date: none
title: none
body: none
tags: none
default_hour: 9
default_minute: 0
editor: noop
encrypt: false
highlight: true
journals:
default: features/journals/basic_folder
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/basic_onefile.yaml

colors:
date: none
title: none
body: none
tags: none
default_hour: 9
default_minute: 0
editor: noop
encrypt: false
highlight: true
journals:
default: features/journals/basic_onefile.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/brackets.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/brackets.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/bug153.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
journals:
default: features/journals/bug153.dayone
linewrap: 80
tagsymbols: '@'
template: false
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/bug780.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
journals:
default: features/journals/bug780.dayone
linewrap: 80
tagsymbols: '@'
template: false
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/dayone.yaml

default_hour: 9
default_minute: 0
editor: noop
template: false
encrypt: false
highlight: true
journals:
default: features/journals/dayone.dayone
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/dayone_empty.yaml

default_hour: 9
default_minute: 0
editor: noop
template: false
encrypt: false
highlight: true
journals:
default: features/journals/dayone_empty.dayone
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/deletion.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/deletion.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/deletion_filters.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/deletion_filters.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/duplicate_keys.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
template: false
template: false
journals:
default:
encrypt: false
journal: features/journals/simple.journal
journal: features/journals/simple.journal
ideas:
encrypt: false
journal: features/journals/does-not-exist.journal
simple:
encrypt: false
journal: features/journals/simple.journal
encrypt: false
work:
encrypt: false
journal: features/journals/work.journal
linewrap: 80
tagsymbols: '@'
editor: nano
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/editor-args.yaml

default_hour: 9
default_minute: 0
editor: vim -f -c 'setf markdown'
encrypt: false
highlight: true
journals:
default: features/journals/simple.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/editor.yaml

default_hour: 9
default_minute: 0
editor: "vim"
encrypt: false
highlight: true
journals:
default: features/journals/simple.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/editor_empty_folder.yaml

default_hour: 9
default_minute: 0
editor: 'vim'
template: false
encrypt: false
highlight: true
journals:
default: features/journals/empty_folder
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/editor_encrypted.yaml

colors:
body: green
date: blue
tags: none
title: yellow
default_hour: 9
default_minute: 0
editor: "vim"
encrypt: true
template: false
highlight: true
journals:
default: features/journals/encrypted.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/editor_markdown_extension.yaml

default_hour: 9
default_minute: 0
encrypt: false
highlight: true
editor: "vim"
journals:
default: features/journals/editor_markdown_extension.journal
linewrap: 80
tagsymbols: "@"
template: features/templates/extension.md
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/empty_file.yaml

[Empty file]

File: tests/data/configs/empty_folder.yaml

default_hour: 9
default_minute: 0
editor: ''
template: false
encrypt: false
highlight: true
journals:
default: features/journals/empty_folder
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/encrypted.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: true
template: false
highlight: true
journals:
default: features/journals/encrypted.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/encrypted_old.json

{
"default_hour": 9,
"default_minute": 0,
"editor": "",
"encrypt": true,
"highlight": true,
"journals": {
"default": "features/journals/encrypted_jrnl-1-9-5.journal"
},
"linewrap": 80,
"tagsymbols": "@",
"timeformat": "%Y-%m-%d %H:%M"
}

File: tests/data/configs/encrypted_old.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: true
highlight: true
journals:
default: features/journals/encrypted_jrnl1-9-5.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/encrypted_v1_journal_legacy_config.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: jrnlv1
template: false
highlight: true
journals:
default: features/journals/encrypted_jrnl-1-9-5.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/encrypted_v1_journal_per_journal_encrypt.yaml

default_hour: 9
default_minute: 0
editor: ''
template: false
highlight: true
journals:
default:
journal: features/journals/encrypted_jrnl-1-9-5.journal
encrypt: jrnlv1
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/encrypted_v2_journal_legacy_config.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: jrnlv2
template: false
highlight: true
journals:
default: features/journals/encrypted.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/encrypted_v3.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: true
template: false
highlight: true
journals:
default: features/journals/encrypted_v3.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/encrypted_v3_legacy_header.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: true
template: false
highlight: true
journals:
default: features/journals/encrypted_v3_legacy_header.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/format_md.yaml

colors:
body: none
date: none
tags: none
title: none
default_hour: 9
default_minute: 0
display_format: markdown
editor: ''
encrypt: false
highlight: true
indent_character: '|'
journals:
default: features/journals/simple.journal
linewrap: 80
tagsymbols: '@'
template: false
timeformat: '%Y-%m-%d %H:%M'
version: v2.4.5

File: tests/data/configs/format_text.yaml

colors:
body: none
date: none
tags: none
title: none
default_hour: 9
default_minute: 0
display_format: text
editor: ''
encrypt: false
highlight: true
indent_character: '|'
journals:
default: features/journals/simple.journal
linewrap: 80
tagsymbols: '@'
template: false
timeformat: '%Y-%m-%d %H:%M'
version: v2.4.5

File: tests/data/configs/invalid_color.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/simple.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: not-a-color
title: also-not-a-color
body: still-no-color
tags: me-too

File: tests/data/configs/linewrap_auto.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/simple.journal
linewrap: auto
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/little_endian_dates.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/little_endian_dates.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%d.%m.%Y %H:%M"
indent_character: "|"

File: tests/data/configs/markdown-headings-335.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
template: false
journals:
default: features/journals/markdown-headings-335.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/missing_directory.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/missing_directory/simple.journal
endslash: features/journals/missing_folder/
endbackslash: features\journals\missing_folder
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/missing_encrypt_key.yaml

default_hour: 9
default_minute: 0
editor: ''
template: false
highlight: true
journals:
default: features/journals/basic_onefile.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/missing_journal.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/missing.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/missing_tags_color.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
template: false
journals:
default: features/journals/tags.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"
colors:
date: none
title: none
body: none

File: tests/data/configs/mostlyreadabledates.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/mostlyreadabledates.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/multiline-tags.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/multiline-tags.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/multiline.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/multiline.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/multiple.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
template: false
journals:
default: features/journals/simple.journal
ideas: features/journals/does-not-exist.journal
simple: features/journals/simple.journal
work: features/journals/work.journal
new_encrypted:
encrypt: true
journal: features/journals/new_encrypted.journal
✨: features/journals/simple.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/no_colors.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/simple.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"

File: tests/data/configs/no_default_journal.yaml

default_hour: 9
default_minute: 0
editor: ''
template: false
encrypt: false
highlight: true
journals:
simple: features/journals/simple.journal
work: features/journals/work.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"

File: tests/data/configs/simple.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/simple.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/tags-216.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
template: false
journals:
default: features/journals/tags-216.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/tags-237.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
template: false
journals:
default: features/journals/tags-237.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/tags.yaml

default_hour: 9
default_minute: 0
editor: ''
encrypt: false
highlight: true
template: false
journals:
default: features/journals/tags.journal
linewrap: 80
tagsymbols: '@'
timeformat: '%Y-%m-%d %H:%M'
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/unreadabledates.yaml

default_hour: 9
default_minute: 0
editor: ""
encrypt: false
highlight: true
journals:
default: features/journals/unreadabledates.journal
linewrap: 80
tagsymbols: "@"
template: false
timeformat: "%Y-%m-%d %H:%M"
indent_character: "|"
colors:
date: none
title: none
body: none
tags: none

File: tests/data/configs/upgrade_from_195.json

{
"default_hour": 9,
"timeformat": "%Y-%m-%d %H:%M",
"linewrap": 80,
"encrypt": false,
"editor": "",
"default_minute": 0,
"highlight": true,
"journals": {"default": "features/journals/simple_jrnl-1-9-5.journal"},
"tagsymbols": "@"
}

File: tests/data/configs/upgrade_from_195_little_endian_dates.json

{
"default_hour": 9,
"timeformat": "%d.%m.%Y %H:%M",
"linewrap": 80,
"encrypt": false,
"editor": "",
"default_minute": 0,
"highlight": true,
"journals": {"default": "features/journals/simple_jrnl-1-9-5_little_endian_dates.journal"},
"tagsymbols": "@"
}

File: tests/data/configs/upgrade_from_195_with_missing_encrypted_journal.json

{
"default_hour": 9,
"timeformat": "%Y-%m-%d %H:%M",
"linewrap": 80,
"encrypt": true,
"editor": "",
"default_minute": 0,
"highlight": true,
"journals": {"default": "features/journals/encrypted_jrnl-1-9-5.journal", "missing": "features/journals/missing.journal"},
"tagsymbols": "@"
}

File: tests/data/configs/upgrade_from_195_with_missing_journal.json

{
"default_hour": 9,
"timeformat": "%Y-%m-%d %H:%M",
"linewrap": 80,
"encrypt": false,
"editor": "",
"default_minute": 0,
"highlight": true,
"journals": {"default": "features/journals/simple_jrnl-1-9-5.journal", "missing": "features/journals/missing.journal"},
"tagsymbols": "@"
}

File: tests/data/journals/basic_folder/should-be-ignored.txt

[2022-03-02 9:25:00 AM] This file should be ignored (root)
This text file is in a folder journal's root directory, but it's not in the file name format used by jrnl for folder journal entries, so it should be ignored.

This file should not ever appear in a test.

File: tests/data/journals/basic_folder/2020/should-be-ignored.txt

[2022-03-02 9:25:00 AM] This file should be ignored (year)
This text file is in a folder journal's year directory ("2020"), but it's not in the file name format used by jrnl for folder journal entries, so it should be ignored.

This file should not ever appear in a test.

File: tests/data/journals/basic_folder/2020/08/29.txt

[2020-08-29 11:11:00 AM] Entry the first.
Lorem @ipsum dolor sit amet, consectetur adipiscing elit. Praesent malesuada
quis est ac dignissim. Aliquam dignissim rutrum pretium. Phasellus pellentesque
augue et venenatis facilisis. Suspendisse potenti. Sed dignissim sed nisl eu
consequat. Aenean ante ex, elementum ut interdum et, mattis eget lacus. In
commodo nulla nec tellus placerat, sed ultricies metus bibendum. Duis eget
venenatis erat. In at dolor dui. @tagone and maybe also @tagtwo.

Curabitur accumsan nunc ac neque tristique, eleifend faucibus justo
ullamcorper. Suspendisse at mattis nunc. Nullam eget lacinia urna. Suspendisse
potenti. Ut urna est, venenatis sed ante in, ultrices congue mi. Maecenas eget
molestie metus. Mauris porttitor dui ornare gravida porta. Quisque sed lectus
hendrerit, lacinia ante eget, vulputate ante. Aliquam vitae erat non felis
feugiat sagittis. Phasellus quis arcu fringilla, mattis ligula id, vestibulum
urna. Vivamus facilisis leo a mi tincidunt condimentum. Donec eu euismod enim.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam eu ligula eget
velit scelerisque fringilla. Phasellus pharetra justo et nulla fringilla, ac
porta sapien accumsan. Class aptent taciti sociosqu ad litora torquent per
conubia nostra, per inceptos himenaeos.

File: tests/data/journals/basic_folder/2020/08/31.txt

[2020-08-31 02:32:00 PM] A second entry in what I hope to be a long series. *
Sed sit amet metus et sapien feugiat elementum. Aliquam bibendum lobortis leo
vitae tempus. Donec eleifend nec mi non volutpat. Lorem ipsum dolor sit amet,
consectetur adipiscing elit. Praesent ut sodales libero. Maecenas nisl lorem,
vestibulum in tempus sit amet, fermentum ut arcu. Donec vel vestibulum lectus,
eget pretium enim. Maecenas diam nunc, imperdiet vitae pharetra sed, pretium id
lectus. Donec eu metus et turpis tempor tristique ac non ex. In tellus arcu,
egestas at efficitur et, ultrices vel est. Sed commodo et nibh non elementum.
Mauris tempus vitae neque vel viverra. @tagtwo all by its lonesome.

Nulla mattis elementum magna, viverra pretium dui fermentum et. Cras vel
vestibulum odio. Quisque sit amet turpis et urna finibus maximus. Interdum et
malesuada fames ac ante ipsum primis in faucibus. Fusce porttitor iaculis sem,
non dictum ipsum varius nec. Nulla eu erat at risus gravida blandit non vel
ante. Nam egestas ipsum leo, eu ultricies ipsum tincidunt vel. Morbi a commodo
eros.

Nullam dictum, nisl ac varius tempus, ex tortor fermentum nisl, non
tempus dolor neque a lorem. Suspendisse a faucibus ex, vel ornare tortor.
Maecenas tincidunt id felis quis semper. Pellentesque enim libero, fermentum
quis metus id, rhoncus euismod magna. Nulla finibus velit eu purus bibendum
interdum. Integer id justo dui. Integer eu tellus in turpis bibendum blandit.
Quisque auctor lacinia consectetur.

File: tests/data/journals/basic_folder/2020/09/24.txt

[2020-09-24 09:14:00 AM] The third entry finally after weeks without writing.
I'm so excited about emojis. 💯 🎶 💩

Donec semper pellentesque iaculis. Nullam cursus et justo sit amet venenatis.
Vivamus tempus ex dictum metus vehicula gravida. Aliquam sed sem dolor. Nulla
eget ultrices purus. Quisque at nunc at quam pharetra consectetur vitae quis
dolor. Fusce ultricies purus eu est feugiat, quis scelerisque nibh malesuada.
Quisque egestas semper nibh in hendrerit. Nam finibus ex in mi mattis
vulputate. Sed mauris urna, consectetur in justo eu, volutpat accumsan justo.
Phasellus aliquam lacus placerat convallis vestibulum. Curabitur maximus at
ante eget fringilla. @tagthree and also @tagone

File: tests/data/journals/basic_folder/2020/09/should-be-ignored.txt

[2022-03-02 9:25:00 AM] This file should be ignored (month)
This text file is in a folder journal's month directory ("2020/09"), but it's not in the file name format used by jrnl for folder journal entries, so it should be ignored.

This file should not ever appear in a test.

File: tests/data/journals/dayone_empty.dayone/entries/empty.txt

This file exists to preserve the directory structure, but should be ignored by jrnl.

File: .github/actionlint-matcher.json

{
"problemMatcher": [
{
"owner": "actionlint",
"pattern": [
{
"regexp": "^(?:\x1b\[\d+m)?(.+?)(?:\x1b\[\d+m):(?:\x1b\[\d+m)(\d+)(?:\x1b\[\d+m):(?:\x1b\[\d+m)(\d+)(?:\x1b\[\d+m): (?:\x1b\[\d+m)(.+?)(?:\x1b\[\d+m)* \[(.+?)\]$",
"file": 1,
"line": 2,
"column": 3,
"message": 4,
"code": 5
}
]
}
]
}

File: .github/FUNDING.yml

These are supported funding model platforms

github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: jrnl
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

File: .github/lock.yml

Configuration for Lock Threads - https://github.com/dessant/lock-threads-app

Number of days of inactivity before a closed issue or pull request is locked

daysUntilLock: 90

Skip issues and pull requests created before a given timestamp. Timestamp must

follow ISO 8601 (`YYYY-MM-DD`). Set to `false` to disable

skipCreatedBefore: false

Issues and pull requests with these labels will be ignored. Set to `[]` to disable

exemptLabels: []

Label to add before locking, such as `outdated`. Set to `false` to disable

lockLabel: ':lock:'

Comment to post before locking. Set to `false` to disable

lockComment: >
This thread has been automatically locked since there has not been
any recent activity after it was closed. Please open a new issue for
related bugs. You can link back here from your new issue to continue
the conversation.

Assign `resolved` as the reason for locking. Set to `false` to disable

setLockReason: true

Limit to only `issues` or `pulls`

only: issues

Optionally, specify configuration settings just for `issues` or `pulls`

issues:

exemptLabels:

- help-wanted

lockLabel: outdated

pulls:

daysUntilLock: 30

Repository to extend settings from

_extends: repo

File: .github/PULL_REQUEST_TEMPLATE.md

Checklist

  • I have read the contributing doc.
  • I have included a link to the relevant issue number.
  • I have checked to ensure there aren't other open pull requests
    for the same issue.
  • I have written new tests for these changes, as needed.

File: .github/renovate.json

{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": [
"config:base"
],
"schedule": [ "at any time" ],
"prConcurrentLimit": 10,
"prHourlyLimit": 10,
"automerge": true,
"automergeType": "pr",
"reviewers": [
"wren",
"micahellison",
"alichtman"
],
"labels": [ "packaging" ]
}

File: .github/stale.yml

Number of days of inactivity before an issue becomes stale

daysUntilStale: 60

Number of days of inactivity before a stale issue is closed

daysUntilClose: 7

Issues with these labels will never be considered stale

exemptLabels:

  • ':pushpin:'
  • critical

Label to use when marking an issue as stale

staleLabel: stale

Comment to post when marking an issue as stale. Set to `false` to disable

markComment: >
This issue has been automatically marked as stale because it has not had
recent activity. It will be closed if no further activity occurs. Thank you
for your contributions.

Comment to post when closing a stale issue. Set to `false` to disable

closeComment: false

File: .github/actions/run_tests/action.yaml

name: run jrnl tests
inputs:
cache-string:
required: true
runs:
using: "composite"
steps:

  • run: git config --global core.autocrlf false
    shell: bash

  • name: Set up Python ${{ matrix.python-version }}
    uses: actions/setup-python@v7
    with:
    python-version: ${{ matrix.python-version }}
    allow-prereleases: true

  • name: Capture full Python version in env
    run: echo "PYTHON_FULL_VERSION=$(python --version)" >> $GITHUB_ENV
    shell: bash

  • name: poetry cache # Change CACHE_STRING secret to bust the cache
    uses: actions/cache@v6
    with:
    path: .venv
    key: ${{ runner.os }}-${{ hashFiles('poetry.lock') }}-${{ env.PYTHON_FULL_VERSION }}-${{ inputs.cache-string }}

  • name: Install dependencies
    run: |
    echo '::group::poetry'
    pip --disable-pip-version-check install poetry
    poetry config --local virtualenvs.in-project true
    echo '::endgroup::'

    echo '::group::Other dependencies'
    poetry sync
    echo '::endgroup::'

    echo 'DEPS_INSTALLED=true' >> $GITHUB_ENV
    shell: bash

  • name: Linting & Testing
    if: ${{ env.DEPS_INSTALLED == 'true' }}
    run: poetry run poe test
    shell: bash

File: .github/ISSUE_TEMPLATE/bug_report.yaml

name: Bug Report
title: "Bug Report"
labels: [ ":new:", "bug" ]
body:

  • type: markdown
    attributes:
    value: |
    # Bug Report
    Hello, and thank you for reporting an issue!

    Please fill out the points below, as it will make our process much easier.

  • type: textarea
    id: diagnostic
    attributes:
    label: Diagnostic output
    placeholder: Paste output here
    validations:
    required: true

  • type: textarea
    id: current-behavior
    attributes:
    label: Current Behavior
    placeholder: Tell us what is happening
    validations:
    required: true

  • type: textarea
    id: expected-behavior
    attributes:
    label: Expected Behavior
    placeholder: Tell us what should be happening
    validations:
    required: true

  • type: textarea
    id: repro-steps
    attributes:
    label: Repro Steps
    Provide the steps to reproduce the problem.

    Please be as precise as possible, since more info will let us help you faster.

    placeholder: Repro steps
    validations:
    required: true

  • type: textarea
    id: debug-output
    attributes:
    label: Debug output
    Please provide the output of your command with the --debug flag on.

    placeholder: "example: jrnl --debug lorem ipsum"
    validations:
    required: true

  • type: textarea
    id: other-info
    attributes:
    label: Other Information
    Is there anything else we should know?

    (e.g. more detailed explanation, stacktraces, related
    issues, suggestions how to fix, links for us to have context, eg.
    stackoverflow, gitter, etc)

    validations:
    required: false

File: .github/ISSUE_TEMPLATE/config.yml

blank_issues_enabled: false

File: .github/ISSUE_TEMPLATE/documentation.yaml

name: Documentation Change
title: Documentation Change
labels: [ ":new:", "documentation" ]
body:

  • type: markdown
    attributes:
    value: |
    # Documentation Change
    Hello, and thank you for reporting an issue!

    Please fill out the points below, as it will make our process much easier.

  • type: textarea
    id: affected-pages
    attributes:
    label: Affected Page(s)
    Please tell us which page, or pages, from the documentation site
    (https://jrnl.sh) are affected in this issue

    placeholder: "example: https://jrnl.sh/en/stable/overview"
    validations:
    required: true

  • type: textarea
    id: what-could-be-better
    attributes:
    label: What Could Be Better?
    Please write a short description of what you hope can be clarified or
    further explained.

    validations:
    required: true

  • type: textarea
    id: other-info
    attributes:
    label: Other Information
    validations:
    required: false

File: .github/ISSUE_TEMPLATE/feature_request.yaml

name: Feature Request
title: "Feature Report"
labels: [ ":new:", "enhancement" ]
body:

  • type: markdown
    attributes:
    value: |
    # Feature Request
    Hello, and thank you for reporting an issue!

    Please fill out the points below, as it will make our process much easier.

  • type: textarea
    id: user-case
    attributes:
    label: Use Case/Motivation
    placeholder: Tell us about your idea
    validations:
    required: true

  • type: textarea
    id: example-usage
    attributes:
    label: Example Usage
    placeholder: e.g jrnl --new-flag="super cool new feature"
    validations:
    required: true

  • type: textarea
    id: other-info
    attributes:
    label: Other Information
    Is there anything else we should know?

    (e.g. more detailed explanation, stacktraces, related
    issues, suggestions how to fix, links for us to have context, eg.
    stackoverflow, gitter, etc)

    validations:
    required: false

File: .github/ISSUE_TEMPLATE/support_request.yaml

name: Support Request
title: Support Request
labels: [ ":new:", "support" ]
body:

  • type: markdown
    attributes:
    value: |
    # Support Request
    Hello, and thank you for reporting an issue!

    Please fill out the points below, as it will make our process much easier.

  • type: textarea
    id: diagnostic
    attributes:
    label: Diagnostic output
    placeholder: Paste output here
    validations:
    required: true

  • type: textarea
    id: current-behavior
    attributes:
    label: What are you trying to do?
    placeholder: Tell us what is happening
    validations:
    required: true

  • type: textarea
    id: tried
    attributes:
    label: What have you tried?
    Have you tried anything to fix the problem? This can help give us more
    information to help you with.

    placeholder: Tell us what should be happening
    validations:
    required: true

  • type: textarea
    id: other-info
    attributes:
    label: Other Information
    Is there anything else we should know?

    (e.g. more detailed explanation, stacktraces, related
    issues, suggestions how to fix, links for us to have context, eg.
    stackoverflow, gitter, etc)

    validations:
    required: false

File: .github/workflows/changelog.yaml

License: https://www.gnu.org/licenses/gpl-3.0.html

name: Changelog

on:
push:
branches:
- main
tags:
- 'v*'

jobs:
generate:
if: >
! contains(github.event.head_commit.message, '[ci skip]') &&
! (
startsWith(github.event.head_commit.message, 'Increment version to v') &&
startsWith(github.ref, 'refs/heads/')
)
runs-on: ubuntu-latest

text
steps:
  - uses: actions/checkout@v7
    with:
      token: ${{ secrets.JRNL_BOT_TOKEN }}

  - name: Check branch for new commits, and env vars
    run: |
      echo "::group::git fetch origin --tags --force"
      git fetch origin --tags --force
      echo "::endgroup::"

      TAG_REGEX='include-all'
      echo "::debug::GITHUB_REF: $GITHUB_REF"
      BRANCH="${GITHUB_REF##*/}"

      if [[ $GITHUB_REF =~ ^refs/tags/ ]]; then
        # This is a tag build (i.e. a release)
        echo '::debug::Release build'
        if [[ ! $BRANCH =~ ^v[0-9]+(\.[0-9]+){1,2}(-(alpha|beta)([0-9]+)?)?$ ]]; then
          echo "::error::Invalid tag format: ${BRANCH}"
          exit 1
        fi

        RELEASE=1
        BRANCH=main
        git checkout $BRANCH

        # if actual release (not pre), then changelog should exclude prereleases on update
        prerelease_regex='(alpha|beta)'
        if [[ ! ${GITHUB_REF##*/} =~ $prerelease_regex ]]; then
          echo '::debug::Actual release (not a prerelease)'
          TAG_REGEX="$prerelease_regex"
          echo "FULL_RELEASE=true" >> "$GITHUB_ENV"
        fi
      fi
      echo "::debug::TAG_REGEX: $TAG_REGEX"

      if [[ "$(git rev-parse "origin/$BRANCH")" != "$GITHUB_SHA" ]]; then
        # Normal build on a branch (no tag)
        echo "::debug::BRANCH: $BRANCH $(git rev-parse "origin/$BRANCH")"
        echo "::debug::GITHUB_SHA: $GITHUB_SHA"
        echo "::error::$BRANCH has been updated since build started. Aborting changelog."
        exit 1
      fi

      SINCE_TAG=$(git tag --sort=-creatordate | grep -Ev "$TAG_REGEX" | awk "NR==$(( 1 + ${RELEASE:-0} ))")

      echo "::debug::BRANCH: $BRANCH"
      echo "::debug::TAG_REGEX: $TAG_REGEX"
      echo "::debug::FILENAME: CHANGELOG.md"
      echo "::debug::SINCE_TAG: $SINCE_TAG"

      {
      echo "BRANCH=$BRANCH"
      echo "TAG_REGEX=$TAG_REGEX"
      echo "FILENAME=CHANGELOG.md"
      echo "SINCE_TAG=$SINCE_TAG"
      } >> "$GITHUB_ENV"

  - name: Prep changelog file (clear out old lines)
    run: |
      # delete the top of the changelog up to the correct tag
      tagline=$(grep -n "^## \[${SINCE_TAG}\]" "$FILENAME" | awk '{print $1}' FS=':' | head -1)
      echo "tagline: ${tagline}"

      if [[ -z $tagline ]]; then
        echo "::error::Something is wrong. ${SINCE_TAG} isn't in the changelog."
        exit 1
      fi

      if [[ $tagline == 1 ]]; then
        echo "::error::Something is wrong."
        echo "::error::The latest release ${SINCE_TAG} is the first line in the changelog,"
        echo "::error::but the h1 '# Changelog' should always be the first line."
        exit 1
      fi

      sed -i "1,$(( tagline - 1 ))d" "$FILENAME"
      # delete generated line (or it will be added multiple times)
      sed -i '/This Changelog was automatically generated by/d' "$FILENAME"
      # delete trailing empty lines
      sed -i -e :a -e '/^\n*$/{$d;N;};/\n$/ba' "$FILENAME"

  - name: Generate changelog
    uses: heinrichreimer/[email protected]
    with:
      # see: https://github.com/heinrichreimer/action-github-changelog-generator
      repo: jrnl-org/jrnl
      token: ${{ secrets.JRNL_BOT_TOKEN }}
      base: CHANGELOG.md
      addSections: '{"build":{"prefix":"**Build:**","labels":["build"]},"docs":{"prefix":"**Documentation:**","labels":["documentation"]},"packaging":{"prefix":"**Packaging:**","labels":["packaging"]}}'
      issues: true
      pullRequests: true
      issuesWoLabels: false
      unreleased: true
      compareLink: true
      includeLabels: bug,enhancement,documentation,build,packaging,deprecated
      excludeLabels: stale,wontfix
      excludeTagsRegex: ${{ env.TAG_REGEX }}
      sinceTag: ${{ env.SINCE_TAG }}
      maxIssues: 150
      releaseUrl: https://pypi.org/project/jrnl/%s/
      releaseBranch: main
      verbose: false
      author: true

  - name: Small fixes
    run: |
      # Change unreleased link to correct url
      sed -i 's!https://pypi.org/project/jrnl/HEAD/!https://github.com/jrnl-org/jrnl/!' "$FILENAME"

  - name: Diff and consistency check
    run: |
      git diff
      if [[ $(grep -c '^# Changelog$' "$FILENAME") != 1 ]]; then
        echo '::error::Something is wrong with the changelog.'
        exit 1
      fi
      SOMETHING_CHANGED=false
      git diff --exit-code || SOMETHING_CHANGED=true
      echo "::debug::SOMETHING_CHANGED: $SOMETHING_CHANGED"
      echo "SOMETHING_CHANGED=$SOMETHING_CHANGED" >> "$GITHUB_ENV"

  - name: Commit
    if: env.SOMETHING_CHANGED == 'true'
    run: |
      git config --global user.name "${{ secrets.JRNL_BOT_NAME }}"
      git config --global user.email "${{ secrets.JRNL_BOT_EMAIL }}"
      git add "$FILENAME"
      git commit -m "Update changelog [ci skip]"
      git push origin "$BRANCH"

  - name: Update tag to include changelog
    if: startsWith(github.ref, 'refs/tags/')
    run: |
      # This is a tag build (releases and prereleases)
      # update the tag to include the changelog
      git tag -fam "$GITHUB_REF_NAME" "$GITHUB_REF_NAME"
      git push --tags --force

  - name: Create GitHub release
    if: startsWith(github.ref, 'refs/tags/')
    env:
      GH_TOKEN: ${{ secrets.JRNL_BOT_TOKEN }}
    run: |
      # Pull this tag's section out of the changelog to use as release notes
      notes_file=$(mktemp)
      awk -v tag="$GITHUB_REF_NAME" '
        $0 ~ ("^## \\[" tag "\\]") { found=1; next }
        found && /^## \[/ { exit }
        found { print }
      ' "$FILENAME" > "$notes_file"

      prerelease_flag=()
      if [[ "$FULL_RELEASE" != "true" ]]; then
        prerelease_flag=(--prerelease)
      fi

      gh release create "$GITHUB_REF_NAME" \
        --title "$GITHUB_REF_NAME" \
        --notes-file "$notes_file" \
        --repo "$GITHUB_REPOSITORY" \
        "${prerelease_flag[@]}"

  - name: Merge to Release branch
    if: env.FULL_RELEASE == 'true'
    run: |
      git fetch --unshallow origin
      git checkout release
      git merge --ff-only "$BRANCH"
      git push origin release

File: .github/workflows/docs.yaml

License: https://www.gnu.org/licenses/gpl-3.0.html

name: Docs

on:
push:
branches: [ main, release ]
paths:
- 'docs/'
- 'docs_theme/'
- 'mkdocs.yml'
- 'readthedocs.yml'
- '.github/workflows/docs.yaml'
- 'tasks.py'
- 'pyproject.toml'
pull_request:
branches: [ main ]
paths:
- 'docs/'
- 'docs_theme/'
- 'mkdocs.yml'
- 'readthedocs.yml'
- '.github/workflows/docs.yaml'
- 'tasks.py'
- 'pyproject.toml'

jobs:
accessibility:
if: contains(toJson(github.event.commits), '[ci skip]') == false
runs-on: ubuntu-latest
strategy:
fail-fast: true
matrix:
python-version: [ '3.11' ]
os: [ ubuntu-latest ]

text
steps:
- uses: actions/checkout@v7

- name: Set up Python
  uses: actions/setup-python@v7
  with:
    python-version: ${{ matrix.python-version }}

- name: Setup Node.js environment
  uses: actions/setup-node@main

- name: Capture full Python version in env
  run: echo "PYTHON_FULL_VERSION=$(python --version)" >> "$GITHUB_ENV"

- name: poetry cache
  uses: actions/cache@v6
  with:
    path: .venv
    key: ${{ runner.os }}-${{ hashFiles('poetry.lock') }}-${{ env.PYTHON_FULL_VERSION }}-${{ secrets.CACHE_STRING }}

- name: npm cache
  uses: actions/cache@v6
  with:
    path: node_modules
    key: ${{ runner.os }}-pa11y-cache-${{ secrets.CACHE_STRING }}

- name: puppeteer cache for pa11y
  uses: actions/cache@v6
  with:
    path: home/runner/.cache/puppeteer
    key: ${{ runner.os }}-puppeteer-cache-${{ secrets.CACHE_STRING }}

- name: Install dependencies
  run: |
    pip install poetry
    poetry config --local virtualenvs.in-project true
    poetry sync --no-root
    npm install
    npx puppeteer browsers install chrome
    echo "node_modules/.bin" >> "$GITHUB_PATH"

- name: Start docs server
  run: poetry run poe docs-run &

- name: Accessibility testing (Pa11y)
  run: poetry run poe docs-check

File: .github/workflows/release.yaml

License: https://www.gnu.org/licenses/gpl-3.0.html

name: Release
on:
workflow_dispatch:
inputs:
version:
type: string
required: true
include_repo_version:
type: boolean
required: true
default: true
include_pypi:
type: boolean
required: true
default: true

jobs:
validate:
name: "Validate version string"
runs-on: ubuntu-latest
steps:
- name: Validate version
run: |
JRNL_VERSION="${{ github.event.inputs.version }}"
echo "::debug::version: $JRNL_VERSION"
if [[ ! $JRNL_VERSION =~ ^v[0-9]+(.[0-9]+){1,2}(-(alpha|beta)([0-9]+)?)?$ ]]; then
echo
echo "::error::Bad version"
echo
echo "Version string should match pattern above."
echo "Here are some examples of valid version numbers:"
echo
echo " v2.5"
echo " v2.5-alpha"
echo " v2.5-beta"
echo " v2.5.1"
echo " v2.5.1-alpha"
echo " v2.5.1-beta"
exit 1
fi

release_pypi:
needs: validate
name: "Release to PyPI"
runs-on: ubuntu-latest
outputs:
pypi_version: ${{ steps.pypi-version-getter.outputs.pypi_version }}
env:
HOME_REPO: ${{ secrets.HOME_REPO }}
steps:
- name: Get version
run: |
JRNL_VERSION="${{ github.event.inputs.version }}"
echo "::debug::version: $JRNL_VERSION"
echo "JRNL_VERSION=$JRNL_VERSION" >> "$GITHUB_ENV"

text
- name: Set up Python
  uses: actions/setup-python@v7
  with:
    python-version: '3.14'

- name: Checkout repo
  uses: actions/checkout@v7
  with:
    token: ${{ secrets.JRNL_BOT_TOKEN }}

- name: Config git user
  run: |
    git config --global user.name "${{ secrets.JRNL_BOT_NAME }}"
    git config --global user.email "${{ secrets.JRNL_BOT_EMAIL }}"

- name: Install dependencies
  run: pip install poetry

- name: Update version in files
  if: ${{ github.event.inputs.include_repo_version == 'true' }}
  run: |
    poetry version "$JRNL_VERSION"
    echo "__version__ = \"$(poetry version -s)\"" > jrnl/__version__.py

- name: Commit updated files
  if: ${{ github.event.inputs.include_repo_version == 'true' && github.repository == env.HOME_REPO }}
  run: |
    git add pyproject.toml jrnl/__version__.py
    git commit -m "Increment version to ${JRNL_VERSION}"
    git tag -a -m "$JRNL_VERSION" "$JRNL_VERSION"
    git push
    git push --tags

- name: Build
  run: poetry build

- name: Deploy to PyPI
  if: ${{ github.event.inputs.include_pypi == 'true' && github.repository == env.HOME_REPO }}
  env:
    POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
  run: poetry publish

- name: Get PyPI version
  id: pypi-version-getter
  run: |
    pypi_version="$(find dist/jrnl-*.tar.gz | sed -r 's!dist/jrnl-(.*)\.tar\.gz!\1!')"
    echo "pypi_version=$pypi_version" >> "$GITHUB_OUTPUT"

File: .github/workflows/testing_pipelines.yaml

License: https://www.gnu.org/licenses/gpl-3.0.html

name: Testing Pipeline Files

on:
push:
branches: [ main, release ]
paths:
- '.github/workflows/'
- '.github/actions/'
pull_request:
branches: [ main ]
paths:
- '.github/workflows/'
- '.github/actions/'
schedule:
- cron: '0 0 * * SAT'

jobs:
test:
if: >
! contains(github.event.head_commit.message, '[ci skip]')
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ ubuntu-latest ]
steps:
- run: git config --global core.autocrlf false
- uses: actions/checkout@v7
- name: Check workflow files
uses: docker://rhysd/actionlint:latest
with:
args: -color

File: .github/workflows/testing_prs.yaml

License: https://www.gnu.org/licenses/gpl-3.0.html

name: Testing

on:
push:
branches: [ main, release ]
paths:
- 'jrnl/'
- 'features/'
- 'tests/'
- 'poetry.lock'
- 'pyproject.toml'
- '.github/workflows/testing_prs.yaml'
- 'tasks.py'
pull_request:
branches: [ main ]
paths:
- 'jrnl/'
- 'features/'
- 'tests/'
- 'poetry.lock'
- 'pyproject.toml'
- '.github/workflows/testing_prs.yaml'
- 'tasks.py'

defaults:
run:
shell: bash # needed to prevent Windows from using PowerShell

jobs:
test:
if: >
! contains(github.event.head_commit.message, '[ci skip]')
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
python-version: [ '3.11', '3.12', '3.13', '3.14' ]
os: [ ubuntu-latest, macos-latest, windows-latest ]
steps:
- run: git config --global core.autocrlf false
- uses: actions/checkout@v7
- name: Run tests
uses: ./.github/actions/run_tests
with:
cache-string: ${{ secrets.CACHE_STRING }}

File: .github/workflows/testing_schedule.yaml

License: https://www.gnu.org/licenses/gpl-3.0.html

name: Testing

on:
schedule:
- cron: '0 0 * * SAT'

defaults:
run:
shell: bash # needed to prevent Windows from using PowerShell

jobs:
test_all:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
python-version: [ '3.11', '3.12', '3.13', '3.14' ]
os: [ ubuntu-latest, macos-latest, windows-latest ]
steps:
- run: git config --global core.autocrlf false
- uses: actions/checkout@v7
- name: Run tests
uses: ./.github/actions/run_tests
with:
cache-string: ${{ secrets.CACHE_STRING }}

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#cli Browse cli catalog → #command-line Browse command-line catalog → #encrypted Browse encrypted catalog → #journal Browse journal catalog → #journal-application Browse journal-application catalog → #jrnl Browse jrnl catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →