80f1354685
Turns out that CommandStart actions do not have their exceptions caught, which is why the giveup was causing a crash. Mostly these actions do not do very much work on their own, but it does seem possible there are other commands whose CommandStart also throws an exception. So, my first attempt at a fix was to catch those exceptions. But, --json-error-messages then causes a difficulty, because in order to output a json error message, an action needs to have been started; that sets up the json object that the error message will be included in a field of. While it would be possible to output an object with just an error field, this would be json output of a format that the user has no reason to expect, that happens only in an exceptional circumstance. That is something I have always wanted to avoid with the json output; while git-annex man pages don't document what the json looks like, the output has always been made to be self-describing. Eg, it includes "error-messages":[] even when there's no errors. With that ruled out, it doesn't seem a good idea to catch CommandStart exceptions and display the error to stderr when --json-error-messages is set. And so I don't know if it makes sense to catch exceptions from that at all. Maybe I'd have a different opinion if --json-error-messages did not exist though. So instead, output a blank line like other batch commands do. This also leaves open the possibility of implementing support for matching object with metadata --json, which would also want to output a blank line when the input didn't match. Sponsored-by: Dartmouth College's DANDI project
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.
|