git-annex-...ng-options(1)

💅 git-annex-matching-options(1) 💅

okay bestie, welcome to the General Commands Manual — this is the page that teaches you how to tell git-annex exactly which files you mean, and honestly? it's giving main character energy 💅✨ (also psst, there's more of this page coming, so don't go anywhere 🫶)

---

✨ NAME ✨

git-annex-matching-options — specifying what to act on 🎯

🌸 DESCRIPTION 🌸

okay so here's the tea ☕: many git-annex commands support using these options to specify which files they act on. and some of these options can also be used by commands to specify which keys they act on. versatile icon behavior, we love to see it.

you can build arbitrarily complicated expressions out of these, fr fr. for example:

 --include='*.mp3' --and -( --in=usbdrive --or --in=archive -)

the above example makes git-annex work on only mp3 files that are present in either of two repositories. no cap, that's the whole vibe 🔥

---

🔥 OPTIONS 🔥

• --exclude=glob — skips files matching the glob pattern. the glob is matched relative to the current directory. for example:

git annex get --exclude='*.mp3' --exclude='subdir/*'

⚠️ bestie be aware: this will not match anything when using --all or --unused. like, at all. 🙈

• --include=glob — skips files not matching the glob pattern. (same as --not --exclude.) for example, to include only mp3 and ogg files:

git annex get --include='*.mp3' --or --include='*.ogg'

⚠️ and heads up: this will not skip anything when using --all or --unused.

• --excludesamecontent=glob — skips a file when there is another file with the same content, whose name matches the glob. the glob is matched relative to the current directory.

for example, to drop files in the archive directory, but not when the same content is used by a file in the work directory:

git annex drop archive/ --excludesamecontent='work/*'

• --includesamecontent=glob — skips files when there is no other file with the same content whose name matches the glob. (same as --not --excludesamecontent.)

for example, if you have inbox and outbox directories, and want to find anything in the inbox that has the same content as something in the outbox:

git annex find inbox --includesamecontent='outbox/*'

• --in=repository — matches only when git-annex believes that the content is present in a repository. 👑

the repository should be specified using the name of a configured remote, or the UUID or description of a repository. for the current repository, use "here".

⚠️ note that this does not check remote repositories to verify that content is still present on them. however, when checking the current repository, it does verify that content is present in it. so like, trust but verify, yk? 😭

• --in=repository@{date} — matches only when the content was present in a repository on the given date. 🕰️

the date is specified in the same syntax documented in gitrevisions(7). note that this uses the reflog, so dates far in the past cannot be queried. rip to the ancient history girlies 💀

for example, you might need to run git annex drop . to temporarily free up disk space. the next day, you can get back the files you dropped using git annex get . --in=here@{yesterday} — iconic comeback behavior, honestly ✨

• --expected-present — matches only when git-annex believes that the content is present in the local repository.

this is like --in=here, except it does not verify that the content is actually present. so it can be used in situations where the location tracking information is known to be out of date.

for example, if a repository is being restored from a backup that did not include the git-annex objects, this could be used to get back all files that were expected to be in it: git-annex get --expected-present 🫶

• --copies=number — matches only when git-annex believes there are the specified number of copies, or more. note that it does not check remotes to verify that the copies still exist. 🙈
• --copies=trustlevel:number — matches only when git-annex believes there are the specified number of copies, or more, on remotes with the specified trust level. for example, --copies=trusted:2

to match any trust level at or higher than a given level, use 'trustlevel+'. for example, --copies=semitrusted+:2

• --copies=groupname:number — matches only when git-annex believes there are the specified number of copies, or more, on remotes in the specified group. for example, --copies=archive:2
• copies=grouplimit=number — matches only files that git-annex believes have the specified number of copies, or more, on repositories in groups allowed by the group limit.

in a group limit, use "+" before a group to include that group, and "-" before a group to exclude it. (the first group to be included does not need to be prefixed with a "+" though it may be.)

a group limit matches repositories that are in any of the included groups and are in none of the excluded groups.

for example, "--copies=backup+archive-offsite=3" matches files that are stored in 3 backup or archive repositories, excluding offsite repositories. and "--copies=-offsite=3" matches files that are stored in 3 repositories excluding offsite repositories. math girlie hours 📐💖

• --lackingcopies=number — matches only when git-annex believes that the specified number or more additional copies need to be made in order to satisfy numcopies settings. 🔢
• --lackingcopies=groupname:number — providing the name of a group limits --lackingcopies to only considering repositories in that group toward the numcopies count.
• --lackingcopies=grouplimit=number — providing a group limit makes --lackingcopies only consider repositories in groups that match the group limit toward the numcopies count.

in a group limit, use "+" before a group to include that group, and "-" before a group to exclude it. (the first group to be included does not need to be prefixed with a "+" though it may be.)

a group limit matches repositories that are in any of the included groups and are in none of the excluded groups.

for example, "--lackingcopies=backup+archive-offsite=1" matches files that are not stored in enough backup or archive repositories, excluding offsite repositories. and "--lackingcopies=-offsite=1" matches files that are not stored in enough repositories, excluding offsite repositories. 🔥

• --approxlackingcopies=value — like --lackingcopies, but does not look at .gitattributes annex.numcopies settings. this makes it significantly faster. ⚡ not me choosing speed over accuracy, but like, sometimes that's the move
• --inbackend=name — matches only when content is stored using the specified key-value backend.
• --securehash — matches only when content is hashed using a cryptographically secure function. 🔐 very demure, very mindful
• --inallgroup=groupname — matches only when git-annex believes content is present in all repositories in the specified group. 👑
• --onlyingroup=groupname — matches only when git-annex believes content is present in at least one repository that is in the specified group, and is not present in any repositories that are not in the specified group. so like, exclusive friend group energy 💅
• --smallerthan=size
• --largerthan=size — matches only when the content is smaller than, or larger than the specified size. 📏

the size can be specified with any commonly used units, for example, "0.5 gb" or "100 KiloBytes"

• --metadata field=glob — matches only when there is a metadata field attached with a value that matches the glob. the values of metadata fields are matched case insensitively. 🏷️
• --metadata field<value / --metadata field>value
• --metadata field<=value / --metadata field>=value — matches only when there is a metadata field attached with a value that is less than or greater than the specified value, respectively.

when both values are numbers, the comparison is done numerically. when one value is not a number, the values are instead compared lexicographically. ngl that's kind of a plot twist 😭

⚠️ (note that you will need to quote the second parameter to avoid the shell doing redirection.) your shell is not your friend here bestie, protect it

• --url=glob — matches when the content is recorded as being present in an url that matches the glob. 🌐
• --want-get — matches only when the preferred content settings for the local repository make it want to get content. note that this will match even when the content is already present, unless limited with e.g., --not --in=here 🫶
• --want-drop — matches only when the preferred content settings for the local repository make it want to drop content. note that this will match even when the content is not present, unless limited with e.g., --not --in=here 🗑️

⚠️ things that this matches will not necessarily be dropped by git-annex drop --auto. this does not check that there are enough copies to drop. also the same content may be used by a file that is not wanted to be dropped. so like, don't @ me if it doesn't actually drop 💀

• --want-get-by=repository — matches only when the preferred content settings for the specified repository make it want to get content. note that this will match even when the content is already present in that repository, unless limited with e.g., --not --in=repository

the repository should be specified using the name of a configured remote, or the UUID or description of a repository. --want-get-by=here is the same as --want-get. ✨

• --want-drop-by=repository — matches only when the preferred content settings for the specificed repository make it want to drop content. note that this will match even when the content is not present, unless limited with e.g., --not --in=repository

the repository should be specified using the name of a configured remote, or the UUID or description of a repository. --want-drop-by=here is the same as --want-drop. 🎀

• --accessedwithin=interval — matches when the content in the local repository was accessed recently, within the specified time interval. ⏰

the interval can be in the form "5m" or "1h" or "2d" or "1y", or a combination such as "1h5m".

so for example, --accessedwithin=1d matches when the content was accessed within the past day.

⚠️ if the OS or filesystem does not support access times, this will not match anything. tragic, but that's the reality of it 😔

• --presentsince=repository:interval — matches when the content of the file has been present in the specified repository throughout the specified time interval. 🕰️✨

---

okay that's the first chunk of the matching-options lore bestie — more coming, so stay tuned 💜

...and like, when you're pointing at a repo, you gotta use the name of a configured remote, or the UUID, or the description of a repository. For the current repo, just say "here" — that's the whole vibe 💅

The interval can be in the form "5m" or "1h" or "2d" or "1y", or a combination such as "1h5m" — yes bestie, you can stack them, it's giving very flexible ✨

So for example, --presentsince=here:1d matches files that have been in the current repository for 1 day. Iconic behaviour honestly.

• --lackingsince=repository:interval — this is literally the opposite of --presentsince; it matches when, throughout the specified time interval, the content was not present in the specified repository 🫶

For example, --lackingsince=here:1d will match a file that was dropped from the local repository more than 1 day ago, and has not been present in it at any time since then. And it will match files that have never been present in the local repository. (Yes, never-been-there files count too — it's inclusive like that 💖)

• --changedsince=repository:interval — matches when there was a change in the content stored in the repository within the specified time interval. Big main-character energy for spotting movement 👑

For example, --changedsince=here:2d will match a file that was present in the repository but got dropped 1 day ago. And it will match a file that the repository got 1 day ago. But it won't match a file that has been present in the repository since 2 days ago. Read that twice, bestie, the nuance is everything 🎀

• --unlocked — matches annexed files that are unlocked 🔓
• --locked — matches annexed files that are locked 🔒
• --mimetype=glob — looks up the MIME type of a file, and checks if the glob matches it 🔍

For example, --mimetype="text/*" will match many varieties of text files, including "text/plain", but also "text/x-shellscript", "text/x-makefile", etc. So many etc! 🌸

The MIME types are the same that are displayed by running file --mime-type

If the file's annexed content is not present, the file will not match. No content, no match, that's the rule 😭

This is only available to use when git-annex was built with the MagicMime build flag. No flag, no feature — vibe check your build first 💀

• --mimeencoding=glob — looks up the MIME encoding of a file, and checks if the glob matches it 🔎

For example, --mimeencoding=binary will match many kinds of binary files.

The MIME encodings are the same that are displayed by running file --mime-encoding

If the file's annexed content is not present, the file will not match. Same deal as above, bestie.

This is only available to use when git-annex was built with the MagicMime build flag too 🧚

• --anything — always matches. One way this can be useful is git-annex find --anything will list all annexed files, whether their content is present or not. Literally everything, no gatekeeping 🌈
• --nothing — never matches. (Same as --not --anything) — it's giving void, empty, nothing ✨
• --not — inverts the next matching option. For example, to match when there are less than 3 copies, use --not --copies=3 🙈
• --and — requires that both the previous and the next matching option matches. The default. So if you don't say anything, this is the energy you're already running with 💜
• --or — requires that either the previous, or the next matching option matches 🦋
• -( — opens a group of matching options. Group chat time, everyone pile in 🎀
• -) — closes a group of matching options. Bye besties, see you at the closing paren 👋

---

🌟 SEE ALSO 🌟

git-annex(1) — go read the main one, it's iconic 💖

👑 AUTHOR 👑

Joey Hess <id@joeyh.name> — the legend, the moment, the whole entire author fr fr 🫶

---

okay that's the entire page bestie, you made it to the end 🥳 the footer is just git-annex-...ng-options(1) on its own — no extra source/version/date drama down here, it literally just signs off with its own name like the main character it is 💅✨