---
title: 
title-meta: Dirnotes README
note: run this with pandoc -T "Dirnotes README" -s README.md -t html > README.html
---



# Dirnotes

### 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](#macos) stores its comments in a similar way.]

The <code>**dirnotes**</code> 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 <code>**dirnotes-tui**</code> 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 <code>**dirnotes-cli**</code> is a command line tool, which may be handy for scripting.

### USAGE

The <code>**dirnotes**</code> program displays usage and keystoke info when you press _F1_. The <code>**dirnotes-tui**</code> program display onscreen usage when you press the 'h' key, or _F1_. 
The <code>**dirnotes-cli**</code> program has a man page.

In short, you navigate <code>**dirnotes**</code> and <code>**dirnotes-tui**</code> 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 **<code>dirnotes-cli</code>** has options for _-l_ list and _-c_ create a comment. 

### Direct Access

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 also 'comment_date'.

### 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  
 * 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.