1git-annex-preferred-content(1G)eneral Commands Manugailt-annex-preferred-content(1)
2
3
4

NAME

6       git-annex-preferred-content - which files are wanted in a repository
7

DESCRIPTION

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
15       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

SYNTAX

22       Preferred  content  expressions  use  a  similar  syntax  to  the  git-
23       annex-matching-options(1), without the dashes.  For example:
24
25        exclude=archive/* and (include=*.mp3 or smallerthan=1mb)
26
27       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

EXPRESSIONS

33       include=glob / exclude=glob
34
35              Match files to include, or exclude.
36
37              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
42              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
46              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
50              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
54       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
59              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
69       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
74              To match any trust level at or higher than a  given  level,  use
75              trustlevel+. For example, copies=semitrusted+:2
76
77       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
82              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
89       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
94       approxlackingcopies=number
95              Like  lackingcopies,  but  does  not  look   at   .gitattributes
96              annex.numcopies settings. This makes it significantly faster.
97
98       inbackend=name
99              Matches  only  files whose content is stored using the specified
100              key-value backend.
101
102       securehash
103              Matches only files whose content is hashed using a cryptographi‐
104              cally secure function.
105
106       inallgroup=groupname
107              Matches  only  files  that git-annex believes are present in all
108              repositories in the specified group.
109
110       smallerthan=size / largerthan=size
111              Matches only files whose content is smaller than, or larger than
112              the specified size.
113
114              The  size  can  be  specified  with any commonly used units, for
115              example, "0.5 gb" or "100 KiloBytes"
116
117       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
122              To match a tag "done", use metadata=tag=done
123
124              To match author metadata, use metadata=author=*Smith
125
126       metadata=field<number / metadata=field>number
127
128       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
133              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
137       present
138              Makes content be wanted if it's present, but not otherwise.
139
140              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
145              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
149       inpreferreddir
150              Makes  content be preferred if it's in a directory (located any‐
151              where in the tree) with a particular name.
152
153              The name of the directory can  be  configured  using  git  annex
154              enableremote $remote preferreddir=$dirname
155
156              (If  no  directory  name  is  configured,  it  uses  "public" by
157              default.)
158
159              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
163       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
168              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
172              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
176       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
184              When writing a groupwanted preferred content expression, you can
185              use all the  keywords  documented  here,  including  "standard".
186              (But not "groupwanted".)
187
188              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
193              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
199              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
204              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
209               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
216       unused Matches  only  keys  that  git annex unused has determined to be
217              unused.
218
219              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
226              So when is unused useful in a preferred content expression?
227
228              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
232              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
237       anything
238              Always matches.
239
240       nothing
241              Never matches. (Same as "not anything")
242
243       not expression
244              Inverts  what  the  expression   matches.   For   example,   not
245              include=archive/* is the same as exclude=archive/*
246
247       and / or / ( expression )
248              These can be used to build up more complicated expressions.
249

TESTING

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
255       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

SEE ALSO

261       git-annex(1)
262
263       git-annex-vicfg(1)
264
265       git-annex-wanted(1)
266
267       <https://git-annex.branchable.com/preferred_content/>
268
269       <https://git-annex.branchable.com/preferred_content/standard_groups/>
270

AUTHOR

272       Joey Hess <id@joeyh.name>
273
274       <http://git-annex.branchable.com/>
275
276                                                git-annex-preferred-content(1)
Impressum