dirnotes/dirnotes-cli.md

---

title: dirnotes-cli section: 1 header: User Manual footer: dirnotes-cli 1.0

date: Sept 26, 2022

NAME

dirnotes-cli - view and manage Dirnotes file annotations

SYNOPSIS

    dirnotes-cli [-h] [--help] [-V] [--version] 

List:
    dirnotes-cli [-v] [-j] [-l] [-d|-x]
    dirnotes-cli [-v] [-j] [-n] [-d|-x] [filename]...
    dirnotes-cli [-v] [-j] -H [filename]...

Create:
    dirnotes-cli -c "comment" filename...
    dirnotes-cli -a "comment" filename...
    dirnotes-cli -e filename...

FileCopy:
    dirnotes-cli -C src-file...
    dirnotes-cli -M src-file...

Cleanup:
    dirnotes-cli -z [filename]...
    dirnotes-cli -Z

DESCRIPTION

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 list commands will display the comment from the database or xattr (as determined by the config file, below, or as specified with -d/-x options). If the database and xattr comments differ, the comment will be terminated by a '*' character. The -H option displays the history of comments from the database.

The output of the list commands can be in .json format (-j) , and can optionally display the comment creator and the comment date (-v)

The create commands will attempt to store the file comments in both the xattr of the file, and in the database. If either of these fail, they fail silently. Use the -c to create a comment, use -a to append to an existing comment, and -e to erase a comment.

The filecopy commands will copy the file to a destination, and preserve the file comments. [See notes below about LIMITATIONS]

The cleanup commands can clean up the history of comments in the database.

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:

xattr

Comments stored in the xattr properties can be copied/moved with the file, if you use the correct options for cp. 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 are using sshfs, you can use the 'dirnotes' programs to copy a file, and the database comments will work properly. If you want to copy files to a remote machine and include the xattr comments, use rsync with the -X option. Or tar of course.

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.

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.

OPTIONS

-c : add a comment to a file

-C : attempt to copy the file(s) and comments to a destination; if multiple files are copied, the destination must be a directory

-d : use database comments as the primary source; cannot be used with -x

-e : erase the comments on a file

-h --help : display help and usage

-H : output the history of comments for this file(s)

-i
: add a comment to a file; if the comment is not in the command, accept it from stdin

-j : output (to stdio) the file comment in .json format

-l : list all files, including those without dirnotes comments

-M : move the file(s) and comments to the destination; if multiple files are moved, the destination must be a directory

-n : output only the comment; this may be useful for scripting

-v : also include the comment author and comment date in the output

-V --version : display version number

-x : use xattr comments as the primary source; connot be used with -d

-z : erase history comments associated with this file; keep the current comment; if no file is specified, erase the history comments for all files in the current directory

-Z : erase all the historic comments in the user's database

EXAMPLES

To display the comment for a file:

$ dirnotes-cli filename.txt
filename.txt: notes on the car repair

To extract only the comment from a file, use the -n option (useful for scripts):

$ dirnotes-cli -n filename.txt
notes on the car repair

Or, in json format:

$ dirnotes-cli -j filename.txt
[{"file": "filename.txt", "comment": "notes on the car repair"}]

SEE ALSO

dirnotes, dirnotes-tui, dirnotes-cli

The dirnotes program provides a GUI for accessing the files descriptions.

The dirnotes-tui program provides a curses based (terminal) access to the descriptions.

The dirnotes-cli program provides command line access, and can be scripted.

CONFIGURATION FILE

By default, the file ~/.dirnotes.conf will be used to load the user's config. There are three attributes described in that file that are important:

• xattr_tag
  
• database
  
• start_mode