git-annex/ git-annex-metadata

# NAME

git-annex metadata - sets or gets metadata of a file

# SYNOPSIS

git annex metadata `[path ...]`

# DESCRIPTION

The content of an annexed file can have any number of metadata fields attached to it to describe it. Each metadata field can in turn have any number of values.

This command can be used to set metadata, or show the currently set metadata.

When run without any -s or -t parameters, displays the current metadata.

Each metadata field has its own "field-lastchanged" metadata, which contains the date the field was last changed. Unlike other metadata, this cannot be directly modified by this command. It is updated automatically.

Note that the metadata is attached to git-annex key corresponding to the content of a file, not to a particular filename on a particular git branch. All files with the same key share the same metadata, which is stored in the git-annex branch. If a file is modified, the metadata of the previous version will be copied to the new key when git-annex adds the modified file.

# OPTIONS

- `-g field` / `--get field`

  Get the value(s) of a single field.

  The values will be output one per line, with no other output, so this is suitable for use in a script.

- `-s field=value` / `--set field=value`

  Set a field's value, removing any old values.

- `-s field+=value` / `--set field+=value`

  Add an additional value, preserving any old values.

- `-s field?=value` / `--set field?=value`

  Set a value, but only if the field does not already have a value set.

- `-s field-=value` / `--set field-=value`

  Remove a value from a field, leaving any other values that the field has set.

- `-r field` / `--remove field`

  Remove all current values of the field.

- `-t tag` / `--tag tag`

  Set a tag. Note that a tag is just a value of the "tag" field.

- `-u tag` / `--unset tag`

  Unset a tag.

- `--remove-all`

  Remove all metadata from the specified files.

  When a file is modified and the new version added, git-annex will copy over the metadata from the old version of the file. In situations where you don't want that copied metadata, you can use this option to remove it.

- `--force`

  By default, `git annex metadata` refuses to recursively set metadata throughout the files in a directory. This option enables such recursive setting.

- matching options

  The git-annex-matching-options(1) can be used to control what to act on.

- `--all` `-A`

  Specify instead of a file to get/set metadata on all known keys.

- `--branch=ref`

  Specify instead of a file to get/set metadata on all files in the specified branch or treeish.

- `--unused`

  Specify instead of a file to get/set metadata on files found by last run of git-annex unused.

- `--key=keyname`

  Specify instead of a file to get/set metadata of the specified key.

- `--json`

  Enable JSON output (and input). Each line is a JSON object.

  The format of the JSON objects changed in git-annex version 6.20160726.

  Example of the new format:

  {"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true}

  Example of the old format, which lacks the inner fields object:

  {"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true}

- `--json-error-messages`

  Messages that would normally be output to standard error are included in the JSON instead.

- `--batch`

  Enables batch mode, which can be used to both get, store, and unset metadata for multiple files or keys.

  Batch currently only supports JSON input. So, you must enable `--json` along with `--batch`.

  In batch mode, git-annex reads lines from stdin, which contain JSON objects. It replies to each input annexed file with an output JSON object. (But if the file is not an annexed file, an empty line will be output.)

  The format of the JSON sent to git-annex can be the same as the JSON that it outputs. Or, a simplified version. Only the "file" (or "key") field is actually necessary.

  For example, to get the current metadata of file foo:

  {"file":"foo"}

  To get the current metadata of the key k:

  {"key":"k"}

  Any metadata fields included in the JSON object will be stored, replacing whatever values the fields had before. To unset a field, include it with an empty list of values.

  To change the author of file foo to bar:

  {"file":"foo","fields":{"author":["bar"]}}

  To remove the author of file foo:

  {"file":"foo","fields":{"author":[]}}

- Also the git-annex-common-options(1) can be used.

# EXAMPLES

To set some tags on a file and also its author:

    git annex metadata annexscreencast.ogv -t video -t screencast -s author+=Alice

# SEE ALSO

git-annex(1)

git-annex-view(1)

# AUTHOR

Joey Hess id@joeyh.name

Warning: Automatically converted into a man page by mdwn2man. Edit with care.

comment 9
Ok thank you! If you also have names of music playes that can actually read tags from git annex, let me know!
Comment by tobiasBora — Wed Oct 29 14:05:27 2025
comment 8

See git-annex-matching-options for ways to query for metadata.

For example:

    git annex find --metadata tag=foo --or --metadata tag=bar

Comment by joey — Wed Oct 29 14:05:27 2025
Get list of files with specific metadata

Hello, I would like to know, is it possible to get in one command all files with a particular tag, or a list of tags (like "give all files that have tag foo or tag bar"). Note that I don't want to change the current view. Also, are you aware of any music player that could use these tags to find some songs to play and add them to some playlist?

Comment by tobiasBora — Wed Oct 29 14:05:27 2025
meanwhile

I am thinking about some abominations to workaround inability to specify smth like

    licenses/* annex.commit.metadata=(distribution-restrictions=sensitive)

in `.gitattributes`. IMHO by limiting to `.commit` the scope when annex should add metadata becomes clear. Sure thing it could leak across files with the same content (0-length files are most prone) but it is unrelated IMHO since a direct call to `git annex metadata licenses/* -s ...` would have the same effect anyways.

Comment by yarikoptic — Wed Oct 29 14:05:27 2025
comment 5

I think I added that line to the docs, and yes, it's not for git-annex metadata. I'll clarify the page.

I'm not sure there is a well-defined way to set git-annex metadata via .gitattributes, given the different semantics of git-annex metadata (it's tied to timestamps, and is shared between all branches). Maybe one could define some unified-metadata, which interprets git-annex metadata on an annexed file as implicitly setting .gitattributes for that file in that directory.

Comment by Ilya_Shlyakhter — Wed Oct 29 14:05:27 2025
comment 4

I did not write that, Ilya did. I agree that it was confusing that it was talking about some entirely different kind of metadata, and have reworded it.

Comment by joey — Wed Oct 29 14:05:27 2025
question about .gitattributes

Joey, I feel like I have asked it before, but can't quickly search it up, so asking again (sorry if repeating). By

> To attach metadata to a particular path, rather than a particular key, use .gitattributes .

you meant attaching some other metadata, not really "git-annex" metadata, right? Or there is a way to specify metadata `key=value` pairs to be attached to annexed files, e.g. smth like

    *_scans.json annex.metadata=(distribution-restrictions=sensitive)

?

Comment by yarikoptic — Wed Oct 29 14:05:27 2025
comment 2

The only risk in doing this is that if you somehow later add a file that actually uses that key it will have this metadata.

There's no garbage collection of metadata except for keys that have been marked as dead with `git annex dead`.

Comment by joey — Wed Oct 29 14:05:27 2025
comment 11

@AlbertZeyer, this man page says it is "stored in the git-annex branch."

That branch is synced whenever you push it, which git-annex sync does do, but git push can also be set up to do. The branch is automatically merged.

Comment by joey — Wed Oct 29 14:05:27 2025
comment 10

From this man page, it's not totally clear how/where the metadata is stored. Is it inside the Git repo (i.e. as regular file), or inside the Annex, or somewhere else? Is this information synced when you do `git push` (as part of Git), or via `git annex sync`?

How does it resolve any conflicts?

Is the metadata itself under version control? (If it is in Git itself, then clearly yes, but that's not clear to me.)

Comment by AlbertZeyer — Wed Oct 29 14:05:27 2025
adding metadata to keys that don't point to any contents is ok, correct?

I want to store a simple mapping in git-annex on the git-annex branch, from string keys to values. I figured I can just do git annex metadata --key=WORM-s0-m0--mykey -s myfield+=myvalue and after git annex sync these mappings will propagate to copies of the repo. But the keys won't point to any file in any remote. Will that break anything in git-annex? Will they get garbage-collected automatically in some circumstances?

Comment by https://me.yahoo.com/a/iOGTltEpmOTQ.xZ99NFP5c7Zdcc-#6a7ba — Wed Oct 29 14:05:27 2025
Comments on this page are closed.