git-annex-metadata - sets or gets metadata of a file
git annex metadata [path ...]
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.
- -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.
To set some tags on a file and also its author:
git annex metadata annexscreencast.ogv -t video -t screencast -s
author+=Alice
Joey Hess <id@joeyh.name>