--- 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 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. If you are using _sshfs_, you can use the 'dirnotes' programs to copy a file, and the database comments will work properly. # 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