1git-annex-metadata(1) General Commands Manual git-annex-metadata(1)
2
6 git-annex-metadata - sets or gets metadata of a file
7
9 git annex metadata [path ...]
10
12 The content of an annexed file can have any number of metadata fields
13 attached to it to describe it. Each metadata field can in turn have any
14 number of values.
15 This command can be used to set metadata, or show the currently set
17 metadata.
18 When run without any -s or -t parameters, displays the current meta‐
20 data.
21 Each metadata field has its own "field-lastchanged" metadata, which
23 contains the date the field was last changed. Unlike other metadata,
24 this cannot be directly modified by this command. It is updated auto‐
25 matically.
26 Note that the metadata is attached to the particular content of a file,
28 not to a particular filename on a particular git branch. More pre‐
29 cisely, metadata is attached to the key used for the file, which can
30 reflect file contents and/or name, depending on the key-value backend
31 used for the file. All files with the same key share the same meta‐
32 data, which is stored in the git-annex branch. If a file is edited, old
33 metadata will be copied to the new key when you git-annex-add the
34 edited file. Note also that changes to a file's git-annex metadata
35 will not be reflected in the git log of the file, since they are stored
36 on the git-annex branch. To attach metadata to a particular path,
37 rather than a particular key, use .gitattributes .
38
40 -g field / --get field
41 Get the value(s) of a single field.
43 The values will be output one per line, with no other output, so
45 this is suitable for use in a script.
46 -s field=value / --set field=value
48 Set a field's value, removing any old values.
49 -s field+=value / --set field+=value
51 Add an additional value, preserving any old values.
52 -s field?=value / --set field?=value
54 Set a value, but only if the field does not already have a value
55 set.
56 -s field-=value / --set field-=value
58 Remove a value from a field, leaving any other values that the
59 field has set.
60 -r field / --remove field
62 Remove all current values of the field.
63 -t tag / --tag tag
65 Set a tag. Note that a tag is just a value of the "tag" field.
66 -u tag / --unset tag
68 Unset a tag.
69 --remove-all
71 Remove all metadata from the specified files.
72 When a file is modified and the new version added, git-annex
74 will copy over the metadata from the old version of the file. In
75 situations where you don't want that copied metadata, you can
76 use this option to remove it.
77 --force
79 By default, git annex metadata refuses to recursively set meta‐
80 data throughout the files in a directory. This option enables
81 such recursive setting.
82 file matching options
84 The git-annex-matching-options(1) can be used to specify files
85 to act on.
86 --all -A
88 Specify instead of a file to get/set metadata on all known keys.
89 --branch=ref
91 Specify instead of a file to get/set metadata on all files in
92 the specified branch or treeish.
93 --unused
95 Specify instead of a file to get/set metadata on files found by
96 last run of git-annex unused.
97 --key=keyname
99 Specify instead of a file to get/set metadata of the specified
100 key.
101 --json Enable JSON output (and input). Each line is a JSON object.
103 The format of the JSON objects changed in git-annex version
105 6.20160726.
106 Example of the new format:
108 {"command":"meta‐
110 data","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","suc‐
111 cess":true}
112 Example of the old format, which lacks the inner fields object:
114 {"command":"meta‐
116 data","file":"foo","key":"...","author":["bar"],...,"note":"...","suc‐
117 cess":true}
118 --json-error-messages
120 Messages that would normally be output to standard error are
121 included in the json instead.
122 --batch
124 Enables batch mode, which can be used to both get, store, and
125 unset metadata for multiple files or keys.
126 Batch currently only supports JSON input. So, you must enable
128 --json along with --batch.
129 In batch mode, git-annex reads lines from stdin, which contain
131 JSON objects. It replies to each input with an output JSON
132 object.
133 The format of the JSON sent to git-annex can be the same as the
135 JSON that it outputs. Or, a simplified version. Only the "file"
136 (or "key") field is actually necessary.
137 For example, to get the current metadata of file foo:
139 {"file":"foo"}
141 To get the current metadata of the key k:
143 {"key":"k"}
145 Any metadata fields included in the JSON object will be stored,
147 replacing whatever values the fields had before. To unset a
148 field, include it with an empty list of values.
149 To change the author of file foo to bar:
151 {"file":"foo","fields":{"author":["bar"]}}
153 To remove the author of file foo:
155 {"file":"foo","fields":{"author":[]}}
157 Note that file matching options do not affect the files that are
159 processed when in batch mode.
160
162 To set some tags on a file and also its author:
163 git annex metadata annexscreencast.ogv -t video -t screencast -s
165 author+=Alice
166
168 git-annex(1)
169 git-annex-view(1)
171
173 Joey Hess <id@joeyh.name>
174 git-annex-metadata(1)