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