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.

       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)