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 For example, suppose you put files into archive directories when
43 you're done with them. Then you could configure your laptop to
44 prefer to not retain those files, like this: exclude=*/archive/*
45 When a subdirectory is being exported or imported to a special
47 remote (see git-annex-export(1)) and git-annex-import(1), these
48 match relative to the top of the subdirectory.
49 Note that, when a command is run with the --all option, or in a
51 bare repository, there is no filename associated with an annexed
52 object, and so "include=" and "exclude=" will not match.
53 copies=number
55 Matches only files that git-annex believes to have the specified
56 number of copies, or more. Note that it does not check remotes
57 to verify that the copies still exist.
58 To decide if content should be dropped, git-annex evaluates the
60 preferred content expression under the assumption that the con‐
61 tent has *already* been dropped. If the content would not be
62 wanted then, the drop can be done. So, for example, copies=2 in
63 a preferred content expression lets content be dropped only when
64 there are currently 3 copies of it, including the repo it's be‐
65 ing dropped from. This is different than running git annex drop
66 --copies=2, which will drop files that currently have 2 copies.
67 copies=trustlevel:number
69 Matches only files that git-annex believes have the specified
70 number copies, on remotes with the specified trust level. For
71 example, copies=trusted:2
72 To match any trust level at or higher than a given level, use
74 trustlevel+. For example, copies=semitrusted+:2
75 copies=groupname:number
77 Matches only files that git-annex believes have the specified
78 number of copies, on remotes in the specified group. For exam‐
79 ple, copies=archive:2
80 Preferred content expressions have no equivalent to the --in op‐
82 tion, but groups can accomplish similar things. You can add
83 repositories to groups, and match against the groups in a pre‐
84 ferred content expression. So rather than --in=usbdrive, put all
85 the USB drives into a "transfer" group, and use copies=trans‐
86 fer:1
87 lackingcopies=number
89 Matches only files that git-annex believes need the specified
90 number or more additional copies to be made in order to satisfy
91 their numcopies settings.
92 approxlackingcopies=number
94 Like lackingcopies, but does not look at .gitattributes an‐
95 nex.numcopies settings. This makes it significantly faster.
96 inbackend=backendname
98 Matches only files whose content is stored using the specified
99 key-value backend.
100 See git-annex-backends(1) for information about available back‐
102 ends.
103 securehash
105 Matches only files whose content is hashed using a cryptographi‐
106 cally secure function.
107 inallgroup=groupname
109 Matches only files that git-annex believes are present in all
110 repositories in the specified group.
111 smallerthan=size / largerthan=size
113 Matches only files whose content is smaller than, or larger than
114 the specified size.
115 The size can be specified with any commonly used units, for ex‐
117 ample, "0.5 gb" or "100 KiloBytes"
118 metadata=field=glob
120 Matches only files that have a metadata field attached with a
121 value that matches the glob. The values of metadata fields are
122 matched case insensitively.
123 To match a tag "done", use metadata=tag=done
125 To match author metadata, use metadata=author=*Smith
127 metadata=field<number / metadata=field>number
129 metadata=field<=number / metadata=field>=number
131 Matches only files that have a metadata field attached with a
132 value that is a number and is less than or greater than the
133 specified number.
134 To match PDFs with between 100 and 200 pages (assuming something
136 has set that metadata), use metadata=pagecount>=100 and meta‐
137 data=pagecount<=200
138 present
140 Makes content be wanted if it's present, but not otherwise.
141 This leaves it up to you to use git-annex manually to move con‐
143 tent around. You can use this to avoid preferred content set‐
144 tings from affecting a subdirectory. For example: auto/* or (in‐
145 clude=ad-hoc/* and present)
146 Note that not present is a very bad thing to put in a preferred
148 content expression. It'll make it want to get content that's not
149 present, and drop content that is present! Don't go there..
150 inpreferreddir
152 Makes content be preferred if it's in a directory (located any‐
153 where in the tree) with a particular name.
154 The name of the directory can be configured using git annex en‐
156 ableremote $remote preferreddir=$dirname
157 (If no directory name is configured, it uses "public" by de‐
159 fault.)
160 Note that, when a command is run with the --all option, or in a
162 bare repository, there is no filename associated with an annexed
163 object, and so "inpreferreddir" will not match.
164 standard
166 git-annex comes with some built-in preferred content expres‐
167 sions, that can be used with repositories that are in some stan‐
168 dard groups such as "client" and "transfer".
169 When a repository is in exactly one such group, you can use the
171 "standard" keyword in its preferred content expression, to match
172 whatever content the group's expression matches.
173 Most often, the whole preferred content expression is simply
175 "standard". But, you can do more complicated things, for exam‐
176 ple: standard or include=otherdir/*
177 groupwanted
179 The "groupwanted" keyword can be used to refer to a preferred
180 content expression that is associated with a group, as long as
181 there is exactly one such expression amoung the groups a reposi‐
182 tory is in. This is like the "standard" keyword, but you can
183 configure the preferred content expressions using git annex
184 groupwanted.
185 When writing a groupwanted preferred content expression, you can
187 use all the keywords documented here, including "standard".
188 (But not "groupwanted".)
189 For example, to make a variant of the standard client preferred
191 content expression that does not want files in the "out" direc‐
192 tory, you could run: git annex groupwanted client "standard and
193 exclude=out/*"
194 Then repositories that are in the client group and have their
196 preferred content expression set to "groupwanted" will use that,
197 while other client repositories that have their preferred con‐
198 tent expression set to "standard" will use the standard expres‐
199 sion.
200 Or, you could make a new group, with your own custom preferred
202 content expression tuned for your needs, and every repository
203 you put in this group and make its preferred content be "group‐
204 wanted" will use it.
205 For example, the archive group only wants to archive 1 copy of
207 each file, spread among every repository in the group. Here's
208 how to configure a group named redundantarchive, that instead
209 wants to contain 3 copies of each file:
210 git annex groupwanted redundantarchive "not (copies=redun‐
212 dantarchive:3)"
213 for repo in foo bar baz; do
214 git annex group $repo redundantarchive
215 git annex wanted $repo groupwanted
216 done
217 unused Matches only keys that git annex unused has determined to be un‐
219 used.
220 This is related the the --unused option. However, putting un‐
222 used in a preferred content expression doesn't make git-annex
223 consider those unused keys. So when git-annex is only checking
224 preferred content expressions against files in the repository
225 (which are obviously used), unused in a preferred content ex‐
226 pression won't match anything.
227 So when is unused useful in a preferred content expression?
229 Using git annex sync --content --all will operate on all files,
231 including unused ones, and take unused in preferred content ex‐
232 pressions into account.
233 The git-annex assistant periodically scans for unused files, and
235 moves them to some repository whose preferred content expression
236 says it wants them. (Or, if annex.expireunused is set, it may
237 just delete them.)
238 anything
240 Always matches.
241 nothing
243 Never matches. (Same as "not anything")
244 not expression
246 Inverts what the expression matches. For example, not in‐
247 clude=archive/* is the same as exclude=archive/*
248 and / or / ( expression )
250 These can be used to build up more complicated expressions.
251
253 To check at the command line which files are matched by a repository's
254 preferred content settings, you can use the --want-get and --want-drop
255 options.
256 For example, git annex find --want-get --not --in . will find all the
258 files that git annex get --auto will want to get, and git annex find
259 --want-drop --in . will find all the files that git annex drop --auto
260 will want to drop.
261
263 git-annex(1)
264 git-annex-vicfg(1)
266 git-annex-wanted(1)
268 <https://git-annex.branchable.com/preferred_content/>
270 <https://git-annex.branchable.com/preferred_content/standard_groups/>
272
274 Joey Hess <id@joeyh.name>
275 <http://git-annex.branchable.com/>
277 git-annex-preferred-content(1)