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