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-
23 annex-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
65 being dropped from. This is different than running git annex
66 drop --copies=2, which will drop files that currently have 2
67 copies.
68 copies=trustlevel:number
70 Matches only files that git-annex believes have the specified
71 number copies, on remotes with the specified trust level. For
72 example, copies=trusted:2
73 To match any trust level at or higher than a given level, use
75 trustlevel+. For example, copies=semitrusted+:2
76 copies=groupname:number
78 Matches only files that git-annex believes have the specified
79 number of copies, on remotes in the specified group. For exam‐
80 ple, copies=archive:2
81 Preferred content expressions have no equivalent to the --in
83 option, but groups can accomplish similar things. You can add
84 repositories to groups, and match against the groups in a pre‐
85 ferred content expression. So rather than --in=usbdrive, put all
86 the USB drives into a "transfer" group, and use copies=trans‐
87 fer:1
88 lackingcopies=number
90 Matches only files that git-annex believes need the specified
91 number or more additional copies to be made in order to satisfy
92 their numcopies settings.
93 approxlackingcopies=number
95 Like lackingcopies, but does not look at .gitattributes
96 annex.numcopies settings. This makes it significantly faster.
97 inbackend=name
99 Matches only files whose content is stored using the specified
100 key-value backend.
101 securehash
103 Matches only files whose content is hashed using a cryptographi‐
104 cally secure function.
105 inallgroup=groupname
107 Matches only files that git-annex believes are present in all
108 repositories in the specified group.
109 smallerthan=size / largerthan=size
111 Matches only files whose content is smaller than, or larger than
112 the specified size.
113 The size can be specified with any commonly used units, for
115 example, "0.5 gb" or "100 KiloBytes"
116 metadata=field=glob
118 Matches only files that have a metadata field attached with a
119 value that matches the glob. The values of metadata fields are
120 matched case insensitively.
121 To match a tag "done", use metadata=tag=done
123 To match author metadata, use metadata=author=*Smith
125 metadata=field<number / metadata=field>number
127 metadata=field<=number / metadata=field>=number
129 Matches only files that have a metadata field attached with a
130 value that is a number and is less than or greater than the
131 specified number.
132 To match PDFs with between 100 and 200 pages (assuming something
134 has set that metadata), use metadata=pagecount>=100 and meta‐
135 data=pagecount<=200
136 present
138 Makes content be wanted if it's present, but not otherwise.
139 This leaves it up to you to use git-annex manually to move con‐
141 tent around. You can use this to avoid preferred content set‐
142 tings from affecting a subdirectory. For example: auto/* or
143 (include=ad-hoc/* and present)
144 Note that not present is a very bad thing to put in a preferred
146 content expression. It'll make it want to get content that's not
147 present, and drop content that is present! Don't go there..
148 inpreferreddir
150 Makes content be preferred if it's in a directory (located any‐
151 where in the tree) with a particular name.
152 The name of the directory can be configured using git annex
154 enableremote $remote preferreddir=$dirname
155 (If no directory name is configured, it uses "public" by
157 default.)
158 Note that, when a command is run with the --all option, or in a
160 bare repository, there is no filename associated with an annexed
161 object, and so "inpreferreddir" will not match.
162 standard
164 git-annex comes with some built-in preferred content expres‐
165 sions, that can be used with repositories that are in some stan‐
166 dard groups such as "client" and "transfer".
167 When a repository is in exactly one such group, you can use the
169 "standard" keyword in its preferred content expression, to match
170 whatever content the group's expression matches.
171 Most often, the whole preferred content expression is simply
173 "standard". But, you can do more complicated things, for exam‐
174 ple: standard or include=otherdir/*
175 groupwanted
177 The "groupwanted" keyword can be used to refer to a preferred
178 content expression that is associated with a group, as long as
179 there is exactly one such expression amoung the groups a reposi‐
180 tory is in. This is like the "standard" keyword, but you can
181 configure the preferred content expressions using git annex
182 groupwanted.
183 When writing a groupwanted preferred content expression, you can
185 use all the keywords documented here, including "standard".
186 (But not "groupwanted".)
187 For example, to make a variant of the standard client preferred
189 content expression that does not want files in the "out" direc‐
190 tory, you could run: git annex groupwanted client "standard and
191 exclude=out/*"
192 Then repositories that are in the client group and have their
194 preferred content expression set to "groupwanted" will use that,
195 while other client repositories that have their preferred con‐
196 tent expression set to "standard" will use the standard expres‐
197 sion.
198 Or, you could make a new group, with your own custom preferred
200 content expression tuned for your needs, and every repository
201 you put in this group and make its preferred content be "group‐
202 wanted" will use it.
203 For example, the archive group only wants to archive 1 copy of
205 each file, spread among every repository in the group. Here's
206 how to configure a group named redundantarchive, that instead
207 wants to contain 3 copies of each file:
208 git annex groupwanted redundantarchive "not (copies=redun‐
210 dantarchive:3)"
211 for repo in foo bar baz; do
212 git annex group $repo redundantarchive
213 git annex wanted $repo groupwanted
214 done
215 unused Matches only keys that git annex unused has determined to be
217 unused.
218 This is related the the --unused option. However, putting
220 unused in a preferred content expression doesn't make git-annex
221 consider those unused keys. So when git-annex is only checking
222 preferred content expressions against files in the repository
223 (which are obviously used), unused in a preferred content
224 expression won't match anything.
225 So when is unused useful in a preferred content expression?
227 Using git annex sync --content --all will operate on all files,
229 including unused ones, and take unused in preferred content
230 expressions into account.
231 The git-annex assistant periodically scans for unused files, and
233 moves them to some repository whose preferred content expression
234 says it wants them. (Or, if annex.expireunused is set, it may
235 just delete them.)
236 anything
238 Always matches.
239 nothing
241 Never matches. (Same as "not anything")
242 not expression
244 Inverts what the expression matches. For example, not
245 include=archive/* is the same as exclude=archive/*
246 and / or / ( expression )
248 These can be used to build up more complicated expressions.
249
251 To check at the command line which files are matched by a repository's
252 preferred content settings, you can use the --want-get and --want-drop
253 options.
254 For example, git annex find --want-get --not --in . will find all the
256 files that git annex get --auto will want to get, and git annex find
257 --want-drop --in . will find all the files that git annex drop --auto
258 will want to drop.
259
261 git-annex(1)
262 git-annex-vicfg(1)
264 git-annex-wanted(1)
266 <https://git-annex.branchable.com/preferred_content/>
268 <https://git-annex.branchable.com/preferred_content/standard_groups/>
270
272 Joey Hess <id@joeyh.name>
273 <http://git-annex.branchable.com/>
275 git-annex-preferred-content(1)