git-annex-common-options(1)

💖 git-annex-common-options 💖

okay bestie, welcome to the git-annex-common-options(1) page from the git-annex general commands manual ✨ this is the lore drop for all the flags that a whole bunch of git-annex commands just quietly accept, no cap 🫶

---

🌸 NAME 🌸

git-annex-common-options — options supported by many git-annex commands 👑

---

✨ DESCRIPTION ✨

so like, these common options are accepted by many git-annex commands, and they might not even be listed on those commands' own individual man pages. sneaky? a little. iconic? absolutely. 💅

Most of these options are accepted by all git-annex commands. and psst — many commands also accept the git-annex-matching-options(1) too, so go read that one next, iykyk 🦋

---

🎀 OPTIONS 🎀

• --force — forces unsafe actions through, like dropping a file's content when no other source of it can be verified to still exist, or adding ignored files. use with care, fr fr 😭

bestie this one is literally the "danger" button. respect it. 🙈

• --fast — skips some expensive operations that a command would normally do. exactly which stuff gets skipped depends on the command, so check that command's own man page for the deets. ⚡
• --quiet — skips the default verbose display of what's being done, and only shows errors. minimalism era. 🤫
• --verbose — turns on the verbose display. it's on by default, but --quiet can turn it off. 🗣️
• --explain — shows you the explanations of what git-annex is taking into account when it decides what to do. the explanations show up inside square brackets, like this: "[foo is not present here]" 👀

this includes explanations of why preferred content expressions and other similar expressions like annex.largefiles match or fail to match. in those explanations, the expression gets displayed with each term followed by [TRUE] or [FALSE] to show the value. irrelevant terms get omitted from the explanation — for example, "exclude=* and copies=1" will be displayed as "exclude=*[FALSE]". the receipts!! 🧾✨

• --debug — displays debug messages to standard error. 🐛
• --no-debug — disables the display of debug messages. 🚫🐛
• --debugfilter=name[,name..] — once debug message display has been enabled with --debug, this filters the debug messages down to the ones coming from modules with the names you specify. 🎯

to find the names of modules, look at the full debug output — it includes the module name, eg "(Utility.Process)".

you don't need to type the full module name when using this, a substring of the name will do. so chill.

for example, --debugfilter=Process,External will display debugging output when git-annex runs processes, and when it communicates with external special remotes. obsessed with the precision tbh 💅

• --numcopies=n — overrides the numcopies setting. 🔢
• --mincopies=n — overrides the mincopies setting. 🔢
• --rebalance — changes the behavior of the "balanced" preferred content expression so it's the same as "fullbalanced", and the "sizebalanced" expression so it's the same as "fullsizebalanced". when those expressions get used, this can cause a lot of work to be done to rebalance repositories. like, a LOT lot. 😮‍💨
• --time-limit=time — limits how long a git-annex command runs. the time can be something like "5h", or "30m" or even "45s" or "10d". ⏰

note that git-annex may keep running for some time past the specified time limit, in order to finish processing files it started before the time limit was reached. that, plus a cleaner shutdown, are the differences between using this option and a command like timeout(1). 🫶

when the time limit prevents git-annex from doing all it was asked to, it will exit with a special code, 101. 🚪

• --size-limit=size — limits the total size of annexed files that a git-annex command can process. 📏

the size can be specified with any commonly used units, for example, "50gb".

in some cases, an annexed file's size is not known. this option will prevent git-annex from processing such files. 🙅

when the size limit prevents git-annex from acting on any files, it will exit with a special code, 101. 🚪

• --semitrust=repository — and the next one share a description, scroll down bestie 👇
• --untrust=repository — overrides trust settings for a repository. may be specified more than once. 🔁

the repository should be specified using the name of a configured remote, or the UUID or description of a repository. 🗂️

• --trust=repository — this used to override trust settings for a repository, but now it will not do so, because trusting a repository can lead to data loss, and data loss is now only enabled when using the --force option. so yeah, this one's a glow-down, sorry babe 💀
• --trust-glacier — this used to override trust settings for Glacier special remotes, but now it will not do so, because it could lead to data loss, and data loss is now only enabled when using the --force option. same energy as above, the plot twist nobody asked for 😭
• --user-agent=value — overrides the User-Agent to use when downloading files from the web, or otherwise accessing web services. 🕸️
• --notify-finish — causes a desktop notification to be displayed after each successful file download and upload. 🎉

(only supported on some platforms, e.g. Linux with dbus. a no-op when not supported. so if nothing pops up, it's not you, it's the platform 💅)

• --notify-start — causes a desktop notification to be displayed when a file upload or download has started, or when a file is dropped. 🔔
• -c name=value — overrides git configuration settings. may be specified multiple times. 🔧

---

🌈 SEE ALSO 🌈

git-annex(1)

---

👑 AUTHOR 👑

Joey Hess <id@joeyh.name>

---

okay that's the whole thing, bestie, you ate that 🍓💜 and for the cute lil sign-off: this was the git-annex-common-options(1) page from the git-annex general commands manual, footer and all — go forth and flag responsibly, mwah 🎀✨🦋