91ba0cc7fd
This reverts commit a325524454.
Turns out this was predicated on an incorrect belief that json output
didn't already sometimes lack the "key" field. Since json output already
can when `giveup` was used, it seems unncessary to add a whole new
option for this.
182 lines
4.8 KiB
Markdown
182 lines
4.8 KiB
Markdown
# 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.
|