dirnotes/README.md

Dirnotes

Table of Contents

• SYNOPSIS
• USAGE
• INSTALLATION
  • CONFIG FILE
• LIMITATIONS
• PROGRAMMER NOTES
  • MacOS
• DEVELOPMENT STATUS

SYNOPSIS

The dirnotes family of apps allows you to add a descriptive comment to a file. The descriptions are stored in two places:

• in the xattr properties of the file
• in a database located in the user's home directory

[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 tunnel down into directories, or rise up the file system. You can create/edit comments and choose whether the xattr or database version of the comments take 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 you preference.

The dirnotes-cli is a command line tool, which may be handy for scripting.

USAGE

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

All three apps in the dirnotes family have the ability to copy files from the current directory.

INSTALLATION

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.

CONFIG FILE

By default, the file ~/.dirnotes.conf will be used to load the user's config. This is a JSON file, with three attributes that are important:

• xattr_tag (default: usr.xdg.comment)
• database (default: ~/.dirnotes.db, sensible alt: /var/lib/dirnotes.db)
• start_mode (xattr or db priority)

The _configfile should be auto-generated the first time one of the dirnotes apps is run. [not fully implemented]

LIMITATIONS

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.

xattr

Comments stored in the xattr properties can be copied/moved with the file, if you use the correct options: cp -p. 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).

The current implementation of sshfs and scp do not support the copy of xattr properties. 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.

database

Comments stored in the database work for all filesystem types (including vfat/exfat/sshfs)

Comments are personalized to the current user. Another user on the same system will not see these comments.

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.

Comments stored in the database do not travel with the files when they are moved or copied, unless using the dirnotes family of tools.

The database comments that are stored in ~/.dirnotes.db are inherently associated with a single user. If the database is located in /var/lib/dirnotes.db, it is shared by all the users in the system. The comment with the 'most recent timestamp' wins.

PROGRAMMER NOTES

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.

• xattr

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.

• database

The comments are stored in an Sqlite3 database, usually located at "~/.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.

• misc

The dirnotes gui app has a desktop icon built into the code. There is not need for an external .icon file.

There was no consideration given for language translation. Email me if you want this, or can help.

MacOS {#macos}

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:

• in the xattr properties of the file
  
  • using a different xattr-tag (com.apple.metadata:kMDItemFinderComment)
  • the comment string is wrapped in a pList
• in a database located in each directory
  
  • in the .DS-Store file

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.

DEVELOPMENT STATUS{#status}

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.