A Python app that makes it easier to use Zettelkasten with git repos.
Project description
pyzet
A Python app that makes it easier to use Zettelkasten with git repos.
How to use?
The current version is limited in its capabilities, so it might be frustrating to use. Don't hesitate to add an issue or PR, if you have any idea how to improve or expand this tool. The current biggest problem is the lack of configuration file.
The default location of zet repo is ~/zet
. For now, it's hard-coded
path that can be changed with --repo
flag when executing any command.
At this point, the editor for working with zettels is also hard-coded.
On Windows it's the default path to vim.exe
that is installed with Git
for Windows. On Unix (although it wasn't tested on Mac), it's the
default text editor. The option to change editor also will be included
in the config file.
Summary of commands:
$ pyzet -h
usage: pyzet [-h] [-V] [-r REPO] {status,list,tags,show,clean,add,edit,rm,grep,pull,push} ...
positional arguments:
{status,list,tags,show,clean,add,edit,rm,grep,pull,push}
status run `git status` in zet repo,
use `--` before including git options
list list zettels in given repo
tags list tags in given repo
show print zettel contents
clean delete empty folders in zet repo
add add a new zettel
edit edit a zettel
rm remove a zettel
grep run `grep -rni` in zet repo
pull run `git pull --rebase` in zet repo
push run `git push` in zet repo,
use `--` before including git options
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-r REPO, --repo REPO path to point to any zet repo
How to run?
Python 3.7 or later is needed. pyzet doesn't require any external dependencies at this point.
The simplest way to install is to use pip:
pip install pyzet
pyzet --help
You can also obtain the newest version from the develop
branch
directly from this repository:
pip install git+https://github.com/wojdatto/pyzet.git@develop
OS compatibility
Both Windows and Unix are supported, but the current version is 5-10 times faster with the latter. One of the reasons of worse performance might be Windows Defender with its realtime protection.
On of the workarounds is trying to use pyzet with WSL2.
Manual installation
Manual installation is also possible. Clone the repo and run the install command. Using virtual environment is advised.
git clone https://github.com/wojdatto/pyzet.git
cd pyzet
Unix/Linux:
python3 -m venv venv
. venv/bin/activate # in bash `source` is an alias for `.`
pip install .
pyzet --help
Windows:
python -m venv venv
.\venv\Scripts\activate
pip install .
pyzet --help
Development installation
Development dependencies are stored in requirements-dev.txt. To install the package in editable mode with the dev dependencies run the following after cloning the repo:
pip install -e .
pip install -r requirements-dev.txt
Running automatic tests
pyzet uses pytest and tox to run automatic tests. Use pytest
command
to test against the current Python version, or use tox
to test against
multiple Python versions. Pre-commit is also configured as one of tox's
envs.
Automatic test coverage is not ideal at this point, and commands that
directly involve working with I/O (add
, edit
, rm
) are only tested
manually.
Zettel formatting rules and guidelines
Zettels should use Markdown. It is preferred to use consistent flavor of Markdown like CommonMark. pyzet will parse zettel's content trying to extract information like title and tags.
In fact, many rules described below are derived from rwxrob's ZettelMark specification that can be found here, which is also based on CommonMark.
Some of the rules described below are only guidelines, but some of them are needed for pyzet to correctly parse zettels.
General formatting
For a convenient reading zettels in the source form, it's recommended to wrap lines. The common standard is to break line after 72 characters.
Ideal zettels shouldn't be too long, and they should be a brief text description of pretty much anything. Avoid pasting links in the zettel core content and prefer using references section (described below) for that.
pyzet supports tagging zettels with hashtags for easier searching in the future. The number of tags shouldn't be too big, and ideally they should only use keywords that are not a part of a zettel itself. The tagging rules are described below.
Try to use consistent Markdown formatting. We recommend:
-
Use only
*
for bold & italics -
Use only
*
for unordered lists -
If items of unordered lists take more than a single line (will happen if you wrap after 72 chars), separate them with a single blank line
-
Use
<>
to show that something is a link. GitHub and VSCode will detect it even without it, but this is not true for every tool that supports Markdown
Title line
The first line of a zettel that should start with #
and a single
space, and then the title itself. Title line shouldn't have any leading
or trailing spaces.
If wrong formatting is detected, a warning will be raised and pyzet will show you a raw title line instead of a parsed one.
Ideally, title should not exceed 50 characters. This is because a title is also a commit message in a Zettelkasten repo, and GitHub will snip messages longer than 50 characters when displaying commit messages next to the files. At this point, this is not checked by pyzet, so no warning will be raised in that case.
# Example correct zettel title
References
pyzet currently doesn't analyze references, but the suggested way to add them is as follows:
Refs:
* <http://described-example.com/> -- This is an example description
* <http://example.com/>
--
is used here as poor man's En
dash as it's not available
directly from ASCII. However, this won't matter as long as Refs
are
not parsed by pyzet.
If description is longer, break line after 72 characters and put a blank line between references:
Refs:
* <http://described-example.com/> -- This is an example of a longer
description
* <http://example.com/>
Tags
Tags are optional, but if they're used, they should be placed as the
last line of a zettel that starts from 4 or more leading spaces (it's
Markdown syntax for a fenced code block that renders as monospaced
font). Each tag should start with #
and should be separated with a
single space from the next one.
Using small letters and kebab-case
is recommended as a consistent
tagging style, but it's not forced or checked at this moment. A tag line
can be preceded by Tags:
and a single blank line to make zettels more
structured.
Tags:
#tag1 #tag2 #another-tag
TODO
- add a config file
- add integration with Git
- add autocompletion for commands
- add autocompletion for zettels (ID and title?)
Inspiration and further reading
The biggest inspiration for this project was
@rwxrob
, and his approach to
Zettelkasten. Probably the best way to get a grasp of it, is to read
about it in his public Zettelkasten
repo. Rob also
maintains a Bash CLI tool
cmd-zet
.
See also:
-
https://luhmann.surge.sh/ -- two essays by the creator of Zettelkasten, Niklas Luhmann
-
https://gsilvapt.me/posts/building-a-zettelkasten-the-simple-way/ -- even simpler approach to Zettelkasten
-
https://github.com/gsilvapt/pmz.git -- similar tool written in Go
-
https://github.com/Zettlr/Zettlr.git -- if you cannot live without a GUI, this might be an alternative tool for you. There is also an interesting video from the author of this tool that describes his vision of Zettelkasten.
License
Unless explicitly stated otherwise all files in this repository are licensed under the Apache Software License 2.0:
Copyright 2021 Tomasz Wojdat
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.