A Linux/BSD app to add comments to files. The comments are stored in a database, and where possible, in the xattr field of the filesystem. There is a GUI, using Python3+Qt5. There is also a terminal (curses) version and a command-line (scriptable).
Pat Beirne 925ae23f64 add images to the README, clean up the imports in the python code | 2 years ago | |
---|---|---|
README.md | 2 years ago | |
dirnotes | 2 years ago | |
dirnotes-cli | 2 years ago | |
dirnotes-cli.md | 2 years ago | |
dirnotes-tui | 2 years ago | |
dirnotes.desktop | 2 years ago | |
dirnotes.xpm | 2 years ago |
The dirnotes family of apps allows you to add a descriptive comment to a file. The descriptions are stored in two places:
[The MacOS stores its comments in a similar way.]
The dirnotes
app is a GUI app, using the Qt5 framework.
At startup, it displays the contents of the current directory, and the
comments associated with any of the files or directories.
Simple mouse clicks allow you to add or edit comments, tunnel down
into directories, or rise up the file system.
You can copy or move files (with comments), and
choose whether the xattr or database version of the comments
have display priority.
The dirnotes-tui
is a very similar app, but uses the
curses framework to display its activity in a terminal window.
This can be handy if you have to work across a network,
or if terminal apps are your preference.
The dirnotes-cli
is a command line tool,
which may be handy for scripting. This all can also do maintenance on the database.
The dirnotes
program displays usage and keystoke info
when you press F1. The dirnotes-tui
program display
onscreen usage when you press the 'h' key, or F1.
The dirnotes-cli
program has a man page.
In short, you navigate dirnotes
and
dirnotes-tui
by using the up/down arrow keys,
<enter> to enter into a directory.
The -tui version accepts e for edit, s for sort, M to change
between xattr/database priority.
The dirnotes-cli
has options
for -l list and -c create a comment. See also dirnotes-cli.1
man page.
All three apps in the dirnotes family have the ability to copy/move files from the current directory, keeping the comments intact. All three apps have the -h option which shows command line usage.
Each of the 3 apps in the family is self contained.
The dirnotes
app requires Python3 and the Qt5 framework.
The dirnotes-tui
and dirnotes-cli
apps
simply require Python3.
Simply mark the 3 python files as executable copy them into your
path, to ~/.local/bin/
or /usr/local/bin/
.
chmod a+x dirnotes dirnotes-tui dirnotes-cli
cp dirnotes dirnotes-tui dirnotes-cli \~/.local/bin/
For a better GUI experience, copy
dirnotes.desktop
to ~/.local/share/applications
and
dirnotes.xpm
to ~/.local/share/icons/
If you are using the command-line tool dirnotes-cli
,
you can generate a man page using
pandoc -s -t man -o dirnotes-cli.1 dirnotes-cli.md
and copy that to ~/.local/share/man/man1
By default, the file ~/.config/dirnotes/dirnotes.conf will be used to load the user's config. This is a JSON file, with three attributes that are important:
user.xdg.comment
)~/.local/share/dirnotes/dirnotes.db
, sensible alt: /var/lib/dirnotes.db
)The _configfile should be auto-generated the first time one of the dirnotes apps is run.
The file comments are located in two locations: a database, and in the xattr properties of the file. Each of these storage locations has its own benefits and limitations. These can be summed up: xattr comments follow the iNode, database comments follow the file name.
Comments stored in the xattr properties can be copied/moved with the file, if you
use the correct options: cp -p src dest
.
The mv
utility
automatically preserves xattr. Other programs can also be coerced into
perserving xattr properties:
rsync
tar
mksquashfs
Not all file systems support xattr properties (vfat/exfat does not).
xattr comments may only be applied to files for which the user has write permission.
The current implementation of sshfs
and scp
do not support copying of xattr properties. Dropbox type mounts are
unlikely to support xattr comments.
If you want to copy files to a remote machine and include the xattr comments, use rsync
with the -X option. Or tar
.
Some editing apps (like vim) will create a new file when saving the data, which orphans the xattr comments. For these apps, use the database system.
Removable disk devices (usb sticks) which are formatted with a Linux-based filesystem (ext2/3/4, btrfs, xfs, zfs) will carry the xattr comments embedded in the filesystem metadata, and are portable to anther computer.
Comments stored in the database work for all filesystem types (including vfat/exfat/sshfs)
The database comments that are stored in
~/.local/share/dirnotes/dirnotes.db
are inherently associated
with a single user. If the database is located in
/var/lib/dirnotes.db
, it can be shared by all the users in the system.
Files are indexed by their complete path name. Removable filesystems should be mounted in a consistent way, so that the complete path name is reproducable. Symlinks are not dereferenced, so they may have comments bound to them.
Comments stored in the database do not travel with the files when they are moved or copied, unless using the dirnotes family of tools.
Database comments may be applied to any visible file, even if they are readonly.
For exmple, comments may be attached to the files in /usr/bin/*
even though they are probably owned by root.
Instead of an API, here is how you can get directly at the underlying comment data. If you intend to use the dirnotes apps, try to keep the two versions of the comments in sync.
Use the commands
xattr -l [filename]
to display the comments/author/date on a file. For example:
$ xattr -l /etc/fstab
user.xdg.comment: controls the default mount bindings
user.xdg.comment.author: patb
user.xdg.comment.date: 2022-09-29 08:07:42
The other options on the xattr command line tool allow you to write (xattr -w) or delete (xattr -d) the comments.
The comments are stored in an Sqlite3 database, usually located at "~/.local/share/dirnotes/dirnotes.db". The database itself is contained within that file, and its schema is this:
CREATE TABLE dirnotes (name TEXT, date DATETIME, size INTEGER, comment TEXT, comment_date DATETIME, author TEXT)
field | usage | example |
---|---|---|
name | the long filename, using python's os.path.abspath() | /home/patb/projects/dirnotes/README.md |
date | the file's modified date | 2020-01-13 09:25:40 |
size | the byte count of the file | 145 |
comment | a utf-8 string | the readme for the GIT page |
comment_date | the date of the comment itself | 2020-10-03 22:30:19 |
author | the system name of the user who created the comment | patb |
The date and size fields reflect the file's modification date and size at the time of the last edit of the file comment, which is stored in _commentdate.
As comments are editted or appended, new records are added to the database. Older records are are not purged. This gives you a history of the comments, but it means that fetching the most recent comment involves something like
SELECT * FROM dirnotes WHERE name=? ORDER BY comment_date DESC
and just fetch the first record.
The database is created the first time one of the dirnotes apps is run.
The dirnotes
gui app has a desktop icon built into the code.
There is not need for an external .icon file, but there is an .xpm file included
in the project, which can be copied to ~/.local/share/icons/
The 3 apps share a big block of common code. At this point, the code is embedded in each executable, but perhaps in the future it will be brought out as a library. I just like apps to be a single file I can copy to my various devices and servers, but it does create a problem of keepint the 3 apps in sync.
The copy()/move()
methods that are built into the dirnotes library
will ask the operating system to copy/move the file with xattr intact.
The entry in the database is created at the time of invocation.
Therefore, the xattrs will reflect the original author+date on the comments,
whereas the database version is updated on each copy/move;
the dirnotes-comments details will therefor diverge over time.
There was no consideration given for language translation. Email me if you want this, or can help.
All these apps only accomadate a single line comment. An embedded newline will cause unpredictable behaviour.
The MacOS inherently supports file comments. The Finder app manages most of the user activity. It handles file comments in a similar manner to Dirnotes. Comments are stored in two places:
com.apple.metadata:kMDItemFinderComment
)pList
The user can examine the file comments by opening the GetInfo dialog, and scrolling down to "Comment"
If the Finder is used to copy/move files, the comments are moved properly to both destinations. If you use the os to copy/move the files, you can ask that the xattr properties get moved, but the .DS-Store file will not be updated. That means the Finder will not see file comments on the destination file.
MacOS has AppleScript, by which you can ask the Finder to perform the file copy/move. In this case, the comments are moved properly.
Each app is a standalone file. That means there is a lot of redundancy between the three apps. And there may be some inconsistency.
2022-10-04
: All three apps are functioning and usable.
The _configfile is fully implemented.
Themes are not implemented.
Comments are intended to be utf-8, but are strings in some places.
MacOS code is not written yet.
The help dialogs in dirnotes-tui
are meagre.
The qt-gui app is working pretty well.
There are several open-ended questions that need to be answered. Does anyone have an opinion?
How important is multi-line comments?
Is it ok to put the config file and database file buried in ~/.config and ~/.local?
These directories exist on computers with a gui/windowing system installed, but don't neccessarily exist on headless servers. Perhaps the default locations should be in the user directory? (~/.dirnotes.conf and ~/.dirnotes.db)
Who needs translations?
Does anybody have a better edit-window for CURSES?
What about storing the database per directory. That's what MacOS does (the .DS_Store file)
PRO
CON
Is anyone interested in the MacOS version?