git-annex-metadata

git-annex-metadata(1)        General Commands Manual       git-annex-metadata(1)



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 the particular content of a file,
       not to a particular filename on a particular git branch.  All files with
       the same content share the same metadata, which is stored in the git-
       annex branch. If a file is edited, old metadata will be copied to the new
       contents when you git-annex-add the edited 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.

       file matching options
              The git-annex-matching-options(1) can be used to specify files 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 with an output JSON object.

              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":[]}}

              Note that file matching options do not affect the files that are
              processed when in batch mode.

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>

                                                           git-annex-metadata(1)