git-annex/ metadata

git-annex allows you to store arbitrary metadata about the content of files stored in the git-annex repository. The metadata is stored in the `git-annex` branch, and so is automatically kept in sync with the rest of git-annex's state, such as location tracking information.

Some of the things you can do with metadata include:

- Using `git annex metadata file` to show all the metadata associated with a file.
- metadata driven views
- Limiting the files git-annex commands act on to those with or without particular metadata. For example `git annex find --metadata tag=foo --or --metadata tag=bar`
- Using it in preferred content expressions. For example "metadata=tag=important or not metadata=author=me"
- Editing and viewing it with git-annex-metadata-gui, a gui for metadata operations.

Each file (actually the underlying key) can have any number of metadata fields, which each can have any number of values. For example, to tag files, the `tag` field is typically used, with values set to each tag that applies to the file.

The field names are limited to alphanumerics (and `[_-.]`), and are case insensitive. The metadata values can contain absolutely anything you like -- but you're recommended to keep it simple and reasonably short

Here are some metadata fields that git-annex has special support for:

- `tag` - With each tag being a different value.
- `year`, `month` - When this particular version of the file came into being.
- `$field-lastchanged` - This is automatically maintained for each field that's set, and gives the date and time of the most recent change to the field. It cannot be modified directly.
- `lastchanged` - This is automatically maintained, giving the data and time of the last change to any of the metadata of a file.

To make git-annex automatically set the year and month when adding files, run `git config annex.genmetadata true`. Also, see automatically adding metadata.

git-annex's metadata can be updated in a distributed fashion. For example, two users, each with their own clone of a repository, can set and unset metadata at the same time, even for the same field of the same file. When they push their changes, `git annex merge` will combine their metadata changes in a consistent and (probably) intuitive way.

See the metadata design page for more details.

TODO written

@joeyh, yes, it would overwrite all metadata. The idea would be to export with --json, manipulate, import…

http://git-annex.branchable.com/todo/ability_to_set_metadata_from_json/?updated

Comment by madduck — Tue Jul 22 18:11:47 2025
comment 4

@madduck, you could file a todo if you want about that.

However, I have my doubts; if the json supposed to include the full set of metadata for the file? If so, that seems a potentially expensive interface. If not, it would be hard to tell when metadata should be deleted, or when multiple values are being set, vs a value being changed.

The current interface to set metadata deals with these possibilities in a compact and sensible way.

Comment by joey — Tue Jul 22 18:11:47 2025
Overwriting metadata from json
I see that --json allows me to export metadata in a well-parseable format. I'd really like to be able to pipe this into a file, edit the file and then pipe it back to git-annex, causing the metadata for each file to be rewritten from the JSON input. This would make it trivial to write an external metadata editor (like vidir, vorbistagedit, git annex vicfg even… etc.)
Comment by madduck — Tue Jul 22 18:11:47 2025
comment 2

I've made `git annex metadata --key` work.

I'll wait and see what you come up with your special remote and add something to the protocol later if it makes sense.

Comment by http://joeyh.name/ — Tue Jul 22 18:11:47 2025
access metadata by key?

I'm hacking around with using metadata from an external special remote. Those work with keys, not files, so one option would be to add a GETMETADATA to the protocol. It also seems like it would not be too hard to add an option to "git annex metadata" to take a key rather than a file.

Comment by bremner — Tue Jul 22 18:11:47 2025
Comments on this page are closed.