1git-annex-preferred-content(1G)eneral Commands Manugailt-annex-preferred-content(1)
2
6 git-annex-preferred-content - which files are wanted in a repository
7
9 Each repository has a preferred content setting, which specifies con‐
10 tent that the repository wants to have present. These settings can be
11 configured using git annex vicfg or git annex wanted. They are used by
12 the --auto option, by git annex sync --content, and by the git-annex
13 assistant.
14 While preferred content expresses a preference, it can be overridden by
16 simply using git annex drop. On the other hand, required content set‐
17 tings are enforced; git annex drop will refuse to drop a file if doing
18 so would violate its required content settings. A repository's required
19 content can be configured using git annex vicfg or git annex required.
20
22 Preferred content expressions use a similar syntax to the git-an‐
23 nex-matching-options(1), without the dashes. For example:
24 exclude=archive/* and (include=*.mp3 or smallerthan=1mb)
26 The idea is that you write an expression that files are matched
28 against. If a file matches, the repository wants to store its content.
29 If it doesn't, the repository wants to drop its content (if there are
30 enough copies elsewhere to allow removing it).
31
33 include=glob / exclude=glob
34 Match files to include, or exclude.
36 While the command-line options --include=glob and --exclude=glob
38 match files relative to the current directory, preferred content
39 expressions match files relative to the top of the git reposi‐
40 tory.
41 A glob is something like foo.* or b?r. Globs can also contain
43 character classes, like foo[Bb]ar, as well as additional POSIX
44 character classes like [[:space:]]. Which is useful, since a
45 glob in a preferred content expression cannot contain spaces.
46 See the glob(7) man page for more about globs.
47 For example, suppose you put files into archive directories when
49 you're done with them. Then you could configure your laptop to
50 prefer to not retain those files, like this: exclude=*/archive/*
51 When a subdirectory is being exported or imported to a special
53 remote (see git-annex-export(1)) and git-annex-import(1), these
54 match relative to the top of the subdirectory.
55 Note that, when a command is run with the --all option, or in a
57 bare repository, there is no filename associated with an annexed
58 object, and so "include=" and "exclude=" will not match.
59 copies=number
61 Matches only files that git-annex believes to have the specified
62 number of copies, or more. Note that it does not check remotes
63 to verify that the copies still exist.
64 To decide if content should be dropped, git-annex evaluates the
66 preferred content expression under the assumption that the con‐
67 tent has *already* been dropped. If the content would not be
68 wanted then, the drop can be done. So, for example, copies=2 in
69 a preferred content expression lets content be dropped only when
70 there are currently 3 copies of it, including the repo it's be‐
71 ing dropped from. This is different than running git annex drop
72 --copies=2, which will drop files that currently have 2 copies.
73 copies=trustlevel:number
75 Matches only files that git-annex believes have the specified
76 number copies, on remotes with the specified trust level. For
77 example, copies=trusted:2
78 To match any trust level at or higher than a given level, use
80 trustlevel+. For example, copies=semitrusted+:2
81 copies=groupname:number
83 Matches only files that git-annex believes have the specified
84 number of copies, on remotes in the specified group. For exam‐
85 ple, copies=archive:2
86 Preferred content expressions have no equivalent to the --in op‐
88 tion, but groups can accomplish similar things. You can add
89 repositories to groups, and match against the groups in a pre‐
90 ferred content expression. So rather than --in=usbdrive, put all
91 the USB drives into a "transfer" group, and use copies=trans‐
92 fer:1
93 lackingcopies=number
95 Matches only files that git-annex believes need the specified
96 number or more additional copies to be made in order to satisfy
97 their numcopies settings.
98 approxlackingcopies=number
100 Like lackingcopies, but does not look at .gitattributes an‐
101 nex.numcopies settings. This makes it significantly faster.
102 inbackend=backendname
104 Matches only files whose content is stored using the specified
105 key-value backend.
106 See git-annex-backends(1) for information about available back‐
108 ends.
109 securehash
111 Matches only files whose content is hashed using a cryptographi‐
112 cally secure function.
113 inallgroup=groupname
115 Matches only files that git-annex believes are present in all
116 repositories in the specified group.
117 smallerthan=size / largerthan=size
119 Matches only files whose content is smaller than, or larger than
120 the specified size.
121 The size can be specified with any commonly used units, for ex‐
123 ample, "0.5 gb" or "100 KiloBytes"
124 metadata=field=glob
126 Matches only files that have a metadata field attached with a
127 value that matches the glob. The values of metadata fields are
128 matched case insensitively.
129 A glob is something like foo.* or b?r. Globs can also contain
131 character classes, like foo[Bb]ar, as well as additional POSIX
132 character classes like [[:space:]]. Which is useful, since a
133 glob in a preferred content expression cannot contain spaces.
134 See the glob(7) man page for more about globs.
135 To match a tag "done", use metadata=tag=done
137 To match author metadata, use metadata=author=*Smith
139 metadata=field<number / metadata=field>number
141 metadata=field<=number / metadata=field>=number
143 Matches only files that have a metadata field attached with a
144 value that is a number and is less than or greater than the
145 specified number.
146 To match PDFs with between 100 and 200 pages (assuming something
148 has set that metadata), use metadata=pagecount>=100 and meta‐
149 data=pagecount<=200
150 present
152 Makes content be wanted if it's present, but not otherwise.
153 This leaves it up to you to use git-annex manually to move con‐
155 tent around. You can use this to avoid preferred content set‐
156 tings from affecting a subdirectory. For example: auto/* or (in‐
157 clude=ad-hoc/* and present)
158 Note that not present is a very bad thing to put in a preferred
160 content expression. It'll make it want to get content that's not
161 present, and drop content that is present! Don't go there..
162 inpreferreddir
164 Makes content be preferred if it's in a directory (located any‐
165 where in the tree) with a particular name.
166 The name of the directory can be configured using git annex en‐
168 ableremote $remote preferreddir=$dirname
169 (If no directory name is configured, it uses "public" by de‐
171 fault.)
172 Note that, when a command is run with the --all option, or in a
174 bare repository, there is no filename associated with an annexed
175 object, and so "inpreferreddir" will not match.
176 standard
178 git-annex comes with some built-in preferred content expres‐
179 sions, that can be used with repositories that are in some stan‐
180 dard groups such as "client" and "transfer".
181 When a repository is in exactly one such group, you can use the
183 "standard" keyword in its preferred content expression, to match
184 whatever content the group's expression matches.
185 Most often, the whole preferred content expression is simply
187 "standard". But, you can do more complicated things, for exam‐
188 ple: standard or include=otherdir/*
189 groupwanted
191 The "groupwanted" keyword can be used to refer to a preferred
192 content expression that is associated with a group, as long as
193 there is exactly one such expression amoung the groups a reposi‐
194 tory is in. This is like the "standard" keyword, but you can
195 configure the preferred content expressions using git annex
196 groupwanted.
197 When writing a groupwanted preferred content expression, you can
199 use all the keywords documented here, including "standard".
200 (But not "groupwanted".)
201 For example, to make a variant of the standard client preferred
203 content expression that does not want files in the "out" direc‐
204 tory, you could run: git annex groupwanted client "standard and
205 exclude=out/*"
206 Then repositories that are in the client group and have their
208 preferred content expression set to "groupwanted" will use that,
209 while other client repositories that have their preferred con‐
210 tent expression set to "standard" will use the standard expres‐
211 sion.
212 Or, you could make a new group, with your own custom preferred
214 content expression tuned for your needs, and every repository
215 you put in this group and make its preferred content be "group‐
216 wanted" will use it.
217 For example, the archive group only wants to archive 1 copy of
219 each file, spread among every repository in the group. Here's
220 how to configure a group named redundantarchive, that instead
221 wants to contain 3 copies of each file:
222 git annex groupwanted redundantarchive "not (copies=redun‐
224 dantarchive:3)"
225 for repo in foo bar baz; do
226 git annex group $repo redundantarchive
227 git annex wanted $repo groupwanted
228 done
229 unused Matches only keys that git annex unused has determined to be un‐
231 used.
232 This is related the the --unused option. However, putting un‐
234 used in a preferred content expression doesn't make git-annex
235 consider those unused keys. So when git-annex is only checking
236 preferred content expressions against files in the repository
237 (which are obviously used), unused in a preferred content ex‐
238 pression won't match anything.
239 So when is unused useful in a preferred content expression?
241 Using git annex sync --content --all will operate on all files,
243 including unused ones, and take unused in preferred content ex‐
244 pressions into account.
245 The git-annex assistant periodically scans for unused files, and
247 moves them to some repository whose preferred content expression
248 says it wants them. (Or, if annex.expireunused is set, it may
249 just delete them.)
250 anything
252 Always matches.
253 nothing
255 Never matches. (Same as "not anything")
256 not expression
258 Inverts what the expression matches. For example, not in‐
259 clude=archive/* is the same as exclude=archive/*
260 and / or / ( expression )
262 These can be used to build up more complicated expressions.
263
265 To check at the command line which files are matched by a repository's
266 preferred content settings, you can use the --want-get and --want-drop
267 options.
268 For example, git annex find --want-get --not --in . will find all the
270 files that git annex get --auto will want to get, and git annex find
271 --want-drop --in . will find all the files that git annex drop --auto
272 will want to drop.
273
275 git-annex(1)
276 git-annex-vicfg(1)
278 git-annex-wanted(1)
280 <https://git-annex.branchable.com/preferred_content/>
282 <https://git-annex.branchable.com/preferred_content/standard_groups/>
284
286 Joey Hess <id@joeyh.name>
287 <http://git-annex.branchable.com/>
289 git-annex-preferred-content(1)