{"id":15148699,"url":"https://github.com/patbeirne/dirnotes","last_synced_at":"2026-02-03T12:33:43.973Z","repository":{"id":200394291,"uuid":"561070074","full_name":"patbeirne/dirnotes","owner":"patbeirne","description":"A Linux/BSD app to add comments to files. The comments are stored in a database, and where possible, in the xattr field of the filesystem. There is a GUI, using Python3+Qt5. There is also a terminal (curses) version and a command-line (scriptable).","archived":false,"fork":false,"pushed_at":"2022-11-04T14:14:46.000Z","size":471,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-05T07:16:39.055Z","etag":null,"topics":["command-line-tool","comments","curses-ui","file-management","freebsd","linux","openbsd","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patbeirne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-11-02T22:01:07.000Z","updated_at":"2024-12-09T01:57:16.000Z","dependencies_parsed_at":"2023-10-16T20:11:52.195Z","dependency_job_id":null,"html_url":"https://github.com/patbeirne/dirnotes","commit_stats":null,"previous_names":["patbeirne/dirnotes"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/patbeirne/dirnotes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbeirne%2Fdirnotes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbeirne%2Fdirnotes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbeirne%2Fdirnotes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbeirne%2Fdirnotes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patbeirne","download_url":"https://codeload.github.com/patbeirne/dirnotes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbeirne%2Fdirnotes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29045943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-tool","comments","curses-ui","file-management","freebsd","linux","openbsd","python3"],"created_at":"2024-09-26T13:21:50.113Z","updated_at":"2026-02-03T12:33:43.926Z","avatar_url":"https://github.com/patbeirne.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dirnotes\n\nTable of Contents\n----------------\n\n  * [SYNOPSIS](#synopsis)\n  * [USAGE](#usage)\n  * [INSTALLATION](#installation)\n    * [CONFIG FILE](#config-file)\n  * [LIMITATIONS](#limitations)\n  * [PROGRAMMER NOTES](#programmer-notes)\n    * [MacOS](#macos)\n  * [DEVELOPMENT STATUS](#development-status)\n  * [QUESTIONS](#questions)\n\n## SYNOPSIS\n\nThe **dirnotes** family of apps allows you to add a descriptive comment to a file. \nThe descriptions are stored in two places:\n\n * in the _xattr_ properties of the file\n * in a _database_ located in the user's home directory\n\n[The [MacOS](#macos) stores its comments in a similar way.]\n\nThe \u003ccode\u003e**dirnotes**\u003c/code\u003e app is a GUI app, using the Qt5 framework. \nAt startup, it displays the contents of the current directory, and the \ncomments associated with any of the files or directories. \nSimple mouse clicks allow you to add or edit comments, tunnel down \ninto directories, or rise up the file system. \nYou can copy or move files (_with_ comments), and \nchoose whether the _xattr_ or _database_ version of the comments \nhave display priority. \n\nThe \u003ccode\u003e**dirnotes-tui**\u003c/code\u003e is a very similar app, but uses the \n_curses_ framework to display its activity in a terminal window. \nThis can be handy if you have to work across a network, \nor if terminal apps are your preference.\n\nThe \u003ccode\u003e**dirnotes-cli**\u003c/code\u003e is a command line tool, \nwhich may be handy for scripting. This all can also do maintenance on the database.\n\n\u003cimg src=images/gui_sample.png alt=\"gui sample\" /\u003e\n\u003cimg src=images/tui_sample.png alt=\"tui sample\" /\u003e\n\n## USAGE\n\nThe \u003ccode\u003e**dirnotes**\u003c/code\u003e program displays usage and keystoke info \nwhen you press _F1_. The \u003ccode\u003e**dirnotes-tui**\u003c/code\u003e program display \nonscreen usage when you press the 'h' key, or _F1_. \nThe \u003ccode\u003e**dirnotes-cli**\u003c/code\u003e program has a man page.\n\nIn short, you navigate \u003ccode\u003e**dirnotes**\u003c/code\u003e and \n\u003ccode\u003e**dirnotes-tui**\u003c/code\u003e by using the up/down arrow keys, \n\\\u003center\\\u003e to enter into a directory. \nThe **-tui** version accepts _e_ for edit, _s_ for sort, _M_ to change \nbetween xattr/database priority.\n\nThe **\u003ccode\u003edirnotes-cli\u003c/code\u003e** has options \nfor _-l_ list and _-c_ create a comment. See also \u003ccode\u003edirnotes-cli.1\u003c/code\u003e \nman page.\n\nAll three apps in the **dirnotes** family have the ability to \ncopy/move files from the current directory, keeping the comments intact. \nAll three apps have the **-h** option which shows command line usage. \n \n## INSTALLATION\n\nEach of the 3 apps in the family is self contained. \nThe \u003ccode\u003e**dirnotes**\u003c/code\u003e app requires _Python3_ and the _Qt5_ framework. \nThe \u003ccode\u003e**dirnotes-tui**\u003c/code\u003e and \u003ccode\u003e**dirnotes-cli**\u003c/code\u003e apps \nsimply require _Python3_.\n\nSimply mark the 3 python files as executable and copy them into your \npath, to \u003ccode\u003e\\~/.local/bin/\u003c/code\u003e or \u003ccode\u003e/usr/local/bin/\u003c/code\u003e. \n\n        chmod a+x dirnotes dirnotes-tui dirnotes-cli\n        cp dirnotes dirnotes-tui dirnotes-cli \\~/.local/bin/\n \nFor a better GUI experience, copy \n\u003ccode\u003edirnotes.desktop\u003c/code\u003e to \u003ccode\u003e\\~/.local/share/applications\u003c/code\u003e and \n\u003ccode\u003edirnotes.xpm\u003c/code\u003e to \u003ccode\u003e\\~/.local/share/icons/\u003c/code\u003e \n\nIf you are using the command-line tool \u003ccode\u003e**dirnotes-cli**\u003c/code\u003e, \nyou can generate a man page using\n\n        pandoc -s -t man -o dirnotes-cli.1 dirnotes-cli.md\n\nand copy that to ```~/.local/share/man/man1```\n\n### CONFIG FILE\n\nBy default, the file **~/.config/dirnotes/dirnotes.conf** will be used to \nload the user's config. \nThis is a JSON file, with three attributes that are important:\n\n* xattr_tag (default: \u003ccode\u003euser.xdg.comment\u003c/code\u003e)\n* database (default: \u003ccode\u003e~/.local/share/dirnotes/dirnotes.db\u003c/code\u003e, sensible alt: \u003ccode\u003e/var/lib/dirnotes.db\u003c/code\u003e) \n* start_mode (_xattr_ or _db_ display priority)\n\nThe _config_file_ should be auto-generated the first time one of \nthe **dirnotes** apps is run.\n\n## LIMITATIONS \n\nThe file comments are located in two locations: a database, and in the \nxattr properties of the file. Each of these storage locations has its \nown benefits and limitations. These can be summed up: **_xattr_** comments\nfollow the iNode, **_database_** comments follow the file name.\n\n\n### xattr\n\nComments stored in the xattr properties can be copied/moved with the file, if you\nuse the correct options: \u003ccode\u003e**cp\u0026nbsp;-p\u0026nbsp;_src\u0026nbsp;dest_**\u003c/code\u003e. \nThe \u003ccode\u003e**mv**\u003c/code\u003e utility \nautomatically preserves _xattr_. Other programs can also be coerced into \nperserving _xattr_ properties:\n\n* \u003ccode\u003e**rsync**\u003c/code\u003e\n* \u003ccode\u003e**tar**\u003c/code\u003e\n* \u003ccode\u003e**mksquashfs**\u003c/code\u003e\n\nNot all file systems support xattr properties (vfat/exfat does not).\n\n_xattr_ comments may only be applied to files for which the user has _write_ permission.\n\nThe current implementation of \u003ccode\u003e**sshfs**\u003c/code\u003e and \u003ccode\u003e**scp**\u003c/code\u003e \ndo not support copying of _xattr_ properties. **Dropbox** type mounts are \nunlikely to support _xattr_ comments.\nIf you want to copy files to a remote machine and include the _xattr_ comments, use \u003ccode\u003e**rsync**\u003c/code\u003e with the _-X_ option. Or \u003ccode\u003e**tar**\u003c/code\u003e.\n\nSome 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.  \n\nRemovable 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.\n\n## database\n\nComments stored in the database work for all filesystem types \n(including vfat/exfat/sshfs)\n \nThe _database_ comments that are stored in \n\u003ccode\u003e~/.local/share/dirnotes/dirnotes.db\u003c/code\u003e are inherently associated \nwith a single user. If the _database_ is located in \n\u003ccode\u003e/var/lib/dirnotes.db\u003c/code\u003e, it can be shared by all the users in the system.\n\nFiles are indexed by their complete path name. Removable filesystems should be\nmounted in a consistent way, so that the complete path name is reproducable. \nSymlinks are _not_\ndereferenced, so they may have comments bound to them.\n\nComments stored in the database do not travel with the files when\nthey are moved or copied, unless using the **dirnotes** family of tools. \n\n_Database_ comments may be applied to any visible file, _even if they are readonly_. \nFor exmple, comments may be attached to the files in \u003ccode\u003e/usr/bin/\\*\u003c/code\u003e even though they are probably owned by _root_.\n\n## PROGRAMMER NOTES\n\nInstead of an API, here is how you can get directly at the underlying comment data. \nIf you intend to use the **dirnotes** apps, \ntry to keep the two versions of the comments in sync.\n\n  * xattr\n\nUse the commands  \n\n        xattr -l [filename]  \n\nto display the comments/author/date on a file. For example:  \n\n        $ xattr -l /etc/fstab\n        user.xdg.comment: controls the default mount bindings\n        user.xdg.comment.author: patb\n        user.xdg.comment.date: 2022-09-29 08:07:42\n\nThe other options on the **xattr** command line tool allow you to \nwrite (*xattr -w*) or delete (*xattr -d*) the comments.\n\n  * database\n\nThe comments are stored in an Sqlite3 database, usually \nlocated at \"~/.local/share/dirnotes/dirnotes.db\". \nThe database itself is contained within that file, and its schema is this:\n\n~~~~\n    CREATE TABLE dirnotes (name TEXT, date DATETIME, size INTEGER, comment TEXT, comment_date DATETIME, author TEXT)\n~~~~\n\n\n| field | usage | example |\n| -------- | -------- | -------- |\n| name   |       the long filename, using python's os.path.abspath() |   /home/patb/projects/dirnotes/README.md | \n|date    |      the file's modified date  |                             2020-01-13 09:25:40 |\n|size   |      the byte count of the file       |                      145  |\n|comment     |  a utf-8 string |                                         the readme for the GIT page | \n|comment_date | the date of the comment itself   |                      2020-10-03 22:30:19 |\n|author     |   the system name of the user who created the comment  |  patb | \n\n\nThe _date_ and _size_ fields reflect the file's modification date and size \nat the time of the last edit of the file comment, which is stored in _comment_date_.\n\nAs comments are editted or appended, new records are added to the database. \nOlder records are are not purged. This gives you a history of the comments, \nbut it means that fetching the most recent comment involves something like\n\n        SELECT * FROM dirnotes WHERE name=? ORDER BY comment_date DESC\n\nand just fetch the first record.\n\nThe database is created the first time one of the **dirnotes** apps is run.\n\n  * misc\n\nThe \u003ccode\u003e**dirnotes**\u003c/code\u003e gui app has a desktop icon built into the code. \nThere is not need for an external .icon file, but there is an .xpm file included\nin the project, which can be copied to \u003ccode\u003e~/.local/share/icons/\u003c/code\u003e\n\nThe 3 apps share a big block of common code. At this point, the code is embedded\nin each executable, but perhaps in the future it will be brought out as a library.\nI just like apps to be a single file I can copy to my various devices and servers,\nbut it does create a problem of keepint the 3 apps in sync.\n\n### comment date \u0026 author\n\nThe \u003ccode\u003ecopy()/move()\u003c/code\u003e methods that are built into the **dirnotes** library\nwill ask the operating system to copy/move the file _with_ xattr intact. \nThe entry in the database is created _at the time of invocation_. \nTherefore, the xattrs will reflect the original author+date on the comments, \nwhereas the database version is updated on each copy/move; \nthe dirnotes-comments details will therefor diverge over time.\n\nThere was _no_ consideration given for language translation. Email [me](mail:patb@pbeirne.com) if you want this, or can help.\n\nAll these apps only accomadate a single line comment. An embedded newline will \ncause unpredictable behaviour. \n\n### MacOS\n\nThe **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:\n\n  * in the xattr properties of the file  \n    * using a different xattr-tag (\u003ccode\u003ecom.apple.metadata:kMDItemFinderComment\u003c/code\u003e) \n    * the comment string is wrapped in a \u003ccode\u003epList\u003c/code\u003e\n  * in a database located in each directory  \n    * in the .DS-Store file\n \nThe user can examine the file comments by opening the GetInfo dialog, and scrolling down to \"Comment\"\n\nIf the Finder is used to copy/move files, the comments are moved properly \nto both destinations. If you use the os to copy/move the files, \nyou can ask that the xattr properties get moved, but the .DS-Store \nfile will not be updated. That means the Finder will not see \nfile comments on the destination file.\n\n**MacOS** has AppleScript, by which you can ask the Finder to perform the file copy/move. In this case, the comments are moved properly.\n\n## DEVELOPMENT STATUS\n\nEach app is a standalone file. That means there is a lot of redundancy between \nthe three apps. And there _may_ be some inconsistency.\n\n2022-10-04\n: All three apps are functioning and usable.  \n  The _config_file_ is fully implemented.  \n  Themes are not implemented.   \n  Comments are intended to be _utf-8_, but are _strings_ in some places.  \n  MacOS code is not written yet.   \n  The _help_ dialogs in \u003ccode\u003e**dirnotes-tui**\u003c/code\u003e are meagre.    \n  The _qt-gui_ app is working pretty well.  \n\n\n## QUESTIONS:\n\nThere are several open-ended questions that need to be answered. \nDoes anyone have an opinion?\n\n1. How important is multi-line comments?\n\n2. Is it ok to put the config file and database file buried in ~/.config and ~/.local? \n\n    These directories exist on computers with a gui/windowing system installed, \n    but don't neccessarily exist on headless servers. \n    Perhaps the default locations should be in the user directory? \n    (~/.dirnotes.conf and ~/.dirnotes.db)\n\n3. Who needs translations?\n\n4. Does anybody have a better edit-window for CURSES?\n\n5. What about storing the database _per directory_. That's what MacOS does (the .DS_Store file)\n\n    - PRO  \n        - copy of an _entire directory_ will transport the database with it  \n        - database stored on a remote directory (sshfs, nfs, etc) will work properly  \n        - the database only needs to store the basename, not the entire path name\n        - if a removable drive is remounted on a different mount point, it'll still work\n\n    - CON  \n        - won't work on directories where the user doesn't have write permission  \n        - so, for example, the user can't add comments to /usr/bin/\\*\n\n6. Is anyone interested in the MacOS version?\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatbeirne%2Fdirnotes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatbeirne%2Fdirnotes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatbeirne%2Fdirnotes/lists"}