From b184fc490a3e068c27392255780383c35ebb6411 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Mon, 10 May 2021 15:00:13 -0400 Subject: [PATCH] split out common options to its own page and mention it on each subcommand page Sometimes users would get confused because an option they were looking for was not mentioned on a subcommand's man page, and they had not noticed that the main git-annex man page had a list of common options. This change lets each subcommand mention the common options, similarly to how the matching options are handled. This commit was sponsored by Svenne Krap on Patreon. --- doc/git-annex-add.mdwn | 2 + doc/git-annex-addunused.mdwn | 4 + doc/git-annex-addurl.mdwn | 2 + doc/git-annex-adjust.mdwn | 2 + doc/git-annex-assistant.mdwn | 2 + doc/git-annex-calckey.mdwn | 2 + doc/git-annex-checkpresentkey.mdwn | 2 + doc/git-annex-common-options.mdwn | 136 ++++++++++++++++++ doc/git-annex-config.mdwn | 16 +++ doc/git-annex-contentlocation.mdwn | 2 + doc/git-annex-copy.mdwn | 2 + doc/git-annex-dead.mdwn | 10 +- doc/git-annex-describe.mdwn | 4 + doc/git-annex-diffdriver.mdwn | 7 + doc/git-annex-drop.mdwn | 2 + doc/git-annex-dropkey.mdwn | 2 + doc/git-annex-dropunused.mdwn | 2 + doc/git-annex-enable-tor.mdwn | 4 + doc/git-annex-enableremote.mdwn | 7 + doc/git-annex-examinekey.mdwn | 2 + doc/git-annex-expire.mdwn | 2 + doc/git-annex-export.mdwn | 2 + doc/git-annex-find.mdwn | 2 + doc/git-annex-fix.mdwn | 2 + doc/git-annex-forget.mdwn | 2 + doc/git-annex-fromkey.mdwn | 2 + doc/git-annex-fsck.mdwn | 2 + doc/git-annex-fuzztest.mdwn | 4 + doc/git-annex-get.mdwn | 2 + doc/git-annex-group.mdwn | 4 + doc/git-annex-groupwanted.mdwn | 4 + doc/git-annex-import.mdwn | 2 + doc/git-annex-importfeed.mdwn | 2 + doc/git-annex-info.mdwn | 2 + doc/git-annex-init.mdwn | 2 + doc/git-annex-initremote.mdwn | 2 + doc/git-annex-inprogress.mdwn | 2 + doc/git-annex-list.mdwn | 2 + doc/git-annex-lock.mdwn | 2 + doc/git-annex-log.mdwn | 2 + doc/git-annex-lookupkey.mdwn | 2 + doc/git-annex-map.mdwn | 2 + doc/git-annex-matchexpression.mdwn | 2 + doc/git-annex-merge.mdwn | 4 + doc/git-annex-metadata.mdwn | 2 + doc/git-annex-migrate.mdwn | 2 + doc/git-annex-mincopies.mdwn | 4 + doc/git-annex-mirror.mdwn | 2 + doc/git-annex-move.mdwn | 2 + doc/git-annex-multicast.mdwn | 2 + doc/git-annex-numcopies.mdwn | 4 + doc/git-annex-p2p.mdwn | 2 + doc/git-annex-post-receive.mdwn | 4 + doc/git-annex-pre-commit.mdwn | 4 + doc/git-annex-readpresentkey.mdwn | 4 + doc/git-annex-registerurl.mdwn | 2 + doc/git-annex-reinit.mdwn | 4 + doc/git-annex-reinject.mdwn | 2 + doc/git-annex-rekey.mdwn | 2 + doc/git-annex-remotedaemon.mdwn | 14 +- doc/git-annex-renameremote.mdwn | 4 + doc/git-annex-repair.mdwn | 2 + doc/git-annex-required.mdwn | 4 + doc/git-annex-resolvemerge.mdwn | 4 + doc/git-annex-rmurl.mdwn | 2 + doc/git-annex-schedule.mdwn | 4 + doc/git-annex-semitrust.mdwn | 4 + doc/git-annex-setkey.mdwn | 4 + doc/git-annex-setpresentkey.mdwn | 2 + doc/git-annex-shell.mdwn | 2 + doc/git-annex-smudge.mdwn | 4 + doc/git-annex-status.mdwn | 2 + doc/git-annex-sync.mdwn | 2 + doc/git-annex-testremote.mdwn | 2 + doc/git-annex-transferkey.mdwn | 2 + doc/git-annex-transferkeys.mdwn | 4 + doc/git-annex-transferrer.mdwn | 4 + doc/git-annex-trust.mdwn | 4 + doc/git-annex-unannex.mdwn | 2 + doc/git-annex-undo.mdwn | 4 + doc/git-annex-ungroup.mdwn | 4 + doc/git-annex-uninit.mdwn | 4 + doc/git-annex-unlock.mdwn | 2 + doc/git-annex-unregisterurl.mdwn | 2 + doc/git-annex-untrust.mdwn | 4 + doc/git-annex-unused.mdwn | 2 + doc/git-annex-upgrade.mdwn | 2 + doc/git-annex-vadd.mdwn | 4 + doc/git-annex-vcycle.mdwn | 4 + doc/git-annex-version.mdwn | 2 + doc/git-annex-vfilter.mdwn | 4 + doc/git-annex-vicfg.mdwn | 4 + doc/git-annex-view.mdwn | 4 + doc/git-annex-vpop.mdwn | 4 + doc/git-annex-wanted.mdwn | 4 + doc/git-annex-watch.mdwn | 2 + doc/git-annex-webapp.mdwn | 2 + doc/git-annex-whereis.mdwn | 2 + doc/git-annex.mdwn | 120 ---------------- doc/todo/fsck_option_to_only_show_broken.mdwn | 2 + 100 files changed, 437 insertions(+), 127 deletions(-) create mode 100644 doc/git-annex-common-options.mdwn diff --git a/doc/git-annex-add.mdwn b/doc/git-annex-add.mdwn index 7d87a42361..c3e15e12fe 100644 --- a/doc/git-annex-add.mdwn +++ b/doc/git-annex-add.mdwn @@ -106,6 +106,8 @@ annexed content, and other symlinks. Makes the `--batch` input be delimited by nulls instead of the usual newlines. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-addunused.mdwn b/doc/git-annex-addunused.mdwn index 3dbddd6416..2d948bdda1 100644 --- a/doc/git-annex-addunused.mdwn +++ b/doc/git-annex-addunused.mdwn @@ -13,6 +13,10 @@ as listed by the last `git annex unused`. The files will have names starting with "unused." +# OPTIONS + +* The [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-addurl.mdwn b/doc/git-annex-addurl.mdwn index fe5b1627cf..b067c9c34a 100644 --- a/doc/git-annex-addurl.mdwn +++ b/doc/git-annex-addurl.mdwn @@ -130,6 +130,8 @@ be used to get better filenames. Messages that would normally be output to standard error are included in the json instead. +* Also the [[git-annex-common-options]](1) can be used. + # CAVEATS If annex.largefiles is configured, and does not match a file, `git annex diff --git a/doc/git-annex-adjust.mdwn b/doc/git-annex-adjust.mdwn index 97b7518a84..644e9fb267 100644 --- a/doc/git-annex-adjust.mdwn +++ b/doc/git-annex-adjust.mdwn @@ -109,6 +109,8 @@ and will also propagate commits back to the original branch. set the `annex.adjustedbranchrefresh` config. Or use `git-annex sync --content`, which updates the branch after transferring content. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-assistant.mdwn b/doc/git-annex-assistant.mdwn index 98cdab4d04..18f9341e2a 100644 --- a/doc/git-annex-assistant.mdwn +++ b/doc/git-annex-assistant.mdwn @@ -40,6 +40,8 @@ and automatically syncs them to other remotes. The complement to --autostart; stops all running daemons in the repositories listed in the autostart file. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-calckey.mdwn b/doc/git-annex-calckey.mdwn index b7f5464548..616e6aa662 100644 --- a/doc/git-annex-calckey.mdwn +++ b/doc/git-annex-calckey.mdwn @@ -34,6 +34,8 @@ For example, to force use of the SHA1 backend: Makes the `--batch` input be delimited by nulls instead of the usual newlines. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-checkpresentkey.mdwn b/doc/git-annex-checkpresentkey.mdwn index baa5ba47c3..5d4d4b971c 100644 --- a/doc/git-annex-checkpresentkey.mdwn +++ b/doc/git-annex-checkpresentkey.mdwn @@ -27,6 +27,8 @@ the special exit code 100 is used, and an error message is output to stderr. read from stdin, and a line is output with "1" if the key is verified to be present, and "0" otherwise. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-common-options.mdwn b/doc/git-annex-common-options.mdwn new file mode 100644 index 0000000000..ec9b56b851 --- /dev/null +++ b/doc/git-annex-common-options.mdwn @@ -0,0 +1,136 @@ +# NAME + +git-annex-common-options - options supported by all git-annex commands + +# DESCRIPTION + +These common options are accepted by all git-annex commands, and +may not be explicitly listed on their individual man pages. +(Many commands also accept the [[git-annex-matching-options]](1).) + +# OPTIONS + +* `--force` + + Force unsafe actions, such as dropping a file's content when no other + source of it can be verified to still exist, or adding ignored files. + Use with care. + +* `--fast` + + Avoid some expensive operations normally performed by a command. + What is avoided depends on the command, see individual command's man + pages for details. + +* `--quiet` + + Avoid the default verbose display of what is done; only show errors. + +* `--verbose` + + Enable verbose display. + +* `--debug` + + Display debug messages. + +* `--no-debug` + + Disable display of debug messages. + +* `--debugfilter=name[,name..]` + + When debug message display has been enabled by `--debug`, this filters + the debug messages that are displayed to ones coming from modules with + the specified names. + + To find the names of modules, see the full debug output, which includes + the module name, eg "(Utility.Process)" + + The full module name does not need to be + specified when using this, a substring of the name will do. + + For example, `--debugfilter=Process,External` will display debugging + output when git-annex runs processes, and when it communicates with + external special remotes. + +* `--numcopies=n` + + Overrides the numcopies setting. + + Note that setting numcopies to 0 is very unsafe. + +* `--mincopies=n` + + Overrides the mincopies setting. + + Note that setting mincopies to 0 is very unsafe. + +* `--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 continue running a little past the specified + time limit, in order to finish processing a file. + + Also, note that if the time limit prevents git-annex from doing all it + was asked to, it will exit with a special code, 101. + +* `--semitrust=repository` +* `--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 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. + +* `--trust-glacier` + + This used to override trust settings for Glacier special remotes, + but now will not do so, because it could lead to data loss, + and data loss is now only enabled when using the `--force` option. + +* `--backend=name` + + Specifies which key-value backend to use. This can be used when + adding a file to the annex, or migrating a file. Once files + are in the annex, their backend is known and this option is not + necessary. + +* `--user-agent=value` + + Overrides the User-Agent to use when downloading files from the web. + +* `--notify-finish` + + Caused 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.) + +* `--notify-start` + + Caused 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 + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-config.mdwn b/doc/git-annex-config.mdwn index daf5821c02..ed710ab7e8 100644 --- a/doc/git-annex-config.mdwn +++ b/doc/git-annex-config.mdwn @@ -100,6 +100,22 @@ looks for these. So, changes to the value in the git-annex branch won't affect a repository once it has been initialized. +# OPTIONS + +* `--set name value` + + Set a value. + +* `--get name` + + Get a value. + +* `--unset` + + Unset a value. + +* Also the [[git-annex-common-options]](1) can be used. + # EXAMPLE Suppose you want to prevent git annex sync from committing changes diff --git a/doc/git-annex-contentlocation.mdwn b/doc/git-annex-contentlocation.mdwn index baba8d883d..f5030a6dd7 100644 --- a/doc/git-annex-contentlocation.mdwn +++ b/doc/git-annex-contentlocation.mdwn @@ -23,6 +23,8 @@ present in the local repository, nothing is output, and it exits nonzero. Note that if a key's content is not present, an empty line is output to stdout instead. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-copy.mdwn b/doc/git-annex-copy.mdwn index 494cda3d26..e77d9a508b 100644 --- a/doc/git-annex-copy.mdwn +++ b/doc/git-annex-copy.mdwn @@ -112,6 +112,8 @@ Paths of files or directories to operate on can be specified. Messages that would normally be output to standard error are included in the json instead. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-dead.mdwn b/doc/git-annex-dead.mdwn index a139340338..2793a25bd5 100644 --- a/doc/git-annex-dead.mdwn +++ b/doc/git-annex-dead.mdwn @@ -4,7 +4,7 @@ git-annex dead - hide a lost repository or key # SYNOPSIS -git annex dead `[repository ...] [--key key]` +git annex dead `[repository ...] [--key somekey]` # DESCRIPTION @@ -22,6 +22,14 @@ from complaining about it; `--all` will not operate on the key anymore. (To undo, add the key's content back to the repository, by using eg, `git-annex reinject`.) +# OPTIONS + +* `--key=somekey` + + Use to specify a key that is dead. + +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-describe.mdwn b/doc/git-annex-describe.mdwn index cc5439ddda..a061371d1c 100644 --- a/doc/git-annex-describe.mdwn +++ b/doc/git-annex-describe.mdwn @@ -18,6 +18,10 @@ Repository descriptions are displayed by git-annex in various places. They are most useful when git-annex knows about a repository, but there is no git remote corresponding to it. +# OPTIONS + +* The [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-diffdriver.mdwn b/doc/git-annex-diffdriver.mdwn index f787c69fdd..994d195202 100644 --- a/doc/git-annex-diffdriver.mdwn +++ b/doc/git-annex-diffdriver.mdwn @@ -26,6 +26,13 @@ to it. Note the trailing "--", which is required. For example, set `GIT_EXTERNAL_DIFF=git-annex diffdriver -- j-c-diff --` +# OPTIONS + +Normally "--" followed by the diff driver command, its options, +and another "--" + +Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-drop.mdwn b/doc/git-annex-drop.mdwn index 3b1f7707e5..23f0b70268 100644 --- a/doc/git-annex-drop.mdwn +++ b/doc/git-annex-drop.mdwn @@ -125,6 +125,8 @@ Paths of files or directories to drop can be specified. Messages that would normally be output to standard error are included in the json instead. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-dropkey.mdwn b/doc/git-annex-dropkey.mdwn index 6816407371..fa5088590f 100644 --- a/doc/git-annex-dropkey.mdwn +++ b/doc/git-annex-dropkey.mdwn @@ -34,6 +34,8 @@ exist; using it can easily result in data loss. Messages that would normally be output to standard error are included in the json instead. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-dropunused.mdwn b/doc/git-annex-dropunused.mdwn index baadd0cc3c..29e601bcdc 100644 --- a/doc/git-annex-dropunused.mdwn +++ b/doc/git-annex-dropunused.mdwn @@ -28,6 +28,8 @@ Or, specify "all" to drop all unused data. the last repository that is storing their content. Data loss can result from using this option. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-enable-tor.mdwn b/doc/git-annex-enable-tor.mdwn index f06966400e..1553e7962c 100644 --- a/doc/git-annex-enable-tor.mdwn +++ b/doc/git-annex-enable-tor.mdwn @@ -21,6 +21,10 @@ After this command is run, `git annex remotedaemon` can be run to serve the tor hidden service, and then `git-annex p2p --gen-address` can be run to give other users access to your repository via the tor hidden service. +# OPTIONS + +* The [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-enableremote.mdwn b/doc/git-annex-enableremote.mdwn index 6620829854..fcd3b6a7cc 100644 --- a/doc/git-annex-enableremote.mdwn +++ b/doc/git-annex-enableremote.mdwn @@ -57,6 +57,13 @@ to be done to get it enabled. has found didn't work before and gave up on using, setting `remote..annex-ignore`.) +# OPTIONS + +Most options are not prefixed by a dash, and set parameters of the remote, +as shown above. + +Also, the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-examinekey.mdwn b/doc/git-annex-examinekey.mdwn index 2f7948afc3..50156afbf1 100644 --- a/doc/git-annex-examinekey.mdwn +++ b/doc/git-annex-examinekey.mdwn @@ -74,6 +74,8 @@ that can be determined purely by looking at the key. In order to also provide the name of a file associated with the key, the line can be in the format "$key $file" +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-expire.mdwn b/doc/git-annex-expire.mdwn index 8377d236d0..20c40bdbea 100644 --- a/doc/git-annex-expire.mdwn +++ b/doc/git-annex-expire.mdwn @@ -48,6 +48,8 @@ expired. The first version of git-annex that recorded fsck activity was 5.20150405. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-export.mdwn b/doc/git-annex-export.mdwn index 1b803cedee..98184274ad 100644 --- a/doc/git-annex-export.mdwn +++ b/doc/git-annex-export.mdwn @@ -113,6 +113,8 @@ so the overwritten modification is not lost.) Messages that would normally be output to standard error are included in the json instead. +* Also the [[git-annex-common-options]](1) can be used. + # EXAMPLE git annex initremote myremote type=directory directory=/mnt/myremote \ diff --git a/doc/git-annex-find.mdwn b/doc/git-annex-find.mdwn index cbd59b5ad3..2decd932b8 100644 --- a/doc/git-annex-find.mdwn +++ b/doc/git-annex-find.mdwn @@ -77,6 +77,8 @@ finds files in the current directory and its subdirectories. Makes the `--batch` input be delimited by nulls instead of the usual newlines. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-fix.mdwn b/doc/git-annex-fix.mdwn index e505ea406d..d7c7ef45b0 100644 --- a/doc/git-annex-fix.mdwn +++ b/doc/git-annex-fix.mdwn @@ -24,6 +24,8 @@ configured by annex.thin. The [[git-annex-matching-options]](1) can be used to specify files to fix. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-forget.mdwn b/doc/git-annex-forget.mdwn index b5d428cfbc..003e2946ca 100644 --- a/doc/git-annex-forget.mdwn +++ b/doc/git-annex-forget.mdwn @@ -26,6 +26,8 @@ git to push the branch to any git repositories not running git-annex.) Also prune references to repositories that have been marked as dead. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-fromkey.mdwn b/doc/git-annex-fromkey.mdwn index bdae927e44..ce7f486307 100644 --- a/doc/git-annex-fromkey.mdwn +++ b/doc/git-annex-fromkey.mdwn @@ -47,6 +47,8 @@ to do that. Enable JSON output. This is intended to be parsed by programs that use git-annex. Each line of output is a JSON object. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-fsck.mdwn b/doc/git-annex-fsck.mdwn index 4407f0c5e4..edc0360487 100644 --- a/doc/git-annex-fsck.mdwn +++ b/doc/git-annex-fsck.mdwn @@ -117,6 +117,8 @@ better format. normally displays all the files it's checking even when there is no problem with them. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-fuzztest.mdwn b/doc/git-annex-fuzztest.mdwn index 7045be0ee2..d678561baa 100644 --- a/doc/git-annex-fuzztest.mdwn +++ b/doc/git-annex-fuzztest.mdwn @@ -12,6 +12,10 @@ Generates random changes to files in the current repository, for use in testing the assistant. This is dangerous, so it will not do anything unless --forced. +# OPTIONS + +* The [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-get.mdwn b/doc/git-annex-get.mdwn index 28a73aa3fd..44f4fba0ca 100644 --- a/doc/git-annex-get.mdwn +++ b/doc/git-annex-get.mdwn @@ -133,6 +133,8 @@ be specified. Messages that would normally be output to standard error are included in the json instead. +* Also the [[git-annex-common-options]](1) can be used. + # SEE ALSO [[git-annex]](1) diff --git a/doc/git-annex-group.mdwn b/doc/git-annex-group.mdwn index 8a7455d82f..afe5aee47f 100644 --- a/doc/git-annex-group.mdwn +++ b/doc/git-annex-group.mdwn @@ -18,6 +18,10 @@ settings. See common option man page and references [[done]] --[[Joey]]