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 [-y] src-file...
    dirnotes-cli -M [-y] 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 dirnotes-cli is designed for use on the command line, or in scripting.

The list commands will display the comment from the database or xattr (as determined by the config file 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/move 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

Because xattr comments are bound to the filesystem, other command line tools may be used to manage them. 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 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.

Of course, once you start to manipulate xattr comments outside of the dirnotes programs, the xattr comments will become out of sync with the database comments.

database

Comments stored in the database work for all filesystem types (including vfat/exfat/sshfs) Comments are usually stored in a per user database; thus 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.

If you are using sshfs, you can use the dirnotes programs to copy a file, and the database comments will work properly.

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

OPTIONS

-a : append to a comment on a file

-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; the last argument is the destination

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

-D : print debugging information

-e : erase the comments on the file(s)

-h --help : display help and usage

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

-j : output (to stdout) 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 : list full path names, also include the comment author and date in the output

-V --version : display version number

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

-y : allow file overwrite for -C copy or -M move

-z : erase history comments associated with the file(s); keep the current comment

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

EXAMPLES

To display the comment for a file:

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

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

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

Or, in json format:

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

[NOTE: with json output, consider piping the results to jq for pretty-print]

To append to a comment:

$ dirnotes-cli -a 'first quote: \$1,400' car_notes.txt
$ dirnotes-cli car_notes.txt
car_notes.txt: 'notes on the car repair; first quote: $1,400'

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 [default: user.xdg.comment]
  
• database [default: ~/.local/share/dirnotes/dirnotes.db]
  
• start_mode [default: xattr]
  

The default location for the config file is ~/.config/dirnotes/dirnotes.conf