From: Peter Michael Green Date: Thu, 28 Aug 2025 21:22:53 +0000 (+0000) Subject: Import changes made outside git. X-Git-Tag: archive/raspbian/10.20250416-2+rpi1^0 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=ea978d06e20733985321607ca81e15fa88f459a5;p=git-annex.git Import changes made outside git. --- diff --git a/debian/changelog b/debian/changelog index b6b067b3d9..43bb07ae24 100644 --- a/debian/changelog +++ b/debian/changelog @@ -6,6 +6,10 @@ git-annex (10.20250416-2+rpi1) trixie-staging; urgency=medium [changes brought forward from 10.20240430-1+rpi2 by Peter Michael Green at Thu, 26 Sep 2024 21:51:32 +0000] * Force use of llc-11 instead of llc-14. + [changes introduced in 10.20250416-2+rpi1 by Peter Michael Green] + * Pass -O0 to ghc. + * Disable testsuite. + -- Peter Michael Green Tue, 19 Aug 2025 17:39:24 +0000 git-annex (10.20250416-2) unstable; urgency=medium diff --git a/debian/patches/debian-changes b/debian/patches/debian-changes index 72ccb4c4a8..dd52514d8e 100644 --- a/debian/patches/debian-changes +++ b/debian/patches/debian-changes @@ -88,3 +88,12319 @@ A single combined diff, containing all the changes, follows. diff old new = -- Avoid running smudge clean filter, since we want the -- raw output, and it would block trying to access the +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-add.1 +@@ -0,0 +1,119 @@ ++.TH git-annex-add 1 ++.SH NAME ++git-annex-add \- adds files to the git annex ++.PP ++.SH SYNOPSIS ++git annex add \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Adds the specified files to the annex. If a directory is specified, ++acts on all files inside the directory and its subdirectories. ++If no path is specified, adds files from the current directory and below. ++.PP ++Files that are already checked into git and are unmodified, or that ++git has been configured to ignore will be silently skipped. ++.PP ++If annex.largefiles is configured (in git config, gitattributes, or ++git-annex config), and does not match a file, \fBgit annex add\fP will behave ++the same as \fBgit add\fP and add the non\-large file directly to the git ++repository, instead of to the annex. (By default dotfiles and the contents ++of dotdirs) are assumed to not be large, and are added directly to git, but ++annex.dotfiles can be configured to annex those too.) See the git-annex ++manpage for documentation of these and other configuration settings. ++.PP ++By default, large files are added to the annex in locked form, which ++prevents further modification of their content until ++unlocked by git-annex\-unlock(1). (This is not the case however ++when a repository is in a filesystem not supporting symlinks.) ++The annex.addunlocked git config (and git-annex config) can be used to ++change this behavior. ++.PP ++This command can also be used to add symbolic links, both symlinks to ++annexed content, and other symlinks. ++.PP ++.SH EXAMPLES ++ # git annex add foo bar ++ add foo ok ++ add bar ok ++ # git commit \-m added ++.PP ++.SH OPTIONS ++.IP "\fB\-\-no\-check\-gitignore\fP" ++.IP ++Add gitignored files. ++.IP ++.IP "\fB\-\-force\-large\fP" ++Treat all files as large files, ignoring annex.largefiles and annex.dotfiles ++configuration, and add to the annex. ++.IP ++.IP "\fB\-\-force\-small\fP" ++Treat all files as small files, ignoring annex.largefiles and annex.dotfiles ++and annex.addsmallfiles configuration, and add to git. ++.IP ++.IP "\fB\-\-backend\fP" ++Specifies which key\-value backend to use. ++.IP ++.IP "file matching options" ++Many of the git-annex\-matching\-options(1) ++can be used to specify files to add. ++.IP ++For example: \fB\-\-largerthan=1GB\fP ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Adds multiple files in parallel. This may be faster. ++For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-update\fP \fB\-u\fP" ++Like \fBgit add \-\-update\fP, this does not add new files, but any updates ++to tracked files will be added to the index. ++.IP ++.IP "\fB\-\-dry\-run\fP" ++Output what would be done for each file, but avoid making any changes. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which a file to add is read in a line from stdin, ++the file is added, and repeat. ++.IP ++Note that if a file is skipped (due to not existing, being gitignored, ++already being in git, or doesn't meet the matching options), ++an empty line will be output instead of the normal output produced ++when adding a file. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-unlock(1) ++.PP ++git-annex\-lock(1) ++.PP ++git-annex\-undo(1) ++.PP ++git-annex\-import(1) ++.PP ++git-annex\-unannex(1) ++.PP ++git-annex\-reinject(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-addcomputed.1 +@@ -0,0 +1,100 @@ ++.TH git-annex-addcomputed 1 ++.SH NAME ++git-annex-addcomputed \- adds computed files to the repository ++.PP ++.SH SYNOPSIS ++git annex addcomputed \fB\-\-to=remote \-\- ...\fP ++.PP ++.SH DESCRIPTION ++Adds files to the annex that are computed from input files in the ++repository, using a compute special remote. ++.PP ++Once a file has been added to a compute remote, commands ++like \fBgit-annex get\fP will use it to compute the content of the file. ++.PP ++The syntax of this command after the \fB\-\-\fP is up to the program that ++the compute special remote is set up to run to perform the comuptation. ++.PP ++To see the program's usage, you can run: ++.PP ++git-annex addcomputed \-\-to=foo ++.PP ++Generally you will provide an input file (or files), and often also an ++output filename, and additional parameters to control the computation. ++.PP ++There can be more than one input file that are combined to compute an ++output file. And multiple output files can be computed at the same time. ++.PP ++Some examples of how this might look: ++.PP ++git-annex addcomputed \-\-to=x \-\- convert file.raw file.jpeg passes=10 ++git-annex addcomputed \-\-to=y \-\- compress foo \-\-level=9 ++git-annex addcomputed \-\-to=z \-\- clip foo 2:01\-3:00 combine with bar to baz ++.PP ++Note that parameters that were passed to \fBgit-annex initremote\fP ++when setting up the compute special remote will be appended to the end of ++the parameters provided to \fBgit-annex addcomputed\fP. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-to=remote\fP" ++.IP ++Specify which remote will compute the files. ++.IP ++This must be a compute remote. For example, one can be ++initialized with: ++.IP ++git-annex initremote photoconv type=compute \\ ++program=git-annex\-compute\-photoconv ++.IP ++For details about compute remotes, and a list of some ++of the programs that are available, see ++ ++.IP ++.IP "\fB\-\-fast\fP" ++Adds computed files to the repository, without doing any work yet to ++compute their content. ++.IP ++This implies \fB\-\-unreproducible\fP, because even if the compute remote ++produces reproducible output, it's not available. ++.IP ++.IP "\fB\-\-unreproducible\fP, \fB\-u\fP" ++Indicate that the computation is not expected to be fully reproducible. ++It can vary, in ways that produce files that equivilant enough to ++be interchangeable, but are not necessarily identical. ++.IP ++This is the default unless the compute remote indicates that it produces ++reproducible output. ++.IP ++.IP "\fB\-\-reproducible\fP, \fB\-r\fP" ++Indicate that the computation is expected to be fully reproducible. ++.IP ++This is the default when the compute remote indicates that it produces ++reproducible output (except when using \fB\-\-fast\fP). ++.IP ++If a computation turns out not to be fully reproducible, then getting ++a computed file from the compute remote will later fail with a ++checksum verification error. One thing that can be done then is to use ++\fBgit-annex recompute \-\-original \-\-unreproducible\fP. ++.IP ++.IP "\fB\-\-backend\fP" ++Specifies which key\-value backend to use. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-recompute(1) ++.PP ++git-annex\-findcomputed(1) ++.PP ++git-annex\-initremote(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-addunused.1 +@@ -0,0 +1,36 @@ ++.TH git-annex-addunused 1 ++.SH NAME ++git-annex-addunused \- add back unused files ++.PP ++.SH SYNOPSIS ++git annex addunused \fB[number|range ...]\fP ++.PP ++.SH DESCRIPTION ++Adds back files for the content corresponding to the numbers or ranges, ++as listed by the last \fBgit annex unused\fP. ++.PP ++The files will have names starting with "unused." ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "The git-annex\-common\-options(1) can also be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-add(1) ++.PP ++git-annex\-unused(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-addurl.1 +@@ -0,0 +1,168 @@ ++.TH git-annex-addurl 1 ++.SH NAME ++git-annex-addurl \- add urls to annex ++.PP ++.SH SYNOPSIS ++git annex addurl \fB[url ...]\fP ++.PP ++.SH DESCRIPTION ++Downloads each url to its own file, which is added to the annex. ++.PP ++When \fByt\-dlp\fP is installed, it can be used to check for a video ++embedded in a web page at the url, and that is added to the annex instead. ++(However, this is disabled by default as it can be a security risk. ++See the documentation of annex.security.allowed\-ip\-addresses ++in git-annex(1) for details.) ++.PP ++Special remotes can add other special handling of particular urls. For ++example, the bittorrent special remotes makes urls to torrent files ++(including magnet links) download the content of the torrent, ++using \fBaria2c\fP. ++.PP ++Normally the filename is based on the full url, so will look like ++"www.example.com_dir_subdir_bigfile". In some cases, addurl is able to ++come up with a better filename based on other information. Options can also ++be used to get better filenames. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-fast\fP" ++.IP ++Avoid immediately downloading the url. The url is still checked ++(via HEAD) to verify that it exists, and to get its size if possible. ++.IP ++.IP "\fB\-\-relaxed\fP" ++Don't immediately download the url, and avoid storing the size of the ++url's content. This makes git-annex accept whatever content is there ++at a future point. ++.IP ++This is the fastest option, but it still has to access the network ++to check if the url contains embedded media. When adding large numbers ++of urls, using \fB\-\-relaxed \-\-raw\fP is much faster. ++.IP ++.IP "\fB\-\-verifiable\fP \fB\-V\fP" ++This can be used with the \fB\-\-fast\fP or \fB\-\-relaxed\fP option. It improves ++the safety of the resulting annexed file, by letting its content be ++verified with a checksum when it is transferred between git-annex ++repositories, as well as by things like \fBgit-annex fsck\fP. ++.IP ++When used with \-\-relaxed, content from the web special remote will ++always be accepted, even if it has changed, and the checksum recorded ++for later verification. ++.IP ++When used with \-\-fast, the checksum is recorded the first time the ++content is downloaded from the web special remote. Once a checksum has ++been recorded, subsequent downloads from the web special remote ++must have the same checksum. ++.IP ++When addurl was used without this option before, the file it added ++can be converted to be verifiable by migrating it to the VURL backend. ++For example: \fBgit-annex migrate foo \-\-backend=VURL\fP ++.IP ++.IP "\fB\-\-raw\fP" ++Prevent special handling of urls by yt\-dlp, and by bittorrent ++and other special remotes. This will for example, make addurl ++download the .torrent file and not the contents it points to. ++.IP ++.IP "\fB\-\-no\-raw\fP" ++Require content pointed to by the url to be downloaded using yt\-dlp ++or a special remote, rather than the raw content of the url. if that ++cannot be done, the add will fail. ++.IP ++.IP "\fB\-\-raw\-except=remote\fP" ++Prevent special handling of urls by all special remotes except ++for the specified one. To allow special handling only ++by yt\-dlp, use \fB\-\-raw\-except=web\fP. ++.IP ++.IP "\fB\-\-file=name\fP" ++Use with a filename that does not yet exist to add a new file ++with the specified name and the content downloaded from the url. ++.IP ++If the file already exists, addurl will record that it can be downloaded ++from the specified url(s). ++.IP ++.IP "\fB\-\-preserve\-filename\fP" ++When the web server (or torrent, etc) provides a filename, use it as\-is, ++avoiding sanitizing unusual characters, or truncating it to length, or any ++other modifications. ++.IP ++git-annex will still check the filename for safety, and if the filename ++has a security problem such as path traversal or a control character, ++it will refuse to add it. ++.IP ++.IP "\fB\-\-pathdepth=N\fP" ++Rather than basing the filename on the whole url, this causes a path to ++be constructed, starting at the specified depth within the path of the ++url. ++.IP ++For example, adding the url http://www.example.com/dir/subdir/bigfile ++with \fB\-\-pathdepth=1\fP will use "dir/subdir/bigfile", ++while \fB\-\-pathdepth=3\fP will use "bigfile". ++.IP ++It can also be negative; \fB\-\-pathdepth=\-2\fP will use the last ++two parts of the url. ++.IP ++.IP "\fB\-\-prefix=foo\fP \fB\-\-suffix=bar\fP" ++Use to adjust the filenames that are created by addurl. For example, ++\fB\-\-suffix=.mp3\fP can be used to add an extension to the file. ++.IP ++.IP "\fB\-\-no\-check\-gitignore\fP" ++By default, gitignores are honored and it will refuse to download an ++url to a file that would be ignored. This makes such files be added ++despite any ignores. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel downloads when multiple urls are being added. ++For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which lines containing urls to add are read from ++stdin. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-with\-files\fP" ++When batch mode is enabled, makes it parse lines of the form: "$url $file" ++.IP ++That adds the specified url to the specified file, downloading its ++content if the file does not yet exist; the same as ++\fBgit annex addurl $url \-\-file $file\fP ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-backend\fP" ++Specifies which key\-value backend to use. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH CAVEATS ++If annex.largefiles is configured, and does not match a file, git annex ++addurl will add the non\-large file directly to the git repository, ++instead of to the annex. However, this is not done when \-\-fast or \-\-relaxed ++is used. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-rmurl(1) ++.PP ++git-annex\-registerurl(1) ++.PP ++git-annex\-importfeed(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-adjust.1 +@@ -0,0 +1,128 @@ ++.TH git-annex-adjust 1 ++.SH NAME ++git-annex-adjust \- enter an adjusted branch ++.PP ++.SH SYNOPSIS ++git annex adjust \fB\-\-unlock|\-\-lock|\-\-fix|\-\-hide\-missing [\-\-unlock|\-\-lock|\-\-fix]|\-\-unlock\-present\fP ++.PP ++.SH DESCRIPTION ++Enters an adjusted form of the current branch. The annexed files will ++be treated differently. For example with \-\-unlock all annexed files will ++be unlocked. ++.PP ++The adjusted branch will have a name like "adjusted/master(unlocked)". ++Since it's a regular git branch, you can use \fBgit checkout\fP to switch ++back to the original branch at any time. ++.PP ++This allows changing how annexed files are handled, without making changes ++to a public branch with commands like \fBgit-annex unlock\fP. ++.PP ++While in the adjusted branch, you can use git-annex and git commands as ++usual. Any commits that you make will initially only be made to the ++adjusted branch. ++.PP ++To propagate commits from the adjusted branch back to the original branch, ++and to other repositories, as well as to merge in changes from other ++repositories, run \fBgit annex sync\fP. This will propagate changes that you've ++made such as adding/deleting files, but will not propagate the adjustments ++made by this command. ++.PP ++When in an adjusted branch, using \fBgit merge otherbranch\fP is often not ++ideal, because merging a non\-adjusted branch may lead to unnecessary ++merge conflicts, or add files in non\-adjusted form. To avoid those ++problems, use \fBgit annex merge otherbranch\fP. ++.PP ++Re\-running this command with the same options ++while inside the adjusted branch will update the adjusted branch ++as necessary (eg for \fB\-\-hide\-missing\fP and \fB\-\-unlock\-present\fP), ++and will also propagate commits back to the original branch. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-unlock\fP" ++.IP ++Unlock all annexed files in the adjusted branch. This allows ++annexed files to be modified. ++.IP ++Normally, unlocking a file requires a copy to be made of its content, ++so that its original content is preserved, while the copy can be modified. ++To use less space, annex.thin can be set to true before running this ++command; this makes a hard link to the content be made instead of a copy. ++(When supported by the file system.) While this can save considerable ++disk space, any modification made to a file will cause the old version of the ++file to be lost from the local repository. So, enable annex.thin with care. ++.IP ++When in an adjusted unlocked branch, \fBgit annex add\fP will add files ++unlocked instead of the default behavior of adding them locked. ++.IP ++.IP "\fB\-\-lock\fP" ++Lock all annexed files in the adjusted branch. This may be preferred ++by those who like seeing broken symlinks when the content of an ++annexed file is not present. ++.IP ++When in an adjusted locked branch, \fBgit annex add\fP will add files locked, ++as usual. However, \fBgit add\fP (and \fBgit commit \-a\fP etc) still add files ++unlocked. This is because it's not possible for those git commands to ++add files locked. ++.IP ++.IP "\fB\-\-fix\fP" ++Fix the symlinks to annexed files to point to the local git annex ++object directory. This can be useful if a repository is checked out in an ++unusual way that prevents the symlinks committed to git from pointing at ++the annex objects. ++.IP ++.IP "\fB\-\-hide\-missing\fP" ++Only include annexed files in the adjusted branch when their content ++is present. ++.IP ++The adjusted branch is not immediately changed when content availability ++changes, so if you \fBgit annex drop\fP files, they will become broken ++links in the usual way. And when files that were missing are copied into the ++repository from elsewhere, they won't immediatly become visible in the ++branch. ++.IP ++To update the adjusted branch to reflect changes to content availability, ++run \fBgit annex adjust \-\-hide\-missing\fP again. Or, to automate updates, ++set the \fBannex.adjustedbranchrefresh\fP config. ++.IP ++Despite missing files being hidden, \fBgit annex sync \-\-content\fP will ++still operate on them, and can be used to download missing ++files from remotes. It also updates the adjusted branch after ++transferring content. ++.IP ++This option can be combined with \-\-unlock, \-\-lock, or \-\-fix. ++.IP ++.IP "\fB\-\-unlock\-present\fP" ++Unlock files whose content is present, and lock files whose content is ++missing. This provides the benefits of working with unlocked files, ++but makes it easier to see when the content of a file is not missing, ++since it will be a broken symlink. ++.IP ++The adjusted branch is not immediately changed when content availability ++changes, so when you \fBgit annex get\fP files, they will remain locked. ++And when you \fBgit annex drop\fP files, they will remain locked and so will ++not be broken symlinks. ++.IP ++To update the adjusted branch to reflect changes to content availability, ++run \fBgit annex adjust \-\-unlock\-present\fP again. Or, to automate updates, ++set the \fBannex.adjustedbranchrefresh\fP config. Or use git-annex sync ++\-\-content, which updates the branch after transferring content. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-unlock(1) ++.PP ++git-annex\-lock(1) ++.PP ++git-annex\-upgrade(1) ++.PP ++git-annex\-sync(1) ++.PP ++git-annex\-view(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-assist.1 +@@ -0,0 +1,63 @@ ++.TH git-annex-assist 1 ++.SH NAME ++git-annex-assist \- add files and sync changes with remotes ++.PP ++.SH SYNOPSIS ++git annex assist \fB[remote ...]\fP ++.PP ++.SH DESCRIPTION ++This command assists you in checking files into the repository ++and syncing with remotes. It's the simplest possible way to use git-annex ++at the command line, since only this one command needs to be run on a ++regular basis. ++.PP ++This command first adds any new files to the repository, and commits those ++as well as any modified files. Then it does the equivilant of running ++[[git-annex\-pull](1) followed by git-annex\-push(1). ++.PP ++This command operates on all files in the whole working tree, ++even when ran in a subdirectory. To limit it to operating on files in a ++subdirectory, use the \fB\-\-content\-of\fP option. ++.PP ++To block some files from being added to the repository, use \fB.gitignore\fP ++files. ++.PP ++By default, all files that are added are added to the annex, the same ++as when you run \fBgit annex add\fP. If you configure annex.largefiles, ++files that it does not match will instead be added with \fBgit add\fP. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-message=msg\fP \fB\-m msg\fP" ++.IP ++Use this option to specify a commit message. ++.IP ++If multiple \-m options are given, their values are concatenated ++as separate paragraphs. ++.IP ++.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" ++Only add, pull, and push files in the given path. ++.IP ++This option can be repeated multiple times with different paths. ++.IP ++.IP "Also all options supported by git-annex\-pull(1) and" ++git-annex\-push(1) can be used. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-add(1) ++.PP ++git-annex\-pull(1) ++.PP ++git-annex\-push(1) ++.PP ++git-annex\-sync(1) ++.PP ++git-annex\-assistant(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-assistant.1 +@@ -0,0 +1,63 @@ ++.TH git-annex-assistant 1 ++.SH NAME ++git-annex-assistant \- daemon to add files and automatically sync changes ++.PP ++.SH SYNOPSIS ++git annex assistant ++.PP ++.SH DESCRIPTION ++Watches for changes to files in the current directory and its subdirectories, ++and automatically syncs them to other remotes. This includes adding new ++files. New files published to remotes by others are also automatically ++downloaded. ++.PP ++By default, all new files in the directory will be added to the repository. ++(Including dotfiles.) To block some files from being added, use ++\fB.gitignore\fP files. ++.PP ++By default, all files that are added are added to the annex, the same ++as when you run \fBgit annex add\fP. If you configure annex.largefiles, ++files that it does not match will instead be added with \fBgit add\fP. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-autostart\fP" ++.IP ++Automatically starts the assistant running in each repository listed ++in the file \fB~/.config/git-annex/autostart\fP ++.IP ++This is typically started at boot, or when you log in. ++.IP ++.IP "\fB\-\-startdelay=N\fP" ++Wait N seconds before running the startup scan. This process can ++be expensive and you may not want to run it immediately upon login. ++.IP ++When \-\-autostart is used, defaults to \-\-startdelay=5. ++.IP ++.IP "\fB\-\-foreground\fP" ++Avoid forking to the background. ++.IP ++.IP "\fB\-\-stop\fP" ++Stop a running daemon in the current repository. ++.IP ++.IP "\fB\-\-autostop\fP" ++The complement to \-\-autostart; stops all running daemons in the ++repositories listed in the autostart file. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-watch(1) ++.PP ++git-annex\-assist(1) ++.PP ++git-annex\-schedule(1) ++.PP ++For more details about the git-annex assistant, see ++ ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-backends.1 +@@ -0,0 +1,22 @@ ++.TH git-annex-backends 1 ++.SH NAME ++git-annex\-backends \- key/value backends for git-annex ++.PP ++.SH DESCRIPTION ++The "backend" in git-annex controls how a key is generated from a file's ++content and/or filesystem metadata. Most backends are different kinds of ++hashes. A single repository can use different backends for different files. ++.PP ++For a list of available backends, see \fBgit-annex version\fP. For more ++details, see ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++ ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-benchmark.1 +@@ -0,0 +1,60 @@ ++.TH git-annex-benchmark 1 ++.SH NAME ++git-annex-benchmark \- benchmark git-annex commands ++.PP ++.SH SYNOPSIS ++git annex benchmark [criterionopts] ( \-\- commmand [; command] | \-\-databases=N ) ++.PP ++.SH DESCRIPTION ++When git-annex is built with benchmarking support, this command can be used ++to benchmark any other git-annex command. For example ++"git annex benchmark \-\- get ." ++will benchmark "git annex get". ++.PP ++The command being benchmarked is run in the current git-annex repository. ++It does not run just once; the benchmarking process will run it several ++times to get a statistically meaningful result. ++.PP ++When benchmarking an action like "git annex get", the first run will ++often do much more than subseqent runs. To make the benchmark repeat an ++action like getting a file each time, additional commands can be listed, ++separated by ';'. (Note that ';' needs to be escaped from the shell.) ++The combined script will be run repeatedly by the benchmark. An example ++of using this: ++.PP ++ git annex benchmark \-\- get . ';' drop . ++.PP ++Note that git-annex benchmark does not fork new git-annex processes when ++benchmarking; it calls the command to benchmark internally, and so avoids ++git-annex's startup overhead. (So don't try to use it to optimise git-annex ++startup.) ++.PP ++.SH OPTIONS ++Before the "\-\-" any of the criterion library's command\-line options can be ++used. ++.PP ++Any options that git-annex usually accepts can be included after the ++command to benchmark. ++.PP ++The \-\-databases=N option benchmark's git-annex's use of sqlite databases, ++instead of a command. N is the number of items to benchmark. ++.PP ++.SH OUTPUT ++The output of the commands being benchmarked goes to standard output and ++standard error as usual. It's often a good idea to use \-\-quiet to avoid ++unnecessary output, unless the generation of that output is part of what ++you want to benchmark. ++.PP ++The benchmark report is output to standard output by default, although ++criterion options can be used to redirect it to a file. For example: ++.PP ++ git annex benchmark \-o bench \-\- find >/dev/null ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-calckey.1 +@@ -0,0 +1,40 @@ ++.TH git-annex-calckey 1 ++.SH NAME ++git-annex-calckey \- calculate key for a file ++.PP ++.SH SYNOPSIS ++git annex calckey \fB[file ...]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command calculates the key that would be used ++to refer to a file. The file is not added to the annex by this command. ++The key is output to stdout. ++.PP ++The backend used is the one from the annex.backend configuration ++setting, which can be overridden by the \-\-backend option. ++For example, to force use of the SHA1 backend: ++.PP ++ git annex calckey \-\-backend=SHA1 file ++.PP ++.SH OPTIONS ++.IP "\fB\-\-backend=name\fP" ++.IP ++Specifies which key\-value backend to use. ++.IP ++.IP "\fB\-\-batch\fP" ++Enable batch mode, in which a line containing the filename is read from ++stdin, the key is output to stdout (with a trailing newline), and repeat. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-checkpresentkey.1 +@@ -0,0 +1,35 @@ ++.TH git-annex-checkpresentkey 1 ++.SH NAME ++git-annex-checkpresentkey \- check if key is present in remote ++.PP ++.SH SYNOPSIS ++git annex checkpresentkey \fBkey\fP \fB[remote]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command verifies if the specified key's content ++is present in the specified remote. ++.PP ++When no remote is specified, it verifies if the key's content is present ++in any accessible remotes. ++.PP ++Exits 0 if the content is verified present in the remote, or 1 if it is ++verified to not be present in the remote. If there is a problem, ++the special exit code 100 is used, and an error message is output to stderr. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-batch\fP" ++.IP ++Enables batch mode. In this mode, the \fBkey\fP is not specified at the ++command line, but the \fBremote\fP may still be. Lines containing keys are ++read from stdin, and a line is output with "1" if the key is verified to ++be present, and "0" otherwise. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-common-options.1 +@@ -0,0 +1,142 @@ ++.TH git-annex-common-options 1 ++.SH NAME ++git-annex\-common\-options \- options supported by many git-annex commands ++.PP ++.SH DESCRIPTION ++These common options are accepted by many git-annex commands, and ++may not be explicitly listed on their individual man pages. ++Most of these options are accepted by all git-annex commands. ++(Many commands also accept the git-annex\-matching\-options(1).) ++.PP ++.SH OPTIONS ++.IP "\fB\-\-force\fP" ++.IP ++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. ++.IP ++.IP "\fB\-\-fast\fP" ++Avoid some expensive operations normally performed by a command. ++What is avoided depends on the command, see individual command's man ++pages for details. ++.IP ++.IP "\fB\-\-quiet\fP" ++Avoid the default verbose display of what is done; only show errors. ++.IP ++.IP "\fB\-\-verbose\fP" ++Enable verbose display. On by default but can be disabled by \-\-quiet. ++.IP ++.IP "\fB\-\-explain\fP" ++Display explanations of what git-annex takes into account when deciding ++what to do. The explanations will be inside square brackets. ++For example, "[foo is not present here]" ++.IP ++This includes explanations of why preferred content expressions and ++other similar expressions like annex.largefiles match or fail to match. ++In these explanations, the expression is displayed, with each term ++followed by "[TRUE]" or "[FALSE]" to indicate the value. ++Irrelevant terms will be ommitted from the explanation, for example ++\fB"exclude=* and copies=1"\fP will be displayed as \fB"exclude=*[FALSE]"\fP ++.IP ++.IP "\fB\-\-debug\fP" ++Display debug messages to standard error. ++.IP ++.IP "\fB\-\-no\-debug\fP" ++Disable display of debug messages. ++.IP ++.IP "\fB\-\-debugfilter=name[,name..]\fP" ++When debug message display has been enabled by \fB\-\-debug\fP, this filters ++the debug messages that are displayed to ones coming from modules with ++the specified names. ++.IP ++To find the names of modules, see the full debug output, which includes ++the module name, eg "(Utility.Process)" ++.IP ++The full module name does not need to be ++specified when using this, a substring of the name will do. ++.IP ++For example, \fB\-\-debugfilter=Process,External\fP will display debugging ++output when git-annex runs processes, and when it communicates with ++external special remotes. ++.IP ++.IP "\fB\-\-numcopies=n\fP" ++Overrides the numcopies setting. ++.IP ++.IP "\fB\-\-mincopies=n\fP" ++Overrides the mincopies setting. ++.IP ++.IP "\fB\-\-rebalance\fP" ++Changes the behavior of the "balanced" preferred content expression ++to be the same as "fullbalanced" and the "sizebalanced" expression ++to be the same as "fullsizebalanced". When those expressions are ++used, this can cause a lot of work to be done to rebalance ++repositories. ++.IP ++.IP "\fB\-\-time\-limit=time\fP" ++Limits how long a git-annex command runs. The time can be something ++like "5h", or "30m" or even "45s" or "10d". ++.IP ++Note that git-annex may continue running for some time past the specified ++time limit, in order to finish processing files it started before the ++time limit was reached. That and a cleaner shutdown are the differences ++between using this option and a command like \fBtimeout(1)\fP. ++.IP ++When the time limit prevents git-annex from doing all it ++was asked to, it will exit with a special code, 101. ++.IP ++.IP "\fB\-\-size\-limit=size\fP" ++Limits the total size of annexed files that a git-annex command ++can process. ++.IP ++The size can be specified with any commonly used units, for example, ++"50gb". ++.IP ++In some cases, an annexed file's size is not known. This option will ++prevent git-annex from processing such files. ++.IP ++When the size limit prevents git-annex from acting on any files, ++it will exit with a special code, 101. ++.IP ++.IP "\fB\-\-semitrust=repository\fP" ++.IP "\fB\-\-untrust=repository\fP" ++Overrides trust settings for a repository. May be specified more than once. ++.IP ++The repository should be specified using the name of a configured remote, ++or the UUID or description of a repository. ++.IP ++.IP "\fB\-\-trust=repository\fP" ++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 \fB\-\-force\fP option. ++.IP ++.IP "\fB\-\-trust\-glacier\fP" ++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 \fB\-\-force\fP option. ++.IP ++.IP "\fB\-\-user\-agent=value\fP" ++Overrides the User\-Agent to use when downloading files from the web, ++or otherwise accessing web services. ++.IP ++.IP "\fB\-\-notify\-finish\fP" ++Caused a desktop notification to be displayed after each successful ++file download and upload. ++.IP ++(Only supported on some platforms, e.g. Linux with dbus. A no\-op when ++not supported.) ++.IP ++.IP "\fB\-\-notify\-start\fP" ++Caused a desktop notification to be displayed when a file upload ++or download has started, or when a file is dropped. ++.IP ++.IP "\fB\-c name=value\fP" ++Overrides git configuration settings. May be specified multiple times. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-config.1 +@@ -0,0 +1,219 @@ ++.TH git-annex-config 1 ++.SH NAME ++git-annex-config \- configuration stored in git-annex branch ++.PP ++.SH SYNOPSIS ++git annex config \-\-set name value ++.PP ++git annex config \-\-get name ++.PP ++git annex config \-\-unset name ++.PP ++git annex config \-\-show\-origin name ++.PP ++.SH DESCRIPTION ++Set or get configuration settings stored in the git-annex branch. ++.PP ++Unlike \fBgit config\fP settings, these settings can be seen ++in all clones of the repository, once they have gotten their ++git-annex branches in sync. ++.PP ++These settings can be overridden on a per\-repository basis using ++\fBgit config\fP. ++.PP ++git-annex does not check the git-annex branch for all the \fBgit config\fP ++settings that affect it (which are listed on the git-annex man page ++CONFIGURATION section). Only a few make sense to be able to set such ++that all clones of a repository see the setting, and so git-annex only ++looks for these. ++.PP ++.SH SUPPORTED SETTINGS ++.IP "\fBannex.numcopies\fP" ++.IP ++Tells git-annex how many copies it should preserve of files, over all ++repositories. The default is 1. ++.IP ++When git-annex is asked to drop a file, it first verifies that the ++number of copies can be satisfied among all the other ++repositories that have a copy of the file. ++.IP ++In unusual situations, involving special remotes that do not support ++locking, and concurrent drops of the same content from multiple ++repositories, git-annex may violate the numcopies setting. It still ++guarantees at least 1 copy is preserved. This can be configured by ++setting annex.mincopies. ++.IP ++This is the same setting that the git-annex\-numcopies(1) command ++configures. It can be overridden on a per\-file basis ++by the annex.numcopies setting in \fB.gitattributes\fP files. ++.IP ++.IP "\fBannex.mincopies\fP" ++Tells git-annex how many copies it is required to preserve of files, ++over all repositories. The default is 1. ++.IP ++This supplements the annex.numcopies setting. ++In unusual situations, involving special remotes that do not support ++locking, and concurrent drops of the same content from multiple ++repositories, git-annex may violate the numcopies setting. ++In these unusual situations, git-annex ensures that the number of copies ++never goes below mincopies. ++.IP ++It is a good idea to not only rely on only setting mincopies. Set ++numcopies as well, to a larger number, and keep mincopies at the ++bare minimum you're comfortable with. Setting mincopies to a large ++number, rather than setting numcopies will in some cases prevent ++droping content in entirely safe situations. ++.IP ++This is the same setting that the git-annex\-mincopies(1) command ++configures. It can be overridden on a per\-file basis ++by the annex.mincopies setting in \fB.gitattributes\fP files. ++.IP ++.IP "\fBannex.largefiles\fP" ++Used to configure which files are large enough to be added to the annex. ++It is an expression that matches the large files, eg ++"\fBinclude=*.mp3 or largerthan(500kb)\fP". ++See git-annex\-matching\-expression(1) for details on the syntax. ++.IP ++This configures the behavior of both git-annex and git when adding ++files to the repository. By default, \fBgit-annex add\fP adds all files ++to the annex (except dotfiles and files in dotdirs), and ++\fBgit add\fP adds files to git (unless they were added to the annex previously). ++When annex.largefiles is configured, both ++\fBgit annex add\fP and \fBgit add\fP will add matching large files to the ++annex, and the other files to git. ++.IP ++Other git-annex commands also honor annex.largefiles, including ++\fBgit annex import\fP, \fBgit annex addurl\fP, \fBgit annex importfeed\fP, ++\fBgit-annex assist\fP, and the \fBgit-annex assistant\fP. ++.IP ++This sets a default, which can be overridden by annex.largefiles ++attributes in \fB.gitattributes\fP files, or by \fBgit config\fP. ++.IP ++.IP "\fBannex.dotfiles\fP" ++Normally, dotfiles and files inside dotdirs are assumed to be ++configuration files like .gitignore, whose content should always ++be part of the git repository, so they will not be added to the annex. ++Setting annex.dotfiles to true makes these files be added to the ++annex the same as any other file. ++.IP ++This sets a default, which can be overridden by annex.dotfiles ++in \fBgit config\fP. ++.IP ++.IP "\fBannex.addunlocked\fP" ++Commands like \fBgit-annex add\fP default to adding files to the repository ++in locked form. This can make them add the files in unlocked form, ++the same as if git-annex\-unlock(1) were run on the files. ++.IP ++This can be set to "true" to add everything unlocked, or it can be a more ++complicated expression that matches files by name, size, or content. See ++git-annex\-matching\-expression(1) for details. ++.IP ++This sets a default, which can be overridden by annex.addunlocked ++in \fBgit config\fP. ++.IP ++.IP "\fBannex.autocommit\fP" ++Set to false to prevent the \fBgit-annex assistant\fP, \fBgit-annex assist\fP ++and \fBgit-annex sync\fP from automatically committing changes to files ++in the repository. ++.IP ++This sets a default, which can be overridden by annex.autocommit ++in \fBgit config\fP. ++.IP ++.IP "\fBannex.resolvemerge\fP" ++Set to false to prevent merge conflicts in the checked out branch ++being automatically resolved by the \fBgit-annex assitant\fP, ++\fBgit-annex sync\fP, \fBgit-annex pull\fP, \fB\fPgit-annex merge, ++and the \fBgit-annex post\-receive\fP hook. ++.IP ++This sets a default, which can be overridden by annex.resolvemerge ++in \fBgit config\fP. ++.IP ++.IP "\fBannex.synccontent\fP" ++Set to true to make \fBgit-annex sync\fP default to transferring ++annexed content. ++.IP ++Set to false to prevent \fBgit-annex pull\fP and \fBgit-annex\fP push from ++transferring annexed content. ++.IP ++This sets a default, which can be overridden by annex.synccontent ++in \fBgit config\fP. ++.IP ++.IP "\fBannex.synconlyannex\fP" ++Set to true to make \fBgit-annex sync\fP, \fBgit-annex pull\fP and git-annex ++push default to only operate on the git-annex branch and annexed content. ++.IP ++This sets a default, which can be overridden by annex.synconlyannex ++in \fBgit config\fP. ++.IP ++.IP "\fBannex.securehashesonly\fP" ++Set to true to indicate that the repository should only use ++cryptographically secure hashes (SHA2, SHA3) and not insecure ++hashes (MD5, SHA1) for content. ++.IP ++When this is set, the contents of files using cryptographically ++insecure hashes will not be allowed to be added to the repository. ++.IP ++Also, \fBgit-annex fsck\fP will complain about any files present in ++the repository that use insecure hashes. ++.IP ++Note that this is only read from the git-annex branch by ++\fBgit annex init\fP, and is copied to the corresponding git config setting. ++So, changes to the value in the git-annex branch won't affect a ++repository once it has been initialized. ++.IP ++.SH OPTIONS ++.IP "\fB\-\-set name value\fP" ++.IP ++Set a value. ++.IP ++.IP "\fB\-\-get name\fP" ++Get a value. ++.IP ++.IP "\fB\-\-unset\fP" ++Unset a value. ++.IP ++.IP "\fB\-\-show\-origin name\fP" ++Explain where the value is configured, whether in the git-annex branch, ++or in a \fBgit config\fP file, or \fB.gitattributes\fP file. When a value is ++configured in multiple places, displays the place and the value that ++will be used. ++.IP ++Note that the parameter can be the name of one of the settings listed ++above, but also any other configuration setting supported by git-annex. ++For example, "annex.backend" cannot be set in the git-annex branch, but ++it can be set in \fB.gitattributes\fP or \fBgit config\fP and this option can ++explain which setting will be used for it. ++.IP ++.IP "\fB\-\-for\-file file\fP" ++Can be used in combination with \fB\-\-show\-origin\fP to specify what ++filename to check for in \fB.gitattributes\fP. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH EXAMPLE ++Suppose you want to prevent git annex sync from committing changes ++to files, so a manual git commit workflow is used in all clones of the ++repository. Then run: ++.PP ++ git annex config \-\-set annex.autocommit false ++.PP ++If you want to override that in a partiticular clone, just use git config ++in the clone: ++.PP ++ git config annex.autocommit true ++.PP ++And to get back to the default behavior: ++.PP ++ git annex config \-\-unset annex.autocommit ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git\-config(1) ++.PP ++git-annex\-vicfg(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-configremote.1 +@@ -0,0 +1,37 @@ ++.TH git-annex-configremote 1 ++.SH NAME ++git-annex-configremote \- changes special remote configuration ++.PP ++.SH SYNOPSIS ++git annex configemote \fBname|uuid|desc [param=value ...]\fP ++.PP ++.SH DESCRIPTION ++Changes the configuration of a special remote that was set up earlier ++by \fBgit-annex initremote\fP. The special remote does not need to be enabled ++for use in the current repository, and this command will not enable it. ++.PP ++This command can currently only be used to change the value of the ++\fBautoenable\fP parameter, eg "autoenable=false". ++.PP ++To change other parameters, use \fBgit-annex enableremote\fP ++.PP ++.SH OPTIONS ++Most options are not prefixed by a dash, and set parameters of the remote, ++as shown above. ++.PP ++Also, the git-annex\-common\-options(1) can be used. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-initremote(1) ++.PP ++git-annex\-configremote(1) ++.PP ++git-annex\-renameremote(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-contentlocation.1 +@@ -0,0 +1,31 @@ ++.TH git-annex-contentlocation 1 ++.SH NAME ++git-annex-contentlocation \- looks up content for a key ++.PP ++.SH SYNOPSIS ++git annex contentlocation \fB[key ...]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command looks up filename used to store the content ++of a key. The filename is output to stdout. If the key's content is not ++present in the local repository, nothing is output, and it exits nonzero. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-batch\fP" ++.IP ++Enable batch mode, in which a line containing the key is read from ++stdin, the filename to its content is output to stdout (with a trailing ++newline), and repeat. ++.IP ++Note that if a key's content is not present, an empty line is output to ++stdout instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-copy.1 +@@ -0,0 +1,127 @@ ++.TH git-annex-copy 1 ++.SH NAME ++git-annex-copy \- copy content of files to/from another repository ++.PP ++.SH SYNOPSIS ++git annex copy \fB[path ...] [\-\-from=remote|\-\-to=remote]\fP ++.PP ++.SH DESCRIPTION ++Copies the content of files from or to another remote. ++.PP ++With no parameters, operates on all annexed files in the current directory. ++Paths of files or directories to operate on can be specified. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-from=remote\fP" ++.IP ++Copy the content of files from the specified ++remote to the local repository. ++.IP ++Any files that are not available on the remote will be silently skipped. ++.IP ++.IP "\fB\-\-to=remote\fP" ++Copy the content of files from the local repository ++to the specified remote. ++.IP ++.IP "\fB\-\-to=here\fP" ++Copy the content of files from all reachable remotes to the local ++repository. ++.IP ++.IP "\fB\-\-from=remote1 \-\-to=remote2\fP" ++Copy the content of files that are in remote1 to remote2. ++.IP ++This is implemented by first downloading the content from remote1 to the ++local repository (if not already present), then sending it to remote2, and ++then deleting the content from the local repository (if it was not present ++to start with). ++.IP ++.IP "\fB\-\-from\-anywhere \-\-to=remote\fP" ++Copy to the remote files from the local repository as well as from any reachable ++remotes. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel transfers with up to the specified number of jobs ++running at once. For example: \fB\-J10\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++Note that when using \-\-from with \-\-to, twice this many jobs will ++run at once, evenly split between the two remotes. ++.IP ++.IP "\fB\-\-auto\fP" ++Rather than copying all specified files, only copy those that don't yet have ++the desired number of copies, or that are preferred content of the ++destination repository. See git-annex\-preferred\-content(1) ++.IP ++.IP "\fB\-\-fast\fP" ++When copying content to a remote, avoid a round trip to check if the remote ++already has content. This can be faster, but might skip copying content ++to the remote in some cases. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Rather than specifying a filename or path to copy, this option can be ++used to copy all available versions of all files. ++.IP ++This is the default behavior when running git-annex in a bare repository. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Operate on files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-unused\fP" ++Operate on files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-failed\fP" ++Operate on files that have recently failed to be transferred. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Use this option to copy a specified key. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to specify what to copy. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which lines containing names of files to copy ++are read from stdin. ++.IP ++As each specified file is processed, the usual progress output is ++displayed. If a file's content does not need to be copied, or it does not ++match specified matching options, or it is not an annexed file, ++a blank line is output in response instead. ++.IP ++Since the usual output while copying a file is verbose and not ++machine\-parseable, you may want to use \-\-json in combination with ++\-\-batch. ++.IP ++.IP "\fB\-\-batch\-keys\fP" ++This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. ++.IP ++.IP "\fB\-z\fP" ++Makes batch input be delimited by nulls instead of the usual newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-get(1) ++.PP ++git-annex\-move(1) ++.PP ++git-annex\-drop(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-dead.1 +@@ -0,0 +1,58 @@ ++.TH git-annex-dead 1 ++.SH NAME ++git-annex-dead \- hide a lost repository or key ++.PP ++.SH SYNOPSIS ++git annex dead \fB[repository ...] [\-\-key somekey ...]\fP ++.PP ++.SH DESCRIPTION ++This command exists to deal with situations where data has been lost, ++and you know it has, and you want to stop being reminded of that fact. ++.PP ++When a repository is specified, indicates that the repository has ++been irretrievably lost, so it will not be listed in eg, \fBgit annex whereis\fP. ++Repositories can be specified using their remote name, their ++description, or their UUID. (To undo, use \fBgit-annex semitrust\fP.) ++.PP ++When a key is specified, indicates that the content of that key has been ++irretrievably lost. This makes the key be skipped when operating ++on all keys with eg \fB\-\-all\fP. ++(To undo, add the key's content back to the repository, ++by using eg, \fBgit-annex reinject\fP.) ++.PP ++.SH OPTIONS ++.IP "\fB\-\-key=somekey\fP" ++.IP ++Use to specify a key that is dead. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-trust(1) ++.PP ++git-annex\-semitrust(1) ++.PP ++git-annex\-untrust(1) ++.PP ++git-annex\-renameremote(1) ++.PP ++git-annex\-expire(1) ++.PP ++git-annex\-fsck(1) ++.PP ++git-annex\-reinject(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-describe.1 +@@ -0,0 +1,39 @@ ++.TH git-annex-describe 1 ++.SH NAME ++git-annex-describe \- change description of a repository ++.PP ++.SH SYNOPSIS ++git annex describe repository description ++.PP ++.SH DESCRIPTION ++Changes the description of a repository. ++.PP ++The repository to describe can be specified by git remote name or ++by uuid. To change the description of the current repository, use ++"here". ++.PP ++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. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-init(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-diffdriver.1 +@@ -0,0 +1,60 @@ ++.TH git-annex-diffdriver 1 ++.SH NAME ++git-annex-diffdriver \- git diff driver ++.PP ++.SH SYNOPSIS ++\fBgit annex diffdriver [\-\-get,\-\-text] [\-\- \-\-diffopts \-\-]\fP ++.PP ++\fBgit annex diffdriver \-\- cmd \-\-cmdopts \-\-\fP ++.PP ++.SH DESCRIPTION ++Normally, \fBgit diff\fP when run on annexed files displays the changes that ++are staged in git, eg annex symlinks and pointers. This command allows ++\fBgit diff\fP to diff the content of annexed files instead. ++.PP ++This command can be used either as a simple text differ, ++or as a shim that runs an external git diff driver. ++.PP ++If some of your annexed files are textual in form, and can be usefully ++diffed with diff(1), you can configure git to use this command to diff ++them, by configuring \fB.gitattributes\fP to contain eg \fB*.txt diff=annextextdiff\fP ++and setting \fBgit config diff.annextextdiff.command "git annex diffdriver \-\-text"\fP. ++.PP ++If your annexed files are not textual in form, you will need an external ++diff driver program that is able to diff the file format(s) you use. ++See git's documentation of \fBGIT_EXTERNAL_DIFF\fP and ++gitattributes(5)'s documentation of external diff drivers. ++.PP ++Normally, when using \fBgit diff\fP with an external diff driver, it will not ++see the contents of annexed files, since git passes to it the git-annex ++symlinks or pointer files. This command works around the problem, by ++running the real external diff driver, and passing it the paths to the ++annexed content. Configure git to use "git-annex diffdriver \-\- cmd params \-\-" ++as the external diff driver, where cmd is the external diff ++driver you want it to run, and params are any extra parameters to pass ++to it. Note the trailing "\-\-", which is required. ++.PP ++For example, to use the j\-c\-diff program as the external diff driver, ++set \fBGIT_EXTERNAL_DIFF="git-annex diffdriver \-\- j\-c\-diff \-\-"\fP ++.PP ++.SH OPTIONS ++To get the contents of annexed files from remotes when they are not already ++present, use the \fB\-\-get\fP option. The file contents will remain in the ++repository for later use until dropped in the usual ways. ++.PP ++To diff text files with diff(1), use the \fB\-\-text\fP option. ++To pass additional options to diff(1), use eg "\-\-text \-\- \-\-color \-\-" ++.PP ++To use an external diff driver command, the options must start with ++"\-\-" followed by the diff driver command, its options, and another "\-\-" ++.PP ++Also the git-annex\-common\-options(1) can be used. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-direct.1 +@@ -0,0 +1,24 @@ ++.TH git-annex-direct 1 ++.SH NAME ++git-annex-direct \- switch repository to direct mode (deprecated) ++.PP ++.SH SYNOPSIS ++git annex direct ++.PP ++.SH DESCRIPTION ++This used to switch a repository to use direct mode. ++But direct mode is no longer used; git-annex automatically converts ++direct mode repositories to v7 adjusted unlocked branches. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-indirect(1) ++.PP ++git-annex\-adjust(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-drop.1 +@@ -0,0 +1,133 @@ ++.TH git-annex-drop 1 ++.SH NAME ++git-annex-drop \- remove content of files from repository ++.PP ++.SH SYNOPSIS ++git annex drop \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Drops the content of annexed files from this repository, when ++possible. ++.PP ++git-annex will refuse to drop content if it cannot verify it is ++safe to do so. Usually this involves verifying that the content is stored ++in some other repository. ++.PP ++Content that is required to be stored in the repository will not be dropped ++even if enough copies exist elsewhere. See git-annex\-required(1). ++.PP ++With no parameters, tries to drop all annexed files in the current directory. ++Paths of files or directories to drop can be specified. ++.PP ++.SH EXAMPLES ++ # git annex drop *.jpeg ++ drop photo1.jpg (checking origin...) ok ++ drop photo2.jpg (unsafe) ++ Could only verify the existence of 0 out of 1 necessary copies ++.PP ++ Rather than dropping this file, try using: git annex move ++.PP ++ (Use \-\-force to override this check, or adjust numcopies.) ++ failed ++ drop photo3.jpg (checking origin...) ok ++.PP ++.SH OPTIONS ++.IP "\fB\-\-from=remote\fP" ++.IP ++Rather than dropping the content of files in the local repository, ++this option can specify a remote from which the files' ++contents should be removed. ++.IP ++.IP "\fB\-\-auto\fP" ++Rather than trying to drop all specified files, drop only those that ++are not preferred content of the repository, and avoid trying to drop ++files when there are not enough other copies for the drop to be possible. ++See git-annex\-preferred\-content(1) ++.IP ++.IP "\fB\-\-force\fP" ++Use this option with care! It bypasses safety checks, and forces ++git-annex to delete the content of the specified files, even from ++the last repository that is storing their content. Data loss can ++result from using this option. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Rather than specifying a filename or path to drop, this option can be ++used to drop all available versions of all files. ++.IP ++This is the default behavior when running git-annex drop in a bare ++repository. ++.IP ++Note that this bypasses checking the .gitattributes annex.numcopies ++setting and required content settings. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Drop files in the specified branch or treeish. ++.IP ++Note that this bypasses checking the .gitattributes annex.numcopies ++setting and required content settings. ++.IP ++.IP "\fB\-\-unused\fP" ++Drop files found by last run of git-annex unused. ++.IP ++Note that this bypasses checking the .gitattributes annex.numcopies ++setting and required content settings. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Use this option to drop a specified key. ++.IP ++Note that this bypasses checking the .gitattributes annex.numcopies ++setting and required content settings. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to specify what to drop. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Runs multiple drop jobs in parallel. This is particularly useful ++when git-annex has to contact remotes to check if it can drop files. ++For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which lines containing names of files to drop ++are read from stdin. ++.IP ++As each specified file is processed, the usual output is ++displayed. If a file's content is not present, or it does not ++match specified matching options, or it is not an annexed file, ++a blank line is output in response instead. ++.IP ++.IP "\fB\-\-batch\-keys\fP" ++This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. ++.IP ++Note that this bypasses checking the .gitattributes annex.numcopies ++setting and required content settings. ++.IP ++.IP "\fB\-z\fP" ++Makes the batch input be delimited by nulls ++instead of the usual newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-get(1) ++.PP ++git-annex\-move(1) ++.PP ++git-annex\-copy(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-dropkey.1 +@@ -0,0 +1,42 @@ ++.TH git-annex-dropkey 1 ++.SH NAME ++git-annex-dropkey \- drops annexed content for specified keys ++.PP ++.SH SYNOPSIS ++git annex dropkey \fB[key ...]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command drops the annexed data for the specified ++keys from this repository. ++.PP ++This can be used to drop content for arbitrary keys, which do not need ++to have a file in the git repository pointing at them. ++.PP ++Warning: This command does not check that enough other copies of the content ++exist; using it can easily result in data loss. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-batch\fP" ++.IP ++Enables batch mode, in which lines containing keys to drop are read from ++stdin. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-setkey(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-dropunused.1 +@@ -0,0 +1,56 @@ ++.TH git-annex-dropunused 1 ++.SH NAME ++git-annex-dropunused \- drop unused file content ++.PP ++.SH SYNOPSIS ++git annex dropunused \fB[number|range ...]\fP ++.PP ++.SH DESCRIPTION ++Drops the data corresponding to the numbers, as listed by the last ++\fBgit annex unused\fP ++.PP ++You can also specify ranges of numbers, such as "1\-1000". ++Or, specify "all" to drop all unused data. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-from=remote\fP" ++.IP ++Rather than dropping the unused files from the local repository, ++drop them from the remote repository. ++.IP ++.IP "\fB\-\-force\fP" ++Use this option with care! It bypasses safety checks, and forces ++git-annex to delete the content of the specified files, even from ++the last repository that is storing their content. Data loss can ++result from using this option. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Runs multiple drop jobs in parallel. This is particularly useful ++when git-annex has to contact remotes to check if it can drop content. ++For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-unused(1) ++.PP ++git-annex\-drop(1) ++.PP ++git-annex\-copy(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-edit.1 +@@ -0,0 +1,16 @@ ++.TH git-annex-edit 1 ++.SH NAME ++git-annex-unlock \- unlock files for modification ++.PP ++.SH SYNOPSIS ++git annex edit \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++This is an alias for the \fBunlock\fP command; see git-annex\-unlock(1) ++for details. ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-enable-tor.1 +@@ -0,0 +1,36 @@ ++.TH git-annex-enable-tor 1 ++.SH NAME ++git-annex-enable\-tor \- enable tor hidden service ++.PP ++.SH SYNOPSIS ++git annex enable\-tor ++.PP ++sudo git annex enable\-tor $(id \-u) ++.PP ++.SH DESCRIPTION ++This command enables a tor hidden service for git-annex. ++.PP ++It modifies \fB/etc/tor/torrc\fP to register the hidden service. If run as a ++normal user, it will try to use sudo/su/etc to get root access to modify ++that file. If you run it as root, pass it your non\-root user id number, ++as output by \fBid \-u\fP ++.PP ++After this command is run, \fBgit annex remotedaemon\fP can be run to serve the ++tor hidden service, and then \fBgit-annex p2p \-\-gen\-addresses\fP can be run to ++give other users access to your repository via the tor hidden service. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-p2p\-auth(1) ++.PP ++git-annex\-remotedaemon(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-enableremote.1 +@@ -0,0 +1,86 @@ ++.TH git-annex-enableremote 1 ++.SH NAME ++git-annex-enableremote \- enables git-annex to use a remote ++.PP ++.SH SYNOPSIS ++git annex enableremote \fBname|uuid|desc [param=value ...]\fP ++.PP ++.SH DESCRIPTION ++Enables use of an existing remote in the current repository, ++that was set up earlier by \fBgit annex initremote\fP run in ++another clone of the repository. ++.PP ++When enabling a remote, specify the same name used when originally ++setting up that remote with \fBgit annex initremote\fP. Run ++\fBgit annex enableremote\fP without any name to get a list of ++remote names. Or you can specify the uuid or description of the ++remote. ++.PP ++Some types of special remotes need parameters to be specified every time ++they are enabled. For example, the directory special remote requires a ++directory= parameter every time. The command will prompt for any required ++parameters you leave out. ++.PP ++This command can also be used to modify the configuration of an existing ++special remote, by specifying new values for parameters that are ++usually set when using initremote. (However, some settings such as ++the as the encryption scheme cannot be changed once a special remote ++has been created.) ++.PP ++The GPG keys that an encrypted special remote is encrypted with can be ++changed using the keyid+= and keyid\-= parameters. These respectively ++add and remove keys from the list. However, note that removing a key ++does NOT necessarily prevent the key's owner from accessing data ++in the encrypted special remote ++(which is by design impossible, short of deleting the remote). ++.PP ++One use\-case of keyid\-= is to replace a revoked key with ++a new key: ++.PP ++ git annex enableremote mys3 keyid\-=revokedkey keyid+=newkey ++.PP ++Also, note that for encrypted special remotes using plain public\-key ++encryption (encryption=pubkey), adding or removing a key has NO effect ++on files that have already been copied to the remote. Hence using ++keyid+= and keyid\-= with such remotes should be used with care, and ++make little sense except in cases like the revoked key example above. ++.PP ++If you get tired of manually enabling a special remote in each new clone, ++you can pass "autoenable=true". Then when git-annex\-init(1) is run in ++a new clone, it will will attempt to enable the special remote. Of course, ++this works best when the special remote does not need anything special ++to be done to get it enabled. ++.PP ++(This command also can be used to enable a git remote that git-annex ++has found didn't work before and gave up on using, setting ++\fBremote..annex\-ignore\fP.) ++.PP ++.SH OPTIONS ++.IP "\fB\-\-with\-url\fP" ++.IP ++This configures the remote with an "annex::" url, which allows ++git to push to and pull from it, using git\-remote\-annex. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also, the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-initremote(1) ++.PP ++git-annex\-configremote(1) ++.PP ++git-annex\-renameremote(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-examinekey.1 +@@ -0,0 +1,81 @@ ++.TH git-annex-examinekey 1 ++.SH NAME ++git-annex-examinekey \- prints information from a key ++.PP ++.SH SYNOPSIS ++git annex examinekey \fB[key ...]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command is given a key, and prints information ++that can be determined purely by looking at the key. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-format=value\fP" ++.IP ++Use custom output formatting. ++.IP ++The value is a format string, in which '${var}' is expanded to the ++value of a variable. To right\-justify a variable with whitespace, ++use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; ++to escape unusual characters (including control characters) ++in a variable, use '${escaped_var}' ++.IP ++To generate a path from the top of the repository to the git-annex ++object for a key, use ${objectpath}. To generate the value of a ++git-annex pointer file for a key, use ${objectpointer}. ++.IP ++These variables are also available for use in formats: ${key}, ${backend}, ++${bytesize}, ${humansize}, ${keyname}, ${hashdirlower}, ${hashdirmixed}, ++${mtime} (for the mtime field of a WORM key), ${file} (when a filename is ++provided to examinekey). ++.IP ++Also, '\\n' is a newline, '\\000' is a NULL, etc. ++.IP ++The default output format is the same as \fB\-\-format='${escapedkey}\\n'\fP ++except when outputting to a terminal, control characters will be escaped. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-migrate\-to\-backend=backend\fP" ++Attempt to migrate the input key to the new backend specified. If ++successful, outputs information about the migrated key. Otherwise, ++outputs information about the input key. ++.IP ++This only does fast migrations; it will not re\-hash the content of a key ++or similar expensive operation. ++.IP ++One way to use it is to add an extension to a key. ++.IP ++ git-annex examinekey SHA256\-\-xxx \-\-migrate\-to\-backend=SHA256E \-\-filename=foo.tar.gz ++.IP ++Or to remove the extension from a key: ++.IP ++ git-annex examinekey SHA256E\-\-xxx.tar.gz \-\-migrate\-to\-backend=SHA256 ++.IP ++.IP "\fB\-\-filename=name\fP" ++The name of a file associated with the key, eg a work tree file. ++It does not need to exist. This is needed when using \fB\-\-migrate\-to\-backend\fP ++to add an extension to the key. ++.IP ++.IP "\fB\-\-batch\fP" ++Enable batch mode, in which a line containing a key is read from stdin, ++the information about it is output to stdout, and repeat. ++.IP ++In order to also provide the name of a file associated with the key, the ++line can be in the format "$key $file" ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-expire.1 +@@ -0,0 +1,71 @@ ++.TH git-annex-expire 1 ++.SH NAME ++git-annex-expire \- expire inactive repositories ++.PP ++.SH SYNOPSIS ++git annex expire \fB[repository:]time ...\fP ++.PP ++.SH DESCRIPTION ++This command expires repositories that have not performed some activity ++within a specified time period. A repository is expired by marking it as ++dead. De\-expiration is also done; if a dead repository performed some ++activity recently, it is marked as semitrusted again. ++.PP ++This can be useful when it's not possible to keep track of the state ++of repositories manually. For example, a distributed network of ++repositories where nobody can directly access all the repositories to ++check their status. ++.PP ++The repository can be specified using the name of a remote, ++or the description or uuid of the repository. ++.PP ++The time is in the form "60d" or "1y". A time of "never" will disable ++expiration. ++.PP ++If a time is specified without a repository, it is used as the default ++value for all repositories. Note that the current repository is never ++expired. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-no\-act\fP" ++.IP ++Print out what would be done, but not not actually expire or unexpire ++any repositories. ++.IP ++.IP "\fB\-\-activity=Name\fP" ++Specify the activity that a repository must have performed to avoid being ++expired. The default is any activity. ++.IP ++Currently, the only activity that can be performed to avoid expiration ++is \-\-activity=Fsck which corresponds to \fBgit annex fsck\fP. ++Note that fscking a remote updates the expiration of the remote ++repository, not the local repository. ++.IP ++The first version of git-annex that recorded fsck activity was ++5.20150405. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-fsck(1) ++.PP ++git-annex\-schedule(1) ++.PP ++git-annex\-dead(1) ++.PP ++git-annex\-semitrust(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-export.1 +@@ -0,0 +1,173 @@ ++.TH git-annex-export 1 ++.SH NAME ++git-annex-export \- export a tree of files to a special remote ++.PP ++.SH SYNOPSIS ++git annex export \fBtreeish \-\-to remote\fP ++.PP ++.SH DESCRIPTION ++Use this command to export a tree of files from a git-annex repository. ++.PP ++Normally files are stored on a git-annex special remote named by their ++keys. That is great for reliable data storage, but your filenames are ++obscured. Exporting replicates the tree to the special remote as\-is. ++.PP ++To use this, you have to configure a special remote with ++\fBexporttree=yes\fP when initially setting it up with ++git-annex\-initremote(1). ++.PP ++The treeish to export can be the name of a git branch, or a tag, or any ++other treeish accepted by git, including eg master:subdir to only export a ++subdirectory from a branch. ++.PP ++When the remote has a preferred content expression set by ++git-annex\-wanted(1), the treeish is ++filtered through it, excluding annexed files it does not want from ++being exported to it. (Note that things in the expression like ++"include=" match relative to the top of the treeish being exported.) ++.PP ++Any files in the treeish that are stored on git will also be exported to ++the special remote. ++.PP ++Repeated exports are done efficiently, by diffing the old and new tree, ++and transferring only the changed files, and renaming files as necessary. ++.PP ++Exports can be interrupted and resumed. However, partially uploaded files ++will be re\-started from the beginning in most cases. ++.PP ++Once content has been exported to a remote, commands like \fBgit annex get\fP ++can download content from there the same as from other remotes. However, ++since an export is not a key/value store, git-annex has to do more ++verification of content downloaded from an export. Some types of keys, ++that are not based on checksums, cannot be downloaded from an export. ++And, git-annex will never trust an export to retain the content of a key. ++.PP ++However, some special remotes, notably S3, support keeping track of old ++versions of files stored in them. If a special remote is set up to do ++that, it can be used as a key/value store and the limitations in the above ++paragraph do not apply. Note that dropping content from such a remote is ++not supported. See individual special remotes' documentation for ++details of how to enable such versioning. ++.PP ++Commands like \fBgit-annex push\fP can also be used to export a branch to a ++special remote, updating the special remote whenever the branch is changed. ++To do this, you need to configure "remote..annex\-tracking\-branch" to ++tell it what branch to track. For example: ++.PP ++ git config remote.myremote.annex\-tracking\-branch master ++ git annex push myremote ++.PP ++You can combine using \fBgit annex export\fP to send changes to a special ++remote with \fBgit annex import\fP to fetch changes from a special remote. ++When a file on a special remote has been modified by software other than ++git-annex, exporting to it will not overwrite the modified file, and the ++export will not succeed. You can resolve this conflict by using ++\fBgit annex import\fP. ++.PP ++(Some types of special remotes such as S3 with versioning may instead ++let an export overwrite the modified file; then \fBgit annex import\fP ++will create a sequence of commits that includes the modified file, ++so the overwritten modification is not lost.) ++.PP ++.SH OPTIONS ++.IP "\fB\-\-to=remote\fP" ++.IP ++Specify the special remote to export to. ++.IP ++.IP "\fB\-\-from=remote\fP" ++When the content of a file is not available in the local repository, ++this option lets it be downloaded from another remote, and sent on to the ++destination remote. The file will be temporarily stored on local disk, ++but will never enter the local repository. ++.IP ++This option can be repeated multiple times. ++.IP ++It is possible to use \-\-from with the same remote as \-\-to. If the tree ++contains several files with the same content, and the remote being ++exported to already contains one copy of the content, this allows making ++a copy by downloading the content from it. ++.IP ++.IP "\fB\-\-tracking\fP" ++This is a deprecated way to set "remote..annex\-tracking\-branch". ++Instead of using this option, you should just set the git configuration ++yourself. ++.IP ++.IP "\fB\-\-fast\fP" ++This sets up an export of a tree, but avoids any expensive file uploads to ++the remote. You can later run \fBgit annex push\fP to upload ++the files to the export. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Exports multiple files in parallel. This may be faster. ++For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH EXAMPLE ++ git annex initremote myremote type=directory directory=/mnt/myremote \\ ++ exporttree=yes encryption=none ++ git annex export master \-\-to myremote ++.PP ++After that, /mnt/myremote will contain the same tree of files as the master ++branch does. ++.PP ++ git mv myfile subdir/myfile ++ git commit \-m renamed ++ git annex export master \-\-to myremote ++.PP ++That updates /mnt/myremote to reflect the renamed file. ++.PP ++ git annex export master:subdir \-\-to myremote ++.PP ++That updates /mnt/myremote, to contain only the files in the "subdir" ++directory of the master branch. ++.PP ++.SH EXPORT CONFLICTS ++If two different git-annex repositories are both exporting different trees ++to the same special remote, it's possible for an export conflict to occur. ++This leaves the special remote with some files from one tree, and some ++files from the other. Files in the special remote may have entirely the ++wrong content as well. ++.PP ++It's not possible for git-annex to detect when making an export will result ++in an export conflict. The best way to avoid export conflicts is to either ++only ever export to a special remote from a single repository, or to have a ++rule about the tree that you export to the special remote. For example, if ++you always export origin/master after pushing to origin, then an export ++conflict can't happen. ++.PP ++An export conflict can only be detected after the two git repositories ++that produced it get back in sync. Then the next time you run git annex ++export, it will detect the export conflict, and resolve it. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-initremote(1) ++.PP ++git-annex\-import(1) ++.PP ++git-annex\-push(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++.SH HISTORY ++The \fBexport\fP command was introduced in git-annex version 6.20170925. ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-extendcluster.1 +@@ -0,0 +1,39 @@ ++.TH git-annex-extendcluster 1 ++.SH NAME ++git-annex-extendcluster \- add an additional gateway to a cluster ++.PP ++.SH SYNOPSIS ++git-annex extendcluster gateway clustername ++.PP ++.SH DESCRIPTION ++This command is used to configure a repository to serve as an additional ++gateway to a cluster. It is run in that repository. ++.PP ++The repository this command is run in should have a remote that is a ++gateway to the cluster. The \fBgateway\fP parameter is the name of that remote. ++The \fBclustername\fP parameter is the name of the cluster. ++.PP ++The next step after running this command is to configure ++any additional cluster nodes that this gateway serves to the cluster, ++then run git-annex\-updatecluster. See the documentation of that ++command for details about configuring nodes. ++.PP ++After running this command in the new gateway repository, it typically ++also needs to be run in the other gateway repositories as well, ++after adding the new gateway repository as a remote. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++.IP "git-annex(1)" ++.IP "git-annex\-initcluster(1)" ++.IP "git-annex\-updatecluster(1)" ++.IP "git-annex\-updateproxy(1)" ++.IP "" ++.IP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-filter-branch.1 +@@ -0,0 +1,135 @@ ++.TH git-annex-filter-branch 1 ++.SH NAME ++git-annex-filter\-branch \- filter information from the git-annex branch ++.PP ++.SH SYNOPSIS ++git annex filter\-branch [...] ++.PP ++.SH DESCRIPTION ++This copies selected information from the git-annex branch into a git ++commit object, and outputs its hash. The git commit can be transported ++to another git repository, and given a branch name such as "foo/git-annex", ++and git-annex there will automatically merge that into its git-annex ++branch. This allows publishing some information from your git-annex branch, ++without publishing the whole thing. ++.PP ++Other ways to avoid publishing information from a git-annex branch, ++or remove information from it include git-annex\-forget(1), the ++\fBannex.private\fP git config, and the \fB\-\-private\fP option to ++git-annex\-initremote(1). Those are much easier to use, but this ++provides full control for those who need it. ++.PP ++With no options, no information at all will be included from the git-annex ++branch. Use options to specify what to include. All options can be specified ++multiple times. ++.PP ++When the repository contains information about a private ++repository (due to \fBannex.private\fP being set, or git-annex initremote ++\-\-private being used), that private information will be included when ++allowed by the options, even though it is not recorded on the git-annex ++branch. ++.PP ++When a repository was created with \fBgit annex initremote \-\-sameas=foo\fP, ++its information will be included when the information for foo is, ++and excluded when foo is excluded. ++.PP ++When a special remote is configured with importtree=yes or exporttree=yes, ++normally the git tree corresponding to the repository is included in ++the git-annex branch, to make sure it does not get garbage collected ++by \fBgit gc\fP. Those trees are *not* included when filtering the git-annex ++branch. Usually this will not cause any problems, but if such a tree does ++get garbage collected, it will prevent accessing files on the special ++remote, until the next time a tree is imported or exported to it. ++.PP ++.SH OPTIONS ++.IP "\fBpath\fP" ++.IP ++Include information about all keys of annexed files in the path. ++.IP ++.IP "file matching options" ++The git-annex\-matching\-options(1) ++can be used to specify which files in a path to include. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Include information about keys referred of annexed files in the branch ++or treeish. ++.IP ++.IP "\fB\-\-key=key\fP" ++Include information about a specific key. ++.IP ++.IP "\fB\-\-all\fP" ++Include information about all keys. ++.IP ++.IP "\fB\-\-include\-key\-information\-for=repo\fP" ++When including information about a key, include information specific to ++this repository. The repository can be specified with a uuid or the name ++of a remote. This option can be used repeatedly to include several ++repositories. ++.IP ++.IP "\fB\-\-include\-all\-key\-information\fP" ++Include key information for all repositories, except any excluded with ++the \fB\-\-exclude\-key\-information\-for\fP option. ++.IP ++.IP "\fB\-\-exclude\-key\-information\-for=repo\fP" ++When including information about a key, exclude information specific to ++this repository. The repository can be specified with a uuid or the name ++of a remote. This option can be used repeatedly to exclude ++several repositories. ++.IP ++.IP "\fB\-\-include\-repo\-config\-for=repo\fP" ++Include configuration specific to this repository. ++The repository can be specified with a uuid or the name of a remote. ++.IP ++This includes the configuration of special remotes, which may include ++embedded credentials, or encryption parameters. It also includes trust ++settings, preferred content, etc. It does not include information ++about any git-annex keys. This option can be used repeatedly to include ++several repositories. ++.IP ++.IP "\fB\-\-include\-all\-repo\-config\fP" ++Include the configuration of all repositories, except for any excluded ++with the \fB\-\-exclude\-repo\-config\-for\fP option. ++.IP ++.IP "\fB\-\-exclude\-repo\-config\-for=repo\fP" ++Exclude configuration specific to this repository. ++The repository can be specified with a uuid or the name of a remote. ++This option can be used repeatedly to exclude several repositories. ++.IP ++.IP "\fB\-\-include\-global\-config\fP" ++Include global configuration, that is not specific to any repository. ++.IP ++This includes configs stored by git-annex\-numcopies(1), ++git-annex\-config(1), etc. ++.IP ++.SH EXAMPLES ++You have a big git-annex repository and are splitting the directory "foo" ++out, to make a smaller repository. You want the smaller repo's git-annex ++branch to contain all the information about remotes and other configuration, ++but only information about keys in that directory. ++.PP ++ git-annex filter\-branch foo \-\-include\-all\-key\-information \\ ++ \-\-include\-all\-repo\-config \-\-include\-global\-config ++.PP ++That only includes information about the keys that are currently ++in the directory "foo", not keys used by old versions of files. ++To also include information about the version of the subdir in ++tag "1.0", add the option \fB\-\-branch=1.0:foo\fP ++.PP ++Your repository has a special remote "bar", and you want to share information ++about which annexed files are stored in it, but without sharing anything ++about the configuration of the remote. ++.PP ++ git-annex filter\-branch \-\-all \-\-include\-all\-key\-information \\ ++ \-\-include\-all\-repo\-config \-\-exclude\-repo\-config\-for=bar \\ ++ \-\-include\-global\-config ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-forget(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-filter-process.1 +@@ -0,0 +1,48 @@ ++.TH git-annex-filter-process 1 ++.SH NAME ++git-annex-filter\-process \- long running git filter process for git-annex ++.PP ++.SH SYNOPSIS ++git annex filter\-process ++.PP ++.SH DESCRIPTION ++When this is not enabled, each file that git wants to filter involves ++starting up a new \fBgit-annex smudge\fP process. Starting many such processes ++for many files can be slow, and can make commands like \fBgit checkout\fP and ++\fBgit add\fP slow when they are operating on a lot of files. (A lot of locked ++annexed files do not make \fBgit checkout\fP slow, but unlocked files and ++non\-annexed files do slow it down.) ++.PP ++On the other hand when this is enabled, \fBgit add\fP of a large file does an ++unnecessary extra read of the file, and pipes its contents into git-annex. ++So when this is enabled, it will be faster to use \fBgit-annex add\fP to add ++large files to the annex, rather than \fBgit add\fP. Other commands that ++add files, like \fBgit commit \-a\fP, are also impacted by this. ++.PP ++This is used by default in git-annex repositories v9 and above, while ++v8 repositories use \fBgit-annex smudge\fP for backwards compatability with ++older versions of git-annex. ++.PP ++To enable this in a v8 repository, run: ++.PP ++ git config filter.annex.process 'git-annex filter\-process' ++.PP ++To disable it, you can just unset the config: ++.PP ++ git config \-\-unset filter.annex.process ++.PP ++There will be no visible difference in behavior between enabling this and ++not, besides changes in speed and memory use when using git. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++git-annex\-smudge(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-find.1 +@@ -0,0 +1,84 @@ ++.TH git-annex-find 1 ++.SH NAME ++git-annex-find \- lists available files ++.PP ++.SH SYNOPSIS ++git annex find \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Outputs a list of annexed files in the specified path. With no path, ++finds files in the current directory and its subdirectories. ++.PP ++.SH OPTIONS ++.IP "matching options" ++.IP ++The git-annex\-matching\-options(1) ++can be used to specify files to list. ++.IP ++By default, the find command only lists annexed files whose content is ++currently present. Specifying any of the matching options will override ++this default behavior. ++.IP ++To list all annexed files, present or not, specify \fB\-\-anything\fP. ++.IP ++To list annexed files whose content is not present, specify \fB\-\-not \-\-in=here\fP ++.IP ++.IP "\fB\-\-branch=ref\fP" ++List files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-print0\fP" ++Output filenames terminated with nulls, for use with \fBxargs \-0\fP ++.IP ++.IP "\fB\-\-format=value\fP" ++Use custom output formatting. ++.IP ++The value is a format string, in which '${var}' is expanded to the ++value of a variable. To right\-justify a variable with whitespace, ++use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; ++to escape unusual characters (including control characters) ++in a variable, use '${escaped_var}' ++.IP ++These variables are available for use in formats: file, key, backend, ++bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for ++the mtime field of a WORM key). ++.IP ++Also, '\\n' is a newline, '\\000' is a NULL, etc. ++.IP ++The default output format is the same as \fB\-\-format='${file}\\n'\fP, ++except when outputting to a terminal, control characters will be escaped. ++.IP ++.IP "\fB\-\-json\fP" ++Output the list of files in JSON format. ++.IP ++This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which a file is read in a line from stdin, ++its information displayed, and repeat. ++.IP ++Note that if the file is not an annexed file, or is not present, ++or otherwise doesn't meet the matching options, an empty line ++will be output instead. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-whereis(1) ++.PP ++git-annex\-findkeys(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-findcomputed.1 +@@ -0,0 +1,92 @@ ++.TH git-annex-findcomputed 1 ++.SH NAME ++git-annex-findcomputed \- lists computed files ++.PP ++.SH SYNOPSIS ++git annex findcomputed \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Outputs a list of files in the specified path that can be computed by ++enabled compute special remotes. With no path, lists files in the current ++directory and its subdirectories. ++.PP ++Along with the name of each computed file, this displays the input that ++was provided to git-annex\-addcomputed(1). ++.PP ++For example: ++.PP ++# git-annex findcomputed ++foo.jpeg (imageconvert) \-\- convert file.raw file.jpeg passes=10 ++bar.gz (compressor) \-\- compress bar \-\-level=9 ++.PP ++.SH OPTIONS ++.IP "matching options" ++.IP ++The git-annex\-matching\-options(1) ++can be used to specify files to list. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++List computed files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-inputs\fP" ++Display each computed file followed by the input that is used to ++produce it. The current location of the input file in the work tree is ++displayed, but if the input file is not in the work tree, the key ++is displayed instead. ++.IP ++For example: ++.IP ++foo.jpeg file.raw ++bar.gz bar ++.IP ++When multiple input files are needed to compute a file, outputs multiple ++lines for that file: ++.IP ++foo bar ++foo baz ++.IP ++.IP "\fB\-\-format=value\fP" ++Use custom output formatting. ++.IP ++This option works the same as in git-annex\-find(1), with these ++additional variables available for use in it: ++"${remote}", "${computation}" ++.IP ++The default output format is the same as ++\fB\-\-format='${file} (${remote}) \-\- ${computation}\\n'\fP, ++except when outputting to a terminal, control characters will be escaped. ++.IP ++When \fB\-\-inputs\fP is used, there are additional variables "${inputfile}" ++which is the input filename, "${inputkey}" which is the input key, ++and "${input}" which is either the filename or the key. ++The default output format for \fB\-\-inputs\fP ++is the same as \fB\-\-format='${file} ${input}\\n'\fP ++To separate the pair of files by nulls instead, use eg ++\-\-format='${file}\\000${input}\\n' ++.IP ++.IP "\fB\-\-json\fP" ++Output the list of files in JSON format. ++.IP ++This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-addcomputed(1) ++.PP ++git-annex\-recompute(1) ++.PP ++git-annex\-findcomputed(1) ++.PP ++git-annex\-find(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-findkeys.1 +@@ -0,0 +1,66 @@ ++.TH git-annex-findkeys 1 ++.SH NAME ++git-annex-findkeys \- lists available keys ++.PP ++.SH SYNOPSIS ++git annex findkeys ++.PP ++.SH DESCRIPTION ++Outputs a list of keys known to git-annex. ++.PP ++.SH OPTIONS ++.IP "matching options" ++.IP ++The git-annex\-matching\-options(1) ++can be used to specify which keys to list. ++.IP ++By default, the findkeys command only lists keys whose content is ++currently present. Specifying any of the matching options will override ++this default behavior and match on all keys that git-annex knows about. ++.IP ++To list all keys, present or not, specify \fB\-\-anything\fP. ++.IP ++To list keys whose content is not present, specify \fB\-\-not \-\-in=here\fP ++.IP ++.IP "\fB\-\-print0\fP" ++Output keys terminated with nulls, for use with \fBxargs \-0\fP ++.IP ++.IP "\fB\-\-format=value\fP" ++Use custom output formatting. ++.IP ++The value is a format string, in which '${var}' is expanded to the ++value of a variable. To right\-justify a variable with whitespace, ++use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; ++to escape unusual characters (including control characters) ++in a variable, use '${escaped_var}' ++.IP ++These variables are available for use in formats: key, backend, ++bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for ++the mtime field of a WORM key). ++.IP ++Also, '\\n' is a newline, '\\000' is a NULL, etc. ++.IP ++The default output format is the same as \fB\-\-format='${escapedkey}\\n'\fP ++except when outputting to a terminal, control characters will be escaped. ++.IP ++.IP "\fB\-\-json\fP" ++Output the list of keys in JSON format. ++.IP ++This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-find(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-findref.1 +@@ -0,0 +1,23 @@ ++.TH git-annex-findref 1 ++.SH NAME ++git-annex-findref \- lists files in a git ref (deprecated) ++.PP ++.SH SYNOPSIS ++git annex findref \fB[ref]\fP ++.PP ++.SH DESCRIPTION ++This is the same as \fBgit annex find\fP with the \-\-branch option, and you're ++encouraged to use that instead unless you need to support older versions of ++git-annex. ++.PP ++.SH OPTIONS ++Same as git-annex\-find(1) ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-fix.1 +@@ -0,0 +1,42 @@ ++.TH git-annex-fix 1 ++.SH NAME ++git-annex-fix \- fix up links to annexed content ++.PP ++.SH SYNOPSIS ++git annex fix \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Fixes up symlinks that have become broken to again point to annexed ++content. ++.PP ++This is useful to run manually when you have been moving the symlinks ++around, but is done automatically when committing a change with git too. ++.PP ++Also, adjusts unlocked files to be copies or hard links as ++configured by annex.thin. ++.PP ++.SH OPTIONS ++.IP "file matching options" ++.IP ++The git-annex\-matching\-options(1) ++can be used to specify files to fix. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-fsck(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-forget.1 +@@ -0,0 +1,38 @@ ++.TH git-annex-forget 1 ++.SH NAME ++git-annex-forget \- prune git-annex branch history ++.PP ++.SH SYNOPSIS ++git annex forget ++.PP ++.SH DESCRIPTION ++Causes the git-annex branch to be rewritten, throwing away historical ++data about past locations of files. The resulting branch will use less ++space, but \fBgit annex log\fP will not be able to show where ++files used to be located. ++.PP ++When this rewritten branch is merged into other clones of ++the repository, \fBgit-annex\fP will automatically perform the same rewriting ++to their local \fBgit-annex\fP branches. So the forgetfulness will automatically ++propagate out from its starting point until all repositories running ++git-annex have forgotten their old history. (You may need to force ++git to push the branch to any git repositories not running git-annex.) ++.PP ++.SH OPTIONS ++.IP "\fB\-\-drop\-dead\fP" ++.IP ++Also prune references to repositories that have been marked as dead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-dead(1) ++.PP ++git-annex\-filter\-branch(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-fromkey.1 +@@ -0,0 +1,52 @@ ++.TH git-annex-fromkey 1 ++.SH NAME ++git-annex-fromkey \- adds a file using a specific key ++.PP ++.SH SYNOPSIS ++git annex fromkey \fB[key file ...]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command can be used to manually set up a file ++in the git repository to link to a specified key. ++.PP ++Multiple pairs of file and key can be given in a single command line. ++.PP ++If no key and file pair are specified on the command line, batch input ++is used, the same as if the \-\-batch option were specified. ++.PP ++Normally the key is a git-annex formatted key. However, to make it easier ++to use this to add urls, if the key cannot be parsed as a key, and is a ++valid url, an URL key is constructed from the url. Note that this does not ++register the url as a location of the key; use git-annex\-registerurl(1) ++to do that. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-force\fP" ++.IP ++Allow making a file link to a key whose content is not in the local ++repository. The key may not be known to git-annex at all. ++.IP ++.IP "\fB\-\-batch\fP" ++In batch input mode, lines are read from stdin, and each line ++should contain a key and filename, separated by a single space. ++.IP ++.IP "\fB\-z\fP" ++When in batch mode, the input is delimited by nulls instead of the usual ++newlines. ++.IP ++(Note that for this to be used, you have to explicitly enable batch mode ++with \fB\-\-batch\fP) ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-fsck.1 +@@ -0,0 +1,122 @@ ++.TH git-annex-fsck 1 ++.SH NAME ++git-annex-fsck \- find and fix problems ++.PP ++.SH SYNOPSIS ++git annex fsck \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++This command checks annexed files for consistency, and warns about or ++fixes any problems found. This is a good complement to \fBgit fsck\fP. ++.PP ++The default is to check all annexed files in the current directory and ++subdirectories. With parameters, only the specified files are checked. ++.PP ++The problems fsck finds include files that have gotten corrupted, ++files whose content has somehow become lost, files that do not have the ++configured number of copies yet made, and keys that can be upgraded to a ++better format. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-from=remote\fP" ++.IP ++Check a remote, rather than the local repository. ++.IP ++Note that by default, files will be copied from the remote to check ++their contents. To avoid this expensive transfer, and only ++verify that the remote still has the files that are expected to be on it, ++add the \fB\-\-fast\fP option. ++.IP ++.IP "\fB\-\-fast\fP" ++Avoids expensive checksum calculations (and expensive transfers when ++fscking a remote). ++.IP ++.IP "\fB\-\-incremental\fP" ++Start a new incremental fsck pass, clearing records of all files that ++were checked in the previous incremental fsck pass. ++.IP ++.IP "\fB\-\-more\fP" ++Skip files that were checked since the last incremental fsck pass ++was started. ++.IP ++Note that before \fB\-\-incremental\fP is used to start an incremental fsck ++pass, files that are checked are still recorded, and using this option ++will skip checking those files again. ++.IP ++Resuming may redundantly check some files that were checked ++before. Any files that fsck found problems with before will be re\-checked ++on resume. Also, checkpoints are made every 1000 files or every 5 minutes ++during a fsck, and it resumes from the last checkpoint, so if an ++incremental fsck is interrupted using eg ctrl\-c, it will recheck files ++that didn't get into the last checkpoint. ++.IP ++.IP "\fB\-\-incremental\-schedule=time\fP" ++This makes a new incremental fsck be started only a specified ++time period after the last incremental fsck was started. ++.IP ++The time is in the form "10d" or "300h". ++.IP ++Maybe you'd like to run a fsck for 5 hours at night, picking up each ++night where it left off. You'd like this to continue until all files ++have been fscked. And once it's done, you'd like a new fsck pass to start, ++but no more often than once a month. Then put this in a nightly cron job: ++.IP ++ git annex fsck \-\-incremental\-schedule 30d \-\-time\-limit 5h ++.IP ++.IP "\fB\-\-numcopies=N\fP" ++Override the normally configured number of copies. ++.IP ++To verify data integrity only while disregarding required number of copies, ++use \fB\-\-numcopies=1\fP. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Normally only the files in the currently checked out branch ++are fscked. This option causes all versions of all files to be fscked. ++.IP ++This is the default behavior when running git-annex in a bare repository. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Operate on files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-unused\fP" ++Operate on files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Use this option to fsck a specified key. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to control what to fsck. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Runs multiple fsck jobs in parallel. For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-quiet\fP" ++Like all git-annex commands, this option makes only error and warning ++messages be displayed. This is particularly useful with fsck, which ++normally displays all the files it's checking even when there is no ++problem with them. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-repair(1) ++.PP ++git-annex\-expire(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-fuzztest.1 +@@ -0,0 +1,23 @@ ++.TH git-annex-fuzztest 1 ++.SH NAME ++git-annex-fuzztest \- generates fuzz test files ++.PP ++.SH SYNOPSIS ++git annex fuzztest ++.PP ++.SH DESCRIPTION ++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. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-get.1 +@@ -0,0 +1,135 @@ ++.TH git-annex-get 1 ++.SH NAME ++git-annex-get \- make content of annexed files available ++.PP ++.SH SYNOPSIS ++git annex get \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Makes the content of annexed files available in this repository. This ++will involve copying them from a remote repository, or downloading them, ++or transferring them from some kind of key\-value store. ++.PP ++With no parameters, gets all annexed files in the current directory whose ++content was not already present. Paths of files or directories to get can ++be specified. ++.PP ++.SH EXAMPLES ++ # evince foo.pdf ++ error: Unable to open document foo.pdf: No such file or directory ++ # ls foo.pdf ++ foo.pdf@ ++ # git annex get foo.pdf ++ get foo.pdf (from origin..) ok ++ # evince foo.pdf ++.PP ++.SH OPTIONS ++.IP "\fB\-\-auto\fP" ++.IP ++Rather than getting all the specified files, get only those that don't yet ++have the desired number of copies, or that are preferred content of the ++repository. See git-annex\-preferred\-content(1) ++.IP ++.IP "\fB\-\-from=remote\fP" ++Normally git-annex will choose which remotes to get the content ++from, preferring remotes with lower costs. Use this option to specify ++which remote to use. ++.IP ++Any files that are not available on the remote will be silently skipped. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel download with up to the specified number of jobs ++running at once. For example: \fB\-J10\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++When files can be downloaded from multiple remotes, enabling parallel ++downloads will split the load between the remotes. For example, if ++the files are available on remotes A and B, then one file will be ++downloaded from A, and another file will be downloaded from B in ++parallel. (Remotes with lower costs are still preferred over higher cost ++remotes.) ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to control what to get. ++.IP ++.IP "\fB\-\-incomplete\fP" ++Resume any incomplete downloads of files that were started and ++interrupted at some point previously. Useful to pick up where you left ++off ... when you don't quite remember where that was. ++.IP ++These incomplete files are the same ones that are ++listed as unused temp files by git-annex\-unused(1). ++.IP ++Note that the git-annex key will be displayed when downloading, ++as git-annex does not know the associated file, and the associated file ++may not even be in the current git working directory. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Rather than specifying a filename or path to get, this option can be ++used to get all available versions of all files. ++.IP ++This is the default behavior when running git-annex in a bare repository. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Operate on files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-unused\fP" ++Operate on files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-failed\fP" ++Operate on files that have recently failed to be transferred. ++.IP ++Not to be confused with \fB\-\-incomplete\fP which resumes only downloads ++that managed to transfer part of the content of a file. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Use this option to get a specified key. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which lines containing names of files to get ++are read from stdin. ++.IP ++As each specified file is processed, the usual progress output is ++displayed. If the specified file's content is already present, ++or it does not match specified matching options, or ++it is not an annexed file, a blank line is output in response instead. ++.IP ++Since the usual output while getting a file is verbose and not ++machine\-parseable, you may want to use \-\-json in combination with ++\-\-batch. ++.IP ++.IP "\fB\-\-batch\-keys\fP" ++This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. ++.IP ++.IP "\fB\-z\fP" ++Makes batch input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-drop(1) ++.PP ++git-annex\-copy(1) ++.PP ++git-annex\-move(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-group.1 +@@ -0,0 +1,38 @@ ++.TH git-annex-group 1 ++.SH NAME ++git-annex-group \- add a repository to a group ++.PP ++.SH SYNOPSIS ++git annex group \fBrepository [groupname]\fP ++.PP ++.SH DESCRIPTION ++Adds a repository to a group, such as "archive" or "transfer". ++The groupname must be a single word. ++.PP ++Omit the groupname to show the current groups that a repository is in. ++.PP ++There are some standard groups that have different default preferred content ++settings. See ++.PP ++A repository can be in multiple groups at the same time. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-list\fP" ++.IP ++Outputs a list of all groups that are used by at least one repository. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-ungroup(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++git-annex\-wanted(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-groupwanted.1 +@@ -0,0 +1,42 @@ ++.TH git-annex-groupwanted 1 ++.SH NAME ++git-annex-groupwanted \- get or set groupwanted expression ++.PP ++.SH SYNOPSIS ++git annex groupwanted \fBgroupname [expression]\fP ++.PP ++.SH DESCRIPTION ++Sets or displays the groupwanted expression. This will be used by ++repositories that are in the group, and that have their preferred ++content expression set to "groupwanted". ++.PP ++For example, to configure a group named redundantarchive, and ++make repositories in the group want to contain 3 copies of every file: ++.PP ++ git annex groupwanted redundantarchive "not (copies=redundantarchive:3)" ++ for repo in foo bar baz; do ++ git annex group $repo redundantarchive ++ git annex wanted $repo groupwanted ++ done ++.PP ++Note that there must be exactly one groupwanted expression configured ++amoung all the groups that a repository is in; if there's more than one, ++none of them will be used. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-group(1) ++.PP ++git-annex\-wanted(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-import.1 +@@ -0,0 +1,228 @@ ++.TH git-annex-import 1 ++.SH NAME ++git-annex-import \- import files from a special remote ++.PP ++.SH SYNOPSIS ++git annex import \-\-from remote branch[:subdir] | \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++This command is a way to import a tree of files from elsewhere into your ++git-annex repository. It can import files from a git-annex special remote, ++or from a directory. ++.PP ++.SH IMPORTING FROM A SPECIAL REMOTE ++Importing from a special remote first downloads or hashes all new content ++from it, and then constructs a git commit that reflects files that have ++changed on the special remote since the last time git-annex looked at it. ++Merging that commit into your repository will update it to reflect changes ++made on the special remote. ++.PP ++This way, something can be using the special remote for file storage, ++adding files, modifying files, and deleting files, and you can track those ++changes using git-annex. ++.PP ++You can combine using \fBgit annex import\fP to fetch changes from a special ++remote with \fBgit annex export\fP to send your local changes to the special ++remote. ++.PP ++You can only import from special remotes that were configured with ++\fBimporttree=yes\fP when set up with git-annex\-initremote(1). Only some ++kinds of special remotes will let you configure them this way. A perhaps ++non\-exhaustive list is the directory, s3, and adb special remotes. ++.PP ++To import from a special remote, you must specify the name of a branch. ++A corresponding remote tracking branch will be updated by \fBgit annex import\fP. ++After that point, it's the same as if you had run a \fBgit fetch\fP ++from a regular git remote; you can merge the changes into your ++currently checked out branch. ++.PP ++For example: ++.PP ++ git annex import master \-\-from myremote ++ git annex merge \-\-allow\-unrelated\-histories myremote/master ++.PP ++You could just as well use \fBgit merge \-\-allow\-unrelated\-histories myremote/master\fP ++as the second step, but using \fBgit-annex merge\fP avoids a couple of gotchas. ++When using adjusted branches, it adjusts the branch before merging from it. ++.PP ++The \-\-allow\-unrelated\-histories option is needed for at least the first ++merge of an imported remote tracking branch, since the branch's history is ++not connected. Think of this as the remote being a separate git repository ++with its own files. If you first \fBgit annex export\fP files to a remote, and ++then \fBgit annex import\fP from it, you won't need that option. ++.PP ++You can import into a subdirectory, using the "branch:subdir" syntax. For ++example, if "camera" is a special remote that accesses a camera, and you ++want to import those into the photos directory, rather than to the root of ++your repository: ++.PP ++ git annex import master:photos \-\-from camera ++ git merge camera/master ++.PP ++The \fBgit annex sync \-\-content\fP command (and the git-annex assistant) ++can also be used to import from a special remote. ++To do this, you need to configure "remote..annex\-tracking\-branch" ++to tell it what branch to track. For example: ++.PP ++ git config remote.myremote.annex\-tracking\-branch master ++ git annex sync \-\-content ++.PP ++Any files that are gitignored will not be included in the import, ++but will be left on the remote. ++.PP ++When the special remote has a preferred content expression set by ++git-annex\-wanted(1), that is used to pick which files to import from ++it. Files that are not preferred content of the remote will not be ++imported from it, but will be left on the remote. ++.PP ++So for example, a preferred content expression like ++\fB"include=*.jpeg or largerthan=100mb"\fP will make only jpegs and ++large files be imported. ++.PP ++Parts of a preferred content expression that relate to the key, ++such as "copies=" are ignored when importing, because the key ++is not known before importing. ++.PP ++Things in the expression like "include=" match relative to the top of ++the tree of files on the remote, even when importing into a subdirectory. ++.PP ++.SH OPTIONS FOR IMPORTING FROM A SPECIAL REMOTE ++.IP "\fB\-\-content\fP, \fB\-\-no\-content\fP" ++.IP ++Controls whether annexed content is downloaded from the special remote. ++.IP ++The default is to download content into the git-annex repository. ++.IP ++With \-\-no\-content, git-annex keys are generated from information ++provided by the special remote, without downloading it. Commands like ++\fBgit-annex get\fP can later be used to download files, as desired. ++The \-\-no\-content option is not supported by all special remotes. ++.IP ++.IP "\fB\-\-message=msg\fP \fB\-m msg\fP" ++Use this option to specify a commit message for the changes that have ++been made to the special remote since the last import from it. ++.IP ++If multiple \-m options are given, their values are concatenated ++as separate paragraphs. ++.IP ++.SH IMPORTING FROM A DIRECTORY ++When run with a path, \fBgit annex import\fP **moves** files from somewhere outside ++the git working copy, and adds them to the annex. In contrast to importing ++from a special directory remote, imported files are **deleted from the given ++path**. ++.PP ++This is a legacy interface. It is still supported, but please consider ++switching to importing from a directory special remote instead, using the ++interface documented above. ++.PP ++Individual files to import can be specified. If a directory is specified, ++the entire directory is imported. Please note that the following instruction ++will **delete all files from the source directory**. ++.PP ++ git annex import /media/camera/DCIM/* ++.PP ++When importing files, there's a possibility of importing a duplicate ++of a file that is already known to git-annex \-\- its content is either ++present in the local repository already, or git-annex knows of another ++repository that contains it, or it was present in the annex before but has ++been removed now. ++.PP ++By default, importing a duplicate of a known file will result in ++a new filename being added to the repository, so the duplicate file ++is present in the repository twice. (With all checksumming backends, ++including the default SHA256E, only one copy of the data will be stored.) ++.PP ++Several options can be used to adjust handling of duplicate files, see ++\fB\-\-duplicate\fP, \fB\-\-deduplicate\fP, \fB\-\-skip\-duplicates\fP, \fB\-\-clean\-duplicates\fP, ++and \fB\-\-reinject\-duplicates\fP documentation below. ++.PP ++symbolic links in the directory being imported are skipped to avoid ++accidentially importing things outside the directory that import was ran ++on. The directory that import is run on can, however inself be a symbolic ++link, and that symbolic link will be followed. ++.PP ++.SH OPTIONS FOR IMPORTING FROM A DIRECTORY ++.IP "\fB\-\-duplicate\fP" ++.IP ++Do not delete files from the import location. ++.IP ++Running with this option repeatedly can import the same files into ++different git repositories, or branches, or different locations in a git ++repository. ++.IP ++.IP "\fB\-\-deduplicate\fP" ++Only import files that are not duplicates; ++duplicate files will be deleted from the import location. ++.IP ++.IP "\fB\-\-skip\-duplicates\fP" ++Only import files that are not duplicates. Avoids deleting any ++files from the import location. ++.IP ++.IP "\fB\-\-clean\-duplicates\fP" ++Does not import any files, but any files found in the import location ++that are duplicates are deleted. ++.IP ++.IP "\fB\-\-reinject\-duplicates\fP" ++Imports files that are not duplicates. Files that are duplicates have ++their content reinjected into the annex (similar to ++git-annex\-reinject(1)). ++.IP ++.IP "\fB\-\-force\fP" ++Allow existing files to be overwritten by newly imported files. ++.IP ++Also, causes .gitignore to not take effect when adding files. ++.IP ++.IP "file matching options" ++Many of the git-annex\-matching\-options(1) ++can be used to specify files to import. ++.IP ++ git annex import /dir \-\-include='*.png' ++.IP ++.SH COMMON OPTIONS ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++.IP ++Imports multiple files in parallel. This may be faster. ++For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-backend\fP" ++Specifies which key\-value backend to use for the imported files. ++.IP ++.IP "\fB\-\-no\-check\-gitignore\fP" ++Add gitignored files. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH CAVEATS ++Note that using \fB\-\-deduplicate\fP or \fB\-\-clean\-duplicates\fP with the WORM ++backend does not look at file content, but filename and mtime. ++.PP ++If annex.largefiles is configured, and does not match a file, git annex ++import will add the non\-large file directly to the git repository, ++instead of to the annex. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-add(1) ++.PP ++git-annex\-export(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-importfeed.1 +@@ -0,0 +1,129 @@ ++.TH git-annex-importfeed 1 ++.SH NAME ++git-annex-importfeed \- import files from podcast feeds ++.PP ++.SH SYNOPSIS ++git annex importfeed \fB[url ...]\fP ++.PP ++.SH DESCRIPTION ++Imports the contents of podcasts and other rss and atom feeds. Only ++downloads files whose content has not already been added to the repository ++before, so you can delete, rename, etc the resulting files and repeated ++runs won't duplicate them. ++.PP ++When \fByt\-dlp\fP is installed, it can be used to download links in the feed. ++This allows importing e.g., YouTube playlists. ++(However, this is disabled by default as it can be a security risk. ++See the documentation of annex.security.allowed\-ip\-addresses ++in git-annex(1) for details.) ++.PP ++To make the import process add metadata to the imported files from the feed, ++\fBgit config annex.genmetadata true\fP ++.PP ++By default, the downloaded files are put in a directory with the title ++of the feed, and files are named based on the title of the item in the ++feed. This can be changed using the \-\-template option. ++.PP ++Existing files are not overwritten by this command. If "some feed/foo.mp3" ++already exists, it will instead write to "some feed/2\_foo.mp3" ++(or 3, 4, etc). Sometimes a feed will change an item's url, ++resulting in the new url being downloaded to such a filename. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-force\fP" ++.IP ++Force downloading items it's seen before. ++.IP ++.IP "\fB\-\-fast\fP, \fB\-\-relaxed\fP, \fB\-\-verifiable\fP, \fB\-\-raw\fP, \fB\-\-raw\-except\fP" ++These options behave the same as when using git-annex\-addurl(1). ++.IP ++.IP "\fB\-\-fast\fP" ++Avoid immediately downloading urls. The url is still checked ++(via HEAD) to verify that it exists, and to get its size if possible. ++.IP ++.IP "\fB\-\-relaxed\fP" ++Don't immediately download urls, and avoid storing the size of the ++url's content. This makes git-annex accept whatever content is there ++at a future point. ++.IP ++.IP "\fB\-\-raw\fP" ++Prevent special handling of urls by yt\-dlp, bittorrent, and other ++special remotes. This will for example, make importfeed ++download a .torrent file and not the contents it points to. ++.IP ++.IP "\fB\-\-no\-raw\fP" ++Require content pointed to by the url to be downloaded using yt\-dlp ++or a special remote, rather than the raw content of the url. if that ++cannot be done, the import will fail, and the next import of the feed ++will retry. ++.IP ++.IP "\fB\-\-scrape\fP" ++Rather than downloading the url and parsing it as a rss/atom feed ++to find files to import, uses yt\-dlp to screen scrape the equivilant ++of a feed, and imports what it found. ++.IP ++.IP "\fB\-\-template\fP" ++Controls where the files are stored. ++.IP ++The default template is '${feedtitle}/${itemtitle}${extension}' ++.IP ++The available variables in the template include these that ++are information about the feed: feedtitle, feedauthor, feedurl ++.IP ++And these that are information about individual items in the feed: ++itemtitle, itemauthor, itemsummary, itemdescription, itemrights, ++itemid. ++.IP ++Also, title is itemtitle but falls back to feedtitle if the item has no ++title, and author is itemauthor but falls back to feedauthor. ++.IP ++(All of the above are also added as metadata when annex.genmetadata is ++set.) ++.IP ++The extension variable is the extension of the file in the feed, ++or sometimes ".m" if no extension can be determined. ++.IP ++The template also has some variables for when an item was published. ++.IP ++itempubyear (YYYY), itempubmonth (MM), itempubday (DD), itempubhour (HH), ++itempubminute (MM), itempubsecond (SS), ++itempubdate (YYYY\-MM\-DD or if the feed's date cannot be parsed, the raw ++value from the feed). ++.IP ++(These use the UTC time zone, not the local time zone.) ++.IP ++.IP "\fB\-\-no\-check\-gitignore\fP" ++By default, gitignores are honored and it will refuse to download an ++url to a file that would be ignored. This makes such files be added ++despite any ignores. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Runs multiple downloads parallel. For example: \fB\-J4\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-backend\fP" ++Specifies which key\-value backend to use. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-addurl(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-indirect.1 +@@ -0,0 +1,24 @@ ++.TH git-annex-indirect 1 ++.SH NAME ++git-annex-indirect \- switch repository to indirect mode (deprecated) ++.PP ++.SH SYNOPSIS ++git annex indirect ++.PP ++.SH DESCRIPTION ++This command was used to switch a repository back from direct mode ++indirect mode. ++.PP ++Now git-annex automatically converts direct mode repositories to v7 ++with adjusted unlocked branches, so this command does nothing. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-direct(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-info.1 +@@ -0,0 +1,85 @@ ++.TH git-annex-info 1 ++.SH NAME ++git-annex-info \- information about an item or the repository ++.PP ++.SH SYNOPSIS ++git annex info \fB[directory|file|treeish|remote|description|uuid ...]\fP ++.PP ++.SH DESCRIPTION ++Displays statistics and other information for the specified item. ++.PP ++When no item is specified, displays overall information. This includes a ++list of all known repositories, how much annexed data is present in the ++local repository, the total size of all annexed data in the working ++tree, the combined size of annexed data in all repositories, and the annex ++sizes of each repository. ++.PP ++When a directory is specified, displays information ++about the annexed files in that directory (and subdirectories). ++This includes how much annexed data is present in the local repository, ++the total size of all annexed data in the directory, how many files ++have the specified numcopies or more (+1, +2 etc) or less (\-1, \-2 etc), ++and information about how much of the annexed data is stored in known ++repositories. ++.PP ++When a treeish is specified, displays similar information ++as when a directory is specified, but about the annexed files in that ++treeish. ++.PP ++When a remote, or description of a repository, or uuid is specified, ++displays information about the specified repository, including the total ++amount of annexed data stored in it, and a variety of configuration ++information. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-fast\fP" ++.IP ++Only show the information that can be gathered quickly. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-bytes\fP" ++Show file sizes in bytes, disabling the default nicer units. ++.IP ++.IP "\fB\-\-batch\fP" ++Enable batch mode, in which a line containing an item is read from stdin, ++the information about it is output to stdout, and repeat. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-autoenable\fP" ++Display a list of special remotes that have been configured to ++autoenable. ++.IP ++.IP "\fB\-\-dead\-repositories\fP" ++Display a list of repositories that have been marked as dead. ++Such repositories are not displayed in other info displays. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) can be used to select what ++to include in the statistics. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH EXAMPLES ++Suppose you want to run "git annex get .", but ++would first like to see how much disk space that will use. ++Then run: ++.PP ++ git annex info \-\-fast . \-\-not \-\-in here ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-init.1 +@@ -0,0 +1,80 @@ ++.TH git-annex-init 1 ++.SH NAME ++git-annex-init \- initialize git-annex ++.PP ++.SH SYNOPSIS ++git annex init \fB[description]\fP ++.PP ++.SH DESCRIPTION ++Until a repository (or one of its remotes) has been initialized, ++git-annex will refuse to operate on it, to avoid accidentally ++using it in a repository that was not intended to have an annex. ++.PP ++It's useful, but not mandatory, to initialize each new clone ++of a repository with its own description. If you don't provide one, ++one will be generated using the username, hostname and the path. ++.PP ++If any special remotes were configured with autoenable=true, ++this will also attempt to enable them. See git-annex\-initremote(1). ++To prevent that, re\-enable a remote with "autoenable=false", or ++mark it as dead (see git-annex\-dead(1)). ++.PP ++This command is entirely safe, although usually pointless, to run inside an ++already initialized git-annex repository. ++.PP ++A top\-level \fB.noannex\fP file will prevent git-annex init from being used ++in a repository. This is useful for repositories that have a policy ++reason not to use git-annex. The content of the file will be displayed ++to the user who tries to run git-annex init. ++.PP ++The annex.pre\-init\-command git configuration or pre\-init\-annex hook ++is run before initialization and can exit nonzero as well to prevent ++initialization, as well as doing other setup. ++.PP ++.SH EXAMPLES ++ # git annex add foo ++ git-annex: First run: git-annex init ++ # git annex init ++ init ok ++ # git annex add foo ++ add foo ok ++.PP ++.SH OPTIONS ++.IP "\fB\-\-version=N\fP" ++.IP ++Force the repository to be initialized using a different annex.version ++than the current default. ++.IP ++When the version given is not supported, but can be automatically ++upgraded to a newer version, it will use the newer version instead. ++.IP ++.IP "\fB\-\-autoenable\fP" ++Only enable any special remotes that were configured with ++autoenable=true, do not otherwise initialize anything. ++.IP ++.IP "\fB\-\-no\-autoenable\fP" ++Do not enable special remotes that were configured with autoenable=true. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-describe(1) ++.PP ++git-annex\-reinit(1) ++.PP ++git\-init(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-initcluster.1 +@@ -0,0 +1,34 @@ ++.TH git-annex-initcluster 1 ++.SH NAME ++git-annex-initcluster \- initialize a new cluster ++.PP ++.SH SYNOPSIS ++git-annex initcluster name [description] ++.PP ++.SH DESCRIPTION ++This command initializes a new cluster with the specified name. If no ++description is provided, one will be set automatically. ++.PP ++This command should be run in the repository that will serve as the gateway ++to the cluster. ++.PP ++The next step after running this command is to configure ++the cluster nodes, then run git-annex\-updatecluster. See the ++documentation of that command for details about configuring nodes. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++.IP "git-annex(1)" ++.IP "git-annex\-updatecluster(1)" ++.IP "git-annex\-extendcluster(1)" ++.IP "git-annex\-preferred\-content(1)" ++.IP "git-annex\-updateproxy(1)" ++.IP "" ++.IP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-initremote.1 +@@ -0,0 +1,138 @@ ++.TH git-annex-initremote 1 ++.SH NAME ++git-annex-initremote \- creates a special (non\-git) remote ++.PP ++.SH SYNOPSIS ++git annex initremote \fBname type=value [param=value ...]\fP ++.PP ++.SH DESCRIPTION ++Creates a new special remote, and adds it to \fB.git/config\fP. ++.PP ++Example Amazon S3 remote: ++.PP ++ git annex initremote mys3 type=S3 encryption=hybrid keyid=me@example.com datacenter=EU ++.PP ++Many different types of special remotes are supported by git-annex. ++For a list and details, see ++.PP ++The remote's configuration is specified by the parameters passed ++to this command. Different types of special remotes need different ++configuration values, so consult the documentation of a special remote for ++details. The command will prompt for any required parameters you leave out; ++you can also pass \-\-whatelse to see additional parameters. ++.PP ++A few parameters that are supported by all special remotes are documented in ++the next section below. ++.PP ++Once a special remote has been initialized once with this command, ++other clones of the repository can also be set up to access it using ++\fBgit annex enableremote\fP. ++.PP ++The name you provide for the remote can't be one that's been used for any ++other special remote before, because \fBgit-annex enableremote\fP uses the name ++to identify which special remote to enable. If some old special remote ++that's no longer used has taken the name you want to reuse, you might ++want to use \fBgit annex renameremote\fP. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-with\-url\fP" ++.IP ++This configures the remote with an "annex::" url, which allows ++git to push to and pull from it, using git\-remote\-annex. ++.IP ++.IP "\fB\-\-whatelse\fP / \fB\-w\fP" ++Describe additional configuration parameters that you could specify. ++.IP ++For example, if you know you want a S3 remote, but forget how to ++configure it: ++.IP ++ git annex initremote mys3 type=S3 \-\-whatelse ++.IP ++For a machine\-readable list of the parameters, use this with \fB\-\-json\fP. ++.IP ++.IP "\fB\-\-fast\fP" ++When initializing a remote that uses encryption, a cryptographic key is ++created. This requires sufficient entropy. If initremote seems to hang ++or take a long time while generating the key, you may want to Ctrl\-c it ++and re\-run with \fB\-\-fast\fP, which causes it to use a lower\-quality source of ++randomness. (Ie, /dev/urandom instead of /dev/random) ++.IP ++.IP "\fB\-\-sameas=remote\fP" ++Use this when the new special remote uses the same underlying storage ++as some other remote. This will result in the new special remote having ++the same uuid as the specified remote, and either can be used to access ++the same content. ++.IP ++The \fBremote\fP can be the name of a git remote, or the description ++or uuid of any git-annex repository. ++.IP ++When using this option, the new remote inherits the encryption settings ++of the existing remote, so you should not specify any encryption ++parameters. No other configuration is inherited from the existing remote. ++.IP ++This will only work if both remotes use the underlying storage in ++compatible ways. See this page for information about known ++compatabilities. ++ ++.IP ++.IP "\fB\-\-private\fP" ++Avoid recording information about the special remote in the git-annex ++branch. The special remote will only be usable from the repository where ++it was created. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH COMMON CONFIGURATION PARAMETERS ++.IP "\fBencryption\fP" ++.IP ++Almost all special remotes support encryption. You will need to specify ++what encryption, if any, to use. ++.IP ++If you do not want any encryption, use \fBencryption=none\fP ++.IP ++To encrypt to a GPG key, use \fBencryption=hybrid keyid=$keyid ...\fP ++and fill in the GPG key id (or an email address associated with a GPG key). ++.IP ++For details about this and other encrpytion settings, see ++ ++or \-\-whatelse ++.IP ++.IP "\fBautoenable\fP" ++To avoid \fBgit annex enableremote\fP needing to be run, ++you can pass "autoenable=true". Then when git-annex is run in a new clone, ++it will attempt to enable the special remote. Of course, this works best ++when the special remote does not need anything special to be done to get ++it enabled. ++.IP ++.IP "\fBcost\fP" ++Specify this to override the default cost of the special remote. ++This configuration can be overridden by the local git config, ++eg remote.name.annex\-cost. ++.IP ++.IP "\fBuuid\fP" ++Normally, git-annex initremote generates a new UUID for the new special ++remote. If you want to, you can specify a UUID for it to use, by passing a ++uuid=whatever parameter. This can be useful in some unusual situations. ++But if in doubt, don't do this. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-enableremote(1) ++.PP ++git-annex\-configremote(1) ++.PP ++git-annex\-renameremote(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-inprogress.1 +@@ -0,0 +1,63 @@ ++.TH git-annex-inprogress 1 ++.SH NAME ++git-annex-inprogress \- access files while they're being downloaded ++.PP ++.SH SYNOPSIS ++git annex inprogress \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++This command allows accessing the content of an annexed file while ++it is still being downloaded. It outputs to standard output the ++name of the temporary file that is being used to download the specified ++annexed file. ++.PP ++Nothing will be output when the download is from an encrypted or chunked ++special remote. ++.PP ++This can sometimes be used to stream a file before it's been fully ++downloaded, for example: ++.PP ++ git annex get video.mpeg & ++ vlc $(git annex inprogress video.mpeg) ++.PP ++Of course if the file is downloading too slowly, the media player will ++reach the end too soon and not show the whole thing. And of course, only ++some file formats can be usefully streamed in this way. ++.PP ++.SH OPTIONS ++.IP "\fB[path ..]\fP" ++.IP ++The files or directories whose partially downloaded content you want to ++access. ++.IP ++Note that, when no path is specified, it defaults to all files in the ++current working directory, and subdirectories, which can take a while to ++traverse. It's most efficient to specify a the file you are interested ++in, or to use \fB\-\-all\fP ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Rather than specifying a filename or path, this option can be ++used to access all files that are currently being downloaded. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Access the file that is currently being downloaded for the specified key. ++.IP ++.IP "file matching options" ++The git-annex\-matching\-options(1) ++can be used to specify files to access. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH EXIT STATUS ++If any of the requested items are not currently being downloaded, ++the exit status will be 1. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-get(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-list.1 +@@ -0,0 +1,34 @@ ++.TH git-annex-list 1 ++.SH NAME ++git-annex-list \- show which remotes contain files ++.PP ++.SH SYNOPSIS ++git annex list \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Displays a table of remotes that contain the contents of the specified ++files. This is similar to \fBgit annex whereis\fP but a more compact display. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-allrepos\fP" ++.IP ++Only configured remotes are shown by default; this option ++adds all known repositories to the list. ++.IP ++.IP "file matching options" ++The git-annex\-matching\-options(1) ++can be used to specify files to list. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-find(1) ++.PP ++git-annex\-whereis(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-lock.1 +@@ -0,0 +1,43 @@ ++.TH git-annex-lock 1 ++.SH NAME ++git-annex-lock \- lock files to prevent modification ++.PP ++.SH SYNOPSIS ++git annex lock \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Lock the specified annexed files, to prevent them from being modified. ++When no files are specified, all annexed files in the current directory are ++locked. ++.PP ++Locking a file changes how it is stored in the git repository (from a ++pointer file to a symlink), so this command will make a change that you ++can commit. ++.PP ++.SH OPTIONS ++.IP "file matching options" ++.IP ++The git-annex\-matching\-options(1) ++can be used to specify files to lock. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-add(1) ++.PP ++git-annex\-unlock(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-log.1 +@@ -0,0 +1,137 @@ ++.TH git-annex-log 1 ++.SH NAME ++git-annex-log \- shows location log information ++.PP ++.SH SYNOPSIS ++git annex log \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++This command displays information from the history of the git-annex branch. ++.PP ++Several things can prevent that information being available to display. ++When git-annex\-forget is used, old historical ++data gets cleared from the branch. When annex.private or ++remote.name.annex\-private is configured, git-annex does not write ++information to the branch at all. And when annex.alwayscommit is set to ++false, information may not have been committed to the branch yet. ++.PP ++.SH OPTIONS ++.IP "\fB[path ...]\fP" ++.IP ++Displays the location log for the specified file or files, showing each ++repository they were added to ("+") and removed from ("\-"). Note that ++it displays information about the file content currently at these paths, ++not for any different content that was there in earlier commits. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to control what to act on when displaying the location log ++for specified files. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Shows location log changes to all content, with the most recent changes first. ++In this mode, the names of files are not available and keys are displayed ++instead. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Displays the location log for the specified key. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Displays the location log for the files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-unused\fP" ++Displays the location log for files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-sizesof=repository\fP" ++Displays a history of the total size of the annexed files in a repository ++over time from the creation of the repository to the present. ++.IP ++The repository can be "here" for the current repository, or the name of a ++remote, or a repository description or uuid. ++.IP ++Note that keys that do not have a known size are not included in the ++total. ++.IP ++.IP "\fB\-\-sizes\fP" ++This is like \-\-sizesof, but rather than display the size of a single ++repository, it displays the sizes of all known repositories. ++.IP ++The output is a CSV formatted table. ++.IP ++.IP "\fB\-\-totalsizes\fP" ++This is like \fB\-\-sizesof\fP, but it displays the total size of all ++known repositories. ++.IP ++.IP "\fB\-\-interval=time\fP" ++When using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, and \fB\-\-totalsizes\fP, this ++controls the minimum interval between displays of the size. ++The default is to display each new recorded size. ++.IP ++The time is of the form "30d" or "1y". ++.IP ++.IP "\fB\-\-received\fP" ++Combine this option with \fB\-\-sizesof\fP or \fB\-\-sizes\fP to display ++the amount of data received into repositories since the last ++line was output. ++.IP ++.IP "\fB\-\-gnuplot\fP" ++Combine this option with \fB\-\-sizesof\fP or \fB\-\-sizes\fP or \fB\-\-totalsizes\fP ++to use gnuplot(1) to graph the data. The gnuplot file will be left on ++disk for you to reuse. ++.IP ++For example, to graph the sizes of all repositories: ++.IP ++git-annex log \-\-sizes \-\-interval=1d \-\-gnuplot ++.IP ++To graph the amount of new data received into each repository every 30 ++days: ++.IP ++git-annex log \-\-sizes \-\-interval=30d \-\-gnuplot \-\-recieved ++.IP ++.IP "\fB\-\-bytes\fP" ++Show sizes in bytes, disabling the default nicer units. ++.IP ++.IP "\fB\-\-raw\-date\fP" ++Rather than the normal display of a date in the local time zone, ++displays seconds since the unix epoch. ++.IP ++.IP "\fB\-\-since=date\fP, \fB\-\-after=date\fP, \fB\-\-until=date\fP, \fB\-\-before=date\fP, \fB\-\-max\-count=N\fP" ++These options are passed through to \fBgit log\fP, and can be used to limit ++how far back to search for location log changes. ++.IP ++For example: \fB\-\-since "1 month ago"\fP ++.IP ++These options do not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, ++and \fB\-\-totalsizes\fP. ++.IP ++.IP "\fB\-\-gource\fP" ++Generates output suitable for the \fBgource\fP visualization program. ++.IP ++This option does not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, ++and \fB\-\-totalsizes\fP. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++This option does not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, ++and \fB\-\-totalsizes\fP. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++This option does not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, ++and \fB\-\-totalsizes\fP. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-forget(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-lookupkey.1 +@@ -0,0 +1,41 @@ ++.TH git-annex-lookupkey 1 ++.SH NAME ++git-annex-lookupkey \- looks up key used for file ++.PP ++.SH SYNOPSIS ++git annex lookupkey \fB[file ...]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command looks up the key used for a file in the ++index. The key is output to stdout. If there is no key (because ++the file is not present in the index, or is not a git-annex managed file), ++nothing is output, and it exits nonzero. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-ref\fP" ++.IP ++Rather than looking for the specified files in the index, interpet them ++as git refs. For example to find the key used for somefile in tag v1.0: ++.IP ++git-annex lookupkey v1.0:somefile ++.IP ++.IP "\fB\-\-batch\fP" ++Enable batch mode, in which a line containing the filename is read from ++stdin, the key is output to stdout (with a trailing newline), and repeat. ++.IP ++Note that if there is no key corresponding to the file, an empty line is ++output to stdout instead. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-map.1 +@@ -0,0 +1,46 @@ ++.TH git-annex-map 1 ++.SH NAME ++git-annex-map \- generate map of repositories ++.PP ++.SH SYNOPSIS ++git annex map ++.PP ++.SH DESCRIPTION ++Helps you keep track of your repositories, and the connections between them, ++by going out and looking at all the ones it can get to, and generating a ++Graphviz file displaying it all. If the \fBxdot\fP or \fBdot\fP command is available, ++it is used to display the file to your screen. ++.PP ++This command only connects to hosts that the host it's run on can ++directly connect to. It does not try to tunnel through intermediate hosts. ++So it might not show all connections between the repositories in the network ++.PP ++Also, if connecting to a host requires a password, you might have to enter ++it several times as the map is being built. ++.PP ++Note that this subcommand can be used to graph any git repository; it ++is not limited to git-annex repositories. ++.PP ++.SH LEGEND ++Ovals are repositories. White is regular, green is trusted, red is ++untrusted, and grey is dead. ++.PP ++Arrows between repositories are connections via git remotes. ++.PP ++Light blue boxes are hosts that were mapped, and contain the repositories ++on that host. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-fast\fP" ++.IP ++Don't display the generated Graphviz file, but save it for later use. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-matchexpression.1 +@@ -0,0 +1,66 @@ ++.TH git-annex-matchexpression 1 ++.SH NAME ++git-annex-matchexpression \- checks if an expression matches ++.PP ++.SH SYNOPSIS ++git annex matchexpression \fBexpression [data]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command is given a preferred content expression, ++and some data, and checks if the expression matches the data. It exits 0 if ++it matches, and 1 if not. If not enough data was provided, it displays an ++error and exits with special code 42. ++.PP ++For example, this will exit 0: ++.PP ++ git annex matchexpression "include=*.png and largerthan=1mb" \-\-file=foo.png \-\-size=10mb ++.PP ++.SH OPTIONS ++.IP "\fB\-\-file=\fP" ++.IP ++Provide the filename to match against. Note that the file does not have ++to actually exist on disk. ++.IP ++.IP "\fB\-\-size=\fP" ++Tell what the size of the file is. The size can be specified with any ++commonly used units, for example, "0.5 gb" or "100 KiloBytes". ++.IP ++.IP "\fB\-\-key=\fP" ++Tell what key is being matched against. This is needed for ++matching expressions like "copies=N" and "metadata=tag=foo" and ++"present", which all need to look up the information on file for a key. ++.IP ++Many keys have a known size, and so \-\-size is not needed when specifying ++such a key. ++.IP ++.IP "\fB\-\-largefiles\fP" ++Parse the expression as an annex.largefiles expression, rather than a ++preferred content expression. ++.IP ++.IP "\fB\-\-mimetype=\fP" ++Tell what the mime type of the file is. Only needed when using ++\-\-largefiles with a mimetype= expression. ++.IP ++.IP "\fB\-\-mimeencoding=\fP" ++Tell what the mime encoding of the file is. Only needed when using ++\-\-largefiles with a mimeencoding= expression. ++.IP ++.IP "\fB\-\-explain\fP" ++Display explanation of what parts of the preferred content expression ++match, and which parts don't match. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++git-annex\-matching\-expression(1) ++.PP ++git-annex\-sim(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-matching-expression.1 +@@ -0,0 +1,89 @@ ++.TH git-annex-matching-expression 1 ++.SH NAME ++git-annex\-matching\-expression \- specifying a set of files ++.PP ++.SH DESCRIPTION ++The annex.largefiles and annex.addunlocked configurations both use ++expressions that match some files in the working tree. ++.PP ++.SH SYNTAX ++The format of these expressions is similar to ++git-annex\-preferred\-content(1) expressions. ++.PP ++For example: ++.PP ++ largerthan=100kb and not (include=*.c or include=*.h) ++.PP ++This matches large files, but excludes C source files. ++.PP ++The following terms can be used: ++.PP ++.IP "\fBinclude=glob\fP / \fBexclude=glob\fP" ++Specify files to include or exclude. ++.IP ++The glob can contain \fB*\fP and \fB?\fP to match arbitrary characters. ++.IP ++Note that this matches on the whole filename, relative to the top ++of the git directory. So, \fBinclude=foo\fP will include a file \fBfoo\fP ++in the top, but not \fBsubdir/foo\fP. To include both, use ++\fBinclude=foo or include=*/foo\fP ++.IP ++.IP "\fBsmallerthan=size\fP / \fBlargerthan=size\fP" ++Matches only files smaller than, or larger than the specified size. ++.IP ++The size can be specified with any commonly used units, for example, ++"0.5 gb" or "100 KiloBytes" ++.IP ++.IP "\fBmimetype=glob\fP" ++Looks up the MIME type of a file, and checks if the glob matches it. ++.IP ++For example, \fB"mimetype=text/*"\fP will match many varieties of text files, ++including "text/plain", but also "text/x\-shellscript", "text/x\-makefile", ++etc. ++.IP ++The MIME types are the same that are displayed by running \fBfile \-\-mime\-type\fP ++.IP ++This only matches when the content of the file is present in the local ++repository. Usually that is the case, but eg, when importing from a ++special remote with \-\-no\-content, the content is usually not present. ++.IP ++This is only available to use when git-annex was built with the ++MagicMime build flag. ++.IP ++.IP "\fBmimeencoding=glob\fP" ++Looks up the MIME encoding of a file, and checks if the glob matches it. ++.IP ++For example, \fB"mimeencoding=binary"\fP will match many kinds of binary ++files. ++.IP ++The MIME encodings are the same that are displayed by running \fBfile \-\-mime\-encoding\fP ++.IP ++This only matches when the content of the file is present in the local ++repository. Usually that is the case, but eg, when importing from a ++special remote with \-\-no\-content, the content is usually not present. ++.IP ++This is only available to use when git-annex was built with the ++MagicMime build flag. ++.IP ++.IP "\fBanything\fP" ++Matches any file. ++.IP ++.IP "\fBnothing\fP" ++Matches no files. (Same as "not anything") ++.IP ++.IP "\fBnot expression\fP" ++Inverts what the expression matches. ++.IP ++.IP "\fBand\fP / \fBor\fP / \fB( expression )\fP" ++These can be used to build up more complicated expressions. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++ ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-matching-options.1 +@@ -0,0 +1,273 @@ ++.TH git-annex-matching-options 1 ++.SH NAME ++git-annex\-matching\-options \- specifying what to act on ++.PP ++.SH DESCRIPTION ++Many git-annex commands support using these options to specify which ++files they act on. Some of these options can also be used by commands to ++specify which keys they act on. ++.PP ++Arbitrarily complicated expressions can be built using these options. ++For example: ++.PP ++ \-\-include='*.mp3' \-\-and \-( \-\-in=usbdrive \-\-or \-\-in=archive \-) ++.PP ++The above example makes git-annex work on only mp3 files that are present ++in either of two repositories. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-exclude=glob\fP" ++.IP ++Skips files matching the glob pattern. The glob is matched relative to ++the current directory. For example: ++.IP ++ git annex get \-\-exclude='*.mp3' \-\-exclude='subdir/*' ++.IP ++Note that this will not match anything when using \-\-all or \-\-unused. ++.IP ++.IP "\fB\-\-include=glob\fP" ++Skips files not matching the glob pattern. (Same as \fB\-\-not \-\-exclude\fP.) ++For example, to include only mp3 and ogg files: ++.IP ++ git annex get \-\-include='*.mp3' \-\-or \-\-include='*.ogg' ++.IP ++Note that this will not skip anything when using \-\-all or \-\-unused. ++.IP ++.IP "\fB\-\-excludesamecontent=glob\fP" ++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. ++.IP ++For example, to drop files in the archive directory, but not when the same ++content is used by a file in the work directory: ++.IP ++ git annex drop archive/ \-\-excludesamecontent='work/*' ++.IP ++.IP "\fB\-\-includesamecontent=glob\fP" ++Skips files when there is no other file with the same content ++whose name matches the glob. (Same as \fB\-\-not \-\-excludesamecontent\fP) ++.IP ++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: ++.IP ++ git annex find inbox \-\-includesamecontent='outbox/*' ++.IP ++.IP "\fB\-\-in=repository\fP" ++Matches only when git-annex believes that the content is present in a ++repository. ++.IP ++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 \fB\-\-in=here\fP ++.IP ++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. ++.IP ++.IP "\fB\-\-in=repository@{date}\fP" ++Matches only when the content was present in a repository on the given ++date. ++.IP ++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. ++.IP ++For example, you might need to run \fBgit annex drop .\fP to temporarily ++free up disk space. The next day, you can get back the files you dropped ++using \fBgit annex get . \-\-in=here@{yesterday}\fP ++.IP ++.IP "\fB\-\-expected\-present\fP" ++Matches only when git-annex believes that the content is present ++in the local repository. ++.IP ++This is like \fB\-\-in=here\fP, 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. ++.IP ++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: ++\fBgit-annex get \-\-expected\-present\fP ++.IP ++.IP "\fB\-\-copies=number\fP" ++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. ++.IP ++.IP "\fB\-\-copies=trustlevel:number\fP" ++Matches only when git-annex believes there are the specified number of ++copies, on remotes with the specified trust level. For example, ++\fB\-\-copies=trusted:2\fP ++.IP ++To match any trust level at or higher than a given level, ++use 'trustlevel+'. For example, \fB\-\-copies=semitrusted+:2\fP ++.IP ++.IP "\fB\-\-copies=groupname:number\fP" ++Matches only when git-annex believes there are the specified number of ++copies, on remotes in the specified group. For example, ++\fB\-\-copies=archive:2\fP ++.IP ++.IP "\fB\-\-lackingcopies=number\fP" ++Matches only when git-annex believes that the specified number or ++more additional copies need to be made in order to satisfy numcopies ++settings. ++.IP ++.IP "\fB\-\-approxlackingcopies=number\fP" ++Like lackingcopies, but does not look at .gitattributes annex.numcopies ++settings. This makes it significantly faster. ++.IP ++.IP "\fB\-\-inbackend=name\fP" ++Matches only when content is stored using the specified key\-value ++backend. ++.IP ++.IP "\fB\-\-securehash\fP" ++Matches only when content is hashed using a cryptographically ++secure function. ++.IP ++.IP "\fB\-\-inallgroup=groupname\fP" ++Matches only when git-annex believes content is present in ++all repositories in the specified group. ++.IP ++.IP "\fB\-\-onlyingroup=groupname\fP" ++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. ++.IP ++.IP "\fB\-\-smallerthan=size\fP" ++.IP "\fB\-\-largerthan=size\fP" ++Matches only when the content is is smaller than, or larger than the ++specified size. ++.IP ++The size can be specified with any commonly used units, for example, ++"0.5 gb" or "100 KiloBytes" ++.IP ++.IP "\fB\-\-metadata field=glob\fP" ++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. ++.IP ++.IP "\fB\-\-metadata fieldvalue\fP" ++.IP "\fB\-\-metadata field<=value\fP / \fB\-\-metadata field>=value\fP" ++Matches only when there is a metadata field attached with a value ++that is less then or greater than the specified value, respectively. ++.IP ++When both values are numbers, the comparison is done numerically. ++When one value is not a number, the values are instead compared ++lexicographically. ++.IP ++(Note that you will need to quote the second parameter to avoid ++the shell doing redirection.) ++.IP ++.IP "\fB\-\-want\-get\fP" ++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., \fB\-\-not \-\-in=here\fP ++.IP ++.IP "\fB\-\-want\-drop\fP" ++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., \fB\-\-not \-\-in=here\fP ++.IP ++Things that this matches will not necessarily be dropped by ++\fBgit-annex drop \-\-auto\fP. 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. ++.IP ++.IP "\fB\-\-want\-get\-by=repository\fP" ++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., ++\fB\-\-not \-\-in=repository\fP ++.IP ++The repository should be specified using the name of a configured remote, ++or the UUID or description of a repository. \fB\-\-want\-get\-by=here\fP ++is the same as \fB\-\-want\-get\fP. ++.IP ++.IP "\fB\-\-want\-drop\-by=repository\fP" ++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., ++\fB\-\-not \-\-in=repository\fP ++.IP ++The repository should be specified using the name of a configured remote, ++or the UUID or description of a repository. \fB\-\-want\-drop\-by=here\fP ++is the same as \fB\-\-want\-drop\fP. ++.IP ++.IP "\fB\-\-accessedwithin=interval\fP" ++Matches when the content was accessed recently, within the specified time ++interval. ++.IP ++The interval can be in the form "5m" or "1h" or "2d" or "1y", or a ++combination such as "1h5m". ++.IP ++So for example, \fB\-\-accessedwithin=1d\fP matches when the content was ++accessed within the past day. ++.IP ++If the OS or filesystem does not support access times, this will not ++match anything. ++.IP ++.IP "\fB\-\-unlocked\fP" ++Matches annexed files that are unlocked. ++.IP ++.IP "\fB\-\-locked\fP" ++Matches annexed files that are locked. ++.IP ++.IP "\fB\-\-mimetype=glob\fP" ++Looks up the MIME type of a file, and checks if the glob matches it. ++.IP ++For example, \fB\-\-mimetype="text/*"\fP will match many varieties of text files, ++including "text/plain", but also "text/x\-shellscript", "text/x\-makefile", ++etc. ++.IP ++The MIME types are the same that are displayed by running \fBfile \-\-mime\-type\fP ++.IP ++If the file's annexed content is not present, the file will not match. ++.IP ++This is only available to use when git-annex was built with the ++MagicMime build flag. ++.IP ++.IP "\fB\-\-mimeencoding=glob\fP" ++Looks up the MIME encoding of a file, and checks if the glob matches it. ++.IP ++For example, \fB\-\-mimeencoding=binary\fP will match many kinds of binary ++files. ++.IP ++The MIME encodings are the same that are displayed by running \fBfile \-\-mime\-encoding\fP ++.IP ++If the file's annexed content is not present, the file will not match. ++.IP ++This is only available to use when git-annex was built with the ++MagicMime build flag. ++.IP ++.IP "\fB\-\-anything\fP" ++Always matches. One way this can be useful is \fBgit-annex find \-\-anything\fP ++will list all annexed files, whether their content is present or not. ++.IP ++.IP "\fB\-\-nothing\fP" ++Never matches. (Same as \fB\-\-not \-\-anything\fP) ++.IP ++.IP "\fB\-\-not\fP" ++Inverts the next matching option. For example, to match ++when there are less than 3 copies, use \fB\-\-not \-\-copies=3\fP ++.IP ++.IP "\fB\-\-and\fP" ++Requires that both the previous and the next matching option matches. ++The default. ++.IP ++.IP "\fB\-\-or\fP" ++Requires that either the previous, or the next matching option matches. ++.IP ++.IP "\fB\-(\fP" ++Opens a group of matching options. ++.IP ++.IP "\fB\-)\fP" ++Closes a group of matching options. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-maxsize.1 +@@ -0,0 +1,61 @@ ++.TH git-annex-maxsize 1 ++.SH NAME ++git-annex-maxsize \- configure maximum size of a repository ++.PP ++.SH SYNOPSIS ++git annex maxsize repository size ++.PP ++git annex maxsize repository ++.PP ++git annex maxsize ++.PP ++.SH DESCRIPTION ++This configures the maximum combined size of annexed files that can be ++stored in a repository. When run with a repository but without a size, ++it displays the currently configured maxsize. When run without any ++parameters, it displays an overview of the size and maxsize of all ++repositories. ++.PP ++The repository can be specified by git remote name or ++by uuid. For the current repository, use "here". ++.PP ++The size can be specified using any units. For example "100 gigabytes" or ++"0.8TB" ++.PP ++This is advisory only, it does not prevent git-annex from trying to store ++more data in a repository. When a repository has a preferred content ++expression configured using "balanced" or "sizebalanced", it will take the ++maxsize into account when checking preferred content. It is still possible ++for the maxsize to be exceeded, eg when there are multiple writers to the ++same repository. ++.PP ++A hard repository size limit has to be enforced in some other way, ++eg by putting the repository on a partition of the desired size. ++This command can then be used to tell git-annex about that size limit. ++.PP ++For example, if a git repository is on a 1 terabyte drive, and is the only ++thing stored on that drive, and \fBannex.diskreserve\fP is configured to 1 ++gigabyte, then it would make sense to run ++\fBgit-annex maxsize here "999 gigabytes"\fP ++.PP ++To stop checking maximum size of a repository, set the maxsize to 0. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-bytes\fP " ++.IP ++Displays the maximum size in bytes, disabling the default nicer units. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. ++.IP ++.IP "The git-annex\-common\-options(1) can also be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-merge.1 +@@ -0,0 +1,49 @@ ++.TH git-annex-merge 1 ++.SH NAME ++git-annex-merge \- merge changes from remotes ++.PP ++.SH SYNOPSIS ++git annex merge [branch] ++.PP ++.SH DESCRIPTION ++When run without any parameters, this performs the same merging (and merge ++conflict resolution) that is done by the \fBgit-annex pull\fP and \fBgit-annex sync\fP ++commands, but without uploading or downloading any data. ++.PP ++When a branch to merge is specified, this merges it into the current branch, ++using the same merge conflict resolution as the \fBgit-annex pull\fP command. ++This is especially useful on an adjusted branch, because it applies the same ++adjustment to the branch before merging it. ++.PP ++When annex.resolvemerge is set to false, merge conflict resolution ++will not be done. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-allow\-unrelated\-histories\fP, \fB\-\-no\-allow\-unrelated\-histories\fP" ++.IP ++Passed on to \fBgit merge\fP, to control whether or not to merge ++histories that do not share a common ancestor. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also, the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-pull(1) ++.PP ++git-annex\-sync(1) ++.PP ++git-annex\-adjust(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-metadata.1 +@@ -0,0 +1,159 @@ ++.TH git-annex-metadata 1 ++.SH NAME ++git-annex-metadata \- sets or gets metadata of a file ++.PP ++.SH SYNOPSIS ++git annex metadata \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++The content of an annexed file can have any number of metadata fields ++attached to it to describe it. Each metadata field can in turn ++have any number of values. ++.PP ++This command can be used to set metadata, or show the currently set ++metadata. ++.PP ++When run without any \-s or \-t parameters, displays the current metadata. ++.PP ++Each metadata field has its own "field\-lastchanged" metadata, which ++contains the date the field was last changed. Unlike other metadata, ++this cannot be directly modified by this command. It is updated ++automatically. ++.PP ++Note that the metadata is attached to git-annex key corresponding to the ++content of a file, not to a particular filename on a particular git branch. ++All files with the same key share the same metadata, which is ++stored in the git-annex branch. If a file is modified, the metadata ++of the previous version will be copied to the new key when git-annex adds ++the modified file. ++.PP ++.SH OPTIONS ++.IP "\fB\-g field\fP / \fB\-\-get field\fP" ++.IP ++Get the value(s) of a single field. ++.IP ++The values will be output one per line, with no other output, so ++this is suitable for use in a script. ++.IP ++.IP "\fB\-s field=value\fP / \fB\-\-set field=value\fP" ++Set a field's value, removing any old values. ++.IP ++.IP "\fB\-s field+=value\fP / \fB\-\-set field+=value\fP" ++Add an additional value, preserving any old values. ++.IP ++.IP "\fB\-s field?=value\fP / \fB\-\-set field?=value\fP" ++Set a value, but only if the field does not already have a value set. ++.IP ++.IP "\fB\-s field\-=value\fP / \fB\-\-set field\-=value\fP" ++Remove a value from a field, leaving any other values that the field has ++set. ++.IP ++.IP "\fB\-r field\fP / \fB\-\-remove field\fP" ++Remove all current values of the field. ++.IP ++.IP "\fB\-t tag\fP / \fB\-\-tag tag\fP" ++Set a tag. Note that a tag is just a value of the "tag" field. ++.IP ++.IP "\fB\-u tag\fP / \fB\-\-unset tag\fP" ++Unset a tag. ++.IP ++.IP "\fB\-\-remove\-all\fP" ++Remove all metadata from the specified files. ++.IP ++When a file is modified and the new version added, git-annex will copy ++over the metadata from the old version of the file. In situations where ++you don't want that copied metadata, you can use this option to remove ++it. ++.IP ++.IP "\fB\-\-force\fP" ++By default, \fBgit annex metadata\fP refuses to recursively set metadata ++throughout the files in a directory. This option enables such recursive ++setting. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to control what to act on. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Specify instead of a file to get/set metadata on all known keys. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Specify instead of a file to get/set metadata on all files in the ++specified branch or treeish. ++.IP ++.IP "\fB\-\-unused\fP" ++Specify instead of a file to get/set metadata on ++files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Specify instead of a file to get/set metadata of the specified key. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output (and input). Each line is a JSON object. ++.IP ++The format of the JSON objects changed in git-annex version 6.20160726. ++.IP ++Example of the new format: ++.IP ++ {"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true} ++.IP ++Example of the old format, which lacks the inner fields object: ++.IP ++ {"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true} ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, which can be used to both get, store, and unset ++metadata for multiple files or keys. ++.IP ++Batch currently only supports JSON input. So, you must ++enable \fB\-\-json\fP along with \fB\-\-batch\fP. ++.IP ++In batch mode, git-annex reads lines from stdin, which contain ++JSON objects. It replies to each input annexed file ++with an output JSON object. (But if the file is not an annexed file, ++an empty line will be output.) ++.IP ++The format of the JSON sent to git-annex can be the same as the JSON that ++it outputs. Or, a simplified version. Only the "file" (or "key") field ++is actually necessary. ++.IP ++For example, to get the current metadata of file foo: ++.IP ++ {"file":"foo"} ++.IP ++To get the current metadata of the key k: ++ ++ {"key":"k"} ++.IP ++Any metadata fields included in the JSON object will be stored, ++replacing whatever values the fields had before. ++To unset a field, include it with an empty list of values. ++.IP ++To change the author of file foo to bar: ++.IP ++ {"file":"foo","fields":{"author":["bar"]}} ++.IP ++To remove the author of file foo: ++.IP ++ {"file":"foo","fields":{"author":[]}} ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH EXAMPLES ++To set some tags on a file and also its author: ++.PP ++ git annex metadata annexscreencast.ogv \-t video \-t screencast \-s author+=Alice ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-view(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-migrate.1 +@@ -0,0 +1,100 @@ ++.TH git-annex-migrate 1 ++.SH NAME ++git-annex-migrate \- switch data to different backend ++.PP ++.SH SYNOPSIS ++git annex migrate \fB[path ...]\fP ++.PP ++git annex migrate \-\-update ++.PP ++.SH DESCRIPTION ++Changes the specified annexed files to use the default key\-value backend ++(or the one specified with \fB\-\-backend\fP). Only files whose content ++is currently present are migrated. ++.PP ++Note that the content is also still stored using the old keys after ++migration. When possible, hard links are used to avoid that taking up ++extra disk space. Use \fBgit annex unused\fP to find and remove the old keys. ++.PP ++Normally, nothing will be done to specified files that are already using ++the new backend. However, if a backend changes the information it uses to ++construct a key, this can also be used to migrate files to use the new key ++format. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-update\fP" ++.IP ++This updates the local repository for migrations that were performed ++elsewhere. Only new migrations since the last time this was run will ++be performed. ++.IP ++This does not modify the working tree, but only hard links ++(or in some cases copies) annex objects to their new keys. ++.IP ++\fBgit-annex pull\fP and \fBgit-annex sync \-\-content\fP automatically do this, ++unless the \fBannex.syncmigrations\fP config is set to false. ++.IP ++Note that older versions of git-annex did not record migrations in a ++way that this can use. Migrations performed with those older versions ++had to be manually run in each clone of the repository. ++.IP ++.IP "\fB\-\-apply\fP" ++This applies all recorded migrations to the local repository. It is the ++non\-incremental form of \fB\-\-update\fP. ++.IP ++One situation where this can be useful is when git-annex migrate ++\-\-update has been run, but since then un\-migrated ++objects have entered the repository. Using this option ensures that ++any such objects get migrated. ++.IP ++Note that older versions of git-annex did not record migrations in a ++way that this can use. Migrations performed with those older versions ++had to be manually run in each clone of the repository. ++.IP ++.IP "\fB\-\-backend\fP" ++Specify the new key\-value backend to use for migrated data. ++.IP ++.IP "\fB\-\-force\fP" ++Force migration of keys that are already using the new backend. ++.IP ++.IP "file matching options" ++The git-annex\-matching\-options(1) ++can be used to specify files to migrate. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.IP "\fB\-\-remove\-size\fP" ++Keys often include the size of their content, which is generally a useful ++thing. In fact, this command defaults to adding missing size information ++to keys in most migrations. With this option, the size information is ++removed instead. ++.IP ++One use of this option is to convert URL keys that were added ++by \fBgit-annex addurl \-\-fast\fP to ones that would have been added if ++that command was run with the \fB\-\-relaxed\fP option. Eg: ++.IP ++ git-annex migrate \-\-remove\-size \-\-backend=URL somefile ++.IP ++To add back the size to an URL key, use this: ++.IP ++git-annex migrate \-\-backend=URL somefile ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-upgrade(1) ++.PP ++git-annex\-backend(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-mincopies.1 +@@ -0,0 +1,44 @@ ++.TH git-annex-mincopies 1 ++.SH NAME ++git-annex-mincopies \- configure minimum number of copies ++.PP ++.SH SYNOPSIS ++git annex mincopies \fBN\fP ++.PP ++.SH DESCRIPTION ++Tells git-annex how many copies it is required to preserve of files, over all ++repositories. The default is 1. ++.PP ++Run without a number to get the current value. ++.PP ++This configuration is stored in the git-annex branch, so it will be seen ++by all clones of the repository. It can be overridden on a per\-file basis ++by the annex.mincopies setting in .gitattributes files, or can be ++overridden temporarily with the \-\-mincopies option. ++.PP ++This supplements the git-annex\-numcopies(1) setting. ++In unusual situations, involving special remotes that do not support ++locking, and concurrent drops of the same content from multiple ++repositories, git-annex may violate the numcopies setting. ++In these unusual situations, git-annex ensures that the number of copies ++never goes below mincopies. ++.PP ++It is a good idea to not only rely on only setting mincopies. Set ++numcopies as well, to a larger number, and keep mincopies at the ++bare minimum you're comfortable with. Setting mincopies to a large ++number, rather than setting numcopies will in some cases prevent ++droping content in entirely safe situations. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++git-annex\-numcopies(1) ++git-annex\-config(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-mirror.1 +@@ -0,0 +1,85 @@ ++.TH git-annex-mirror 1 ++.SH NAME ++git-annex-mirror \- mirror content of files to/from another repository ++.PP ++.SH SYNOPSIS ++git annex mirror \fB[path ...] [\-\-to=remote|\-\-from=remote]\fP ++.PP ++.SH DESCRIPTION ++This causes a destination repository to mirror a source repository. ++.PP ++Each specified file in the source repository is mirrored to the destination ++repository. If a file's content is present in the source repository, it is ++copied to the destination repository. If a file's content is not present in ++the source repository, it will be dropped from the destination repository ++when the numcopies setting allows. ++.PP ++Note that mirror does not sync the git repository, but only the file ++contents. Use git-annex\-sync(1) for that. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-to=remote\fP" ++.IP ++Use the local repository as the source repository, and mirror its contents ++to the remote. ++.IP ++.IP "\fB\-\-from=remote\fP" ++Use the remote as the source repository, and mirror its contents to the local ++repository. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel transfers with up to the specified number of jobs ++running at once. For example: \fB\-J10\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Mirror all objects stored in the git annex, not only objects used by ++currently existing files. ++.IP ++However, this bypasses checking the .gitattributes annex.numcopies ++setting when dropping files. ++.IP ++This is the default behavior when running git-annex in a bare repository. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Operate on files in the specified branch or treeish. ++.IP ++Like \-\-all, this bypasses checking the .gitattributes annex.numcopies ++setting when dropping files. ++.IP ++.IP "\fB\-\-unused\fP" ++Operate on files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-failed\fP" ++Operate on files that have recently failed to be transferred. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to control what to mirror. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++Note that unlike all other commands that support \fB\-\-json\fP, this command ++outputs different types of json objects in different circumstances. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-sync(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-move.1 +@@ -0,0 +1,123 @@ ++.TH git-annex-move 1 ++.SH NAME ++git-annex-move \- move content of files to/from another repository ++.PP ++.SH SYNOPSIS ++git annex move \fB[path ...] [\-\-from=remote|\-\-to=remote|\-\-to=here]\fP ++.PP ++.SH DESCRIPTION ++Moves the content of files from or to another remote. ++.PP ++With no parameters, operates on all annexed files in the current directory. ++Paths of files or directories to operate on can be specified. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-from=remote\fP" ++.IP ++Move the content of files from the specified remote to the local repository. ++.IP ++.IP "\fB\-\-to=remote\fP" ++Move the content of files from the local repository to the specified remote. ++.IP ++.IP "\fB\-\-to=here\fP" ++Move the content of files from all reachable remotes to the local ++repository. ++.IP ++.IP "\fB\-\-from=remote1 \-\-to=remote2\fP" ++Move the content of files that are in remote1 to remote2. Does not change ++what is stored in the local repository. ++.IP ++This is implemented by first downloading the content from remote1 to the ++local repository (if not already present), then sending it to remote2, and ++then deleting the content from the local repository (if it was not present ++to start with). ++.IP ++.IP "\fB\-\-from\-anywhere \-\-to=remote\fP" ++Move to the remote files from the local repository and from all ++reachable remotes. ++.IP ++.IP "\fB\-\-force\fP" ++Override numcopies and required content checking, and always remove ++files from the source repository once the destination repository has a ++copy. ++.IP ++Note that, even without this option, you can move the content of a file ++from one repository to another when numcopies is not satisfied, as long ++as the move does not result in there being fewer copies. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel transfers with up to the specified number of jobs ++running at once. For example: \fB\-J10\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++Note that when using \-\-from with \-\-to, twice this many jobs will ++run at once, evenly split between the two remotes. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Rather than specifying a filename or path to move, this option can be ++used to move all available versions of all files. ++.IP ++This is the default behavior when running git-annex in a bare repository. ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Operate on files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-unused\fP" ++Operate on files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-failed\fP" ++Operate on files that have recently failed to be transferred. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Use this option to move a specified key. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) ++can be used to control what to move. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which lines containing names of files to move ++are read from stdin. ++.IP ++As each specified file is processed, the usual progress output is ++displayed. If a file's content does not need to be moved, ++or it does not match specified matching options, or it ++is not an annexed file, a blank line is output in response instead. ++.IP ++Since the usual output while moving a file is verbose and not ++machine\-parseable, you may want to use \-\-json in combination with ++\-\-batch. ++.IP ++.IP "\fB\-\-batch\-keys\fP" ++This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. ++.IP ++.IP "\fB\-z\fP" ++Makes batch input be delimited by nulls instead of the usual newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-progress\fP" ++Include progress objects in JSON output. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-get(1) ++.PP ++git-annex\-copy(1) ++.PP ++git-annex\-drop(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-multicast.1 +@@ -0,0 +1,88 @@ ++.TH git-annex-multicast 1 ++.SH NAME ++git-annex-multicast \- multicast file distribution ++.PP ++.SH SYNOPSIS ++git annex multicast [options] ++.PP ++.SH DESCRIPTION ++Multicast allows files to be broadcast to multiple receivers, ++typically on a single local network. ++.PP ++The uftp program is used for multicast. ++ ++.PP ++.SH OPTIONS ++.IP "\fB\-\-gen\-address\fP" ++.IP ++Generates a multicast encryption key and stores a corresponding multicast ++address to the git-annex branch. ++.IP ++.IP "\fB\-\-send [file]\fP" ++Sends the specified files to any receivers whose multicast addresses ++are stored in the git-annex branch. ++.IP ++When no files are specified, all annexed files in the current directory ++and subdirectories are sent. ++.IP ++The git-annex\-matching\-options(1) can be used to control which files to ++send. For example: ++.IP ++ git annex multicast send . \-\-not \-\-copies 2 ++.IP ++.IP "\fB\-\-receive\fP" ++Receives files from senders whose multicast addresses ++are stored in the git-annex brach. ++.IP ++As each file is received, its filename is displayed. This is the filename ++that the sender used; the local working tree may use a different name ++for the file, or not contain a link to the file. ++.IP ++This command continues running, until it is interrupted by you pressing ++ctrl\-c. ++.IP ++Note that the configured annex.diskreserve is not honored by this ++command, because \fBuftpd\fP receives the actual files, and can receive ++any size file. ++.IP ++.IP "\fB\-\-uftp\-opt=option\fP \fB\-Uoption\fP" ++Pass an option on to the uftp/uftpd command. May be specified multiple ++times. ++.IP ++For example, to broadcast at 50 Mbps: ++.IP ++ git annex multicast send \-U\-R \-U50000 ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH EXAMPLE ++Suppose a teacher wants to multicast files to students in a classroom. ++.PP ++This assumes that the teacher and students have cloned a git-annex ++repository, and both can push changes to its git-annex branch, ++or otherwise push changes to each\-other. ++.PP ++First, the teacher runs \fBgit annex multicast \-\-gen\-address; git annex sync\fP ++.PP ++Next, students each run \fBgit annex multicast \-\-gen\-address; git annex sync\fP ++.PP ++Once all the students have generated addresses, the teacher runs ++\fBgit annex sync\fP once more. (Now the students all have received the ++teacher's address, and the teacher has received all the student's addresses.) ++.PP ++Next students each run \fBgit annex multicast \-\-receive\fP ++.PP ++Finally, once the students are all listening (ahem), teacher runs ++\fBgit annex multicast \-\-send\fP ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++uftp(1) ++.PP ++uftpd(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-numcopies.1 +@@ -0,0 +1,41 @@ ++.TH git-annex-numcopies 1 ++.SH NAME ++git-annex-numcopies \- configure desired number of copies ++.PP ++.SH SYNOPSIS ++git annex numcopies \fBN\fP ++.PP ++.SH DESCRIPTION ++Tells git-annex how many copies it should preserve of files, over all ++repositories. The default is 1. ++.PP ++Run without a number to get the current value. ++.PP ++This configuration is stored in the git-annex branch, so it will be seen ++by all clones of the repository. It can be overridden on a per\-file basis ++by the annex.numcopies setting in .gitattributes files, or can be ++overridden temporarily with the \-\-numcopies option. ++.PP ++When git-annex is asked to drop a file, it first verifies that the ++number of copies can be satisfied among all the other ++repositories that have a copy of the file. ++.PP ++In unusual situations, involving special remotes that do not support ++locking, and concurrent drops of the same content from multiple ++repositories, git-annex may violate the numcopies setting. It still ++guarantees at least 1 copy is preserved. This can be configured by ++using git-annex\-mincopies(1) ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++git-annex\-mincopies(1) ++git-annex\-config(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-oldkeys.1 +@@ -0,0 +1,48 @@ ++.TH git-annex-oldkeys 1 ++.SH NAME ++git-annex-oldkeys \- list keys used for old versions of files ++.PP ++.SH SYNOPSIS ++git annex oldkeys \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Lists keys used for old versions of the specified files or directories. ++.PP ++The output from this command can be piped into a command like ++\fBgit-annex drop \-\-batch\-keys\fP ++.PP ++The keys are listed in order from newest to oldest. ++.PP ++When listing old keys for a directory, it will include keys used by deleted ++files that were in that directory in past commits. ++.PP ++.SH OPTIONS ++.IP "\-\-unchecked" ++.IP ++By default this command does not list a key that is also used by any ++file in the currently checked out branch. This option makes it also ++list such keys. ++.IP ++The default behavior avoids surprises when dropping listed keys. ++This option can be useful when eg copying all old versions of a file to a ++remote. ++.IP ++.IP "\-\-revision\-range=value" ++Only list old keys used in the specified range of revisions. ++This works the same as the revision range option of \fBgit log\fP. ++See gitrevisions(7) for documentation about the format of this option. ++.IP ++For example, to list only keys used since the tag v1.0, use ++\fB\-\-revision\-range=v1.0..HEAD\fP ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-unused(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-p2p.1 +@@ -0,0 +1,74 @@ ++.TH git-annex-p2p 1 ++.SH NAME ++git-annex-p2p \- configure peer\-2\-peer links between repositories ++.PP ++.SH SYNOPSIS ++git annex p2p [options] ++.PP ++.SH DESCRIPTION ++This command can be used to link git-annex repositories over peer\-2\-peer ++networks. ++.PP ++Currently, the only P2P network supported by git-annex is Tor hidden ++services. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-pair\fP" ++.IP ++Run this in two repositories to pair them together over the P2P network. ++.IP ++This will print out a code phrase, like "3\-mango\-elephant", and ++will prompt for you to enter the code phrase from the other repository. ++.IP ++Once code phrases have been exchanged, the two repositories will ++be paired. A git remote will be created for the other repository, ++with a name like "peer1". ++.IP ++This uses [Magic Wormhole](https://github.com/warner/magic\-wormhole) ++to verify the code phrases and securely communicate the P2P addresses of ++the repositories, so you will need it installed on both computers that are ++being paired. ++.IP ++This feature was present in a broken form in git-annex versions ++before version 6.20180705. Make sure that a new enough git-annex ++is installed on both computers that are being paired. ++.IP ++.IP "\fB\-\-gen\-addresses\fP" ++Generates addresses that can be used to access this git-annex repository ++over the available P2P networks. The address or addresses is output to ++stdout. ++.IP ++Note that anyone who knows these addresses can access your ++repository over the P2P networks. ++.IP ++This can be run repeatedly, in order to give different addresses ++out to different people. ++.IP ++.IP "\fB\-\-link\fP" ++Sets up a git remote that is accessed over a P2P network. ++.IP ++This will prompt for an address to be entered; you should paste in the ++address that was generated by \-\-gen\-addresses in the remote repository. ++.IP ++Defaults to making the git remote be named "peer1", "peer2", ++etc. This can be overridden with the \fB\-\-name\fP option. ++.IP ++.IP "\fB\-\-name\fP" ++Specify a name to use when setting up a git remote with \fB\-\-link\fP ++or \fB\-\-pair\fP. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-enable\-tor(1) ++.PP ++git-annex\-remotedaemon(1) ++.PP ++wormhole(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-p2phttp.1 +@@ -0,0 +1,179 @@ ++.TH git-annex-p2phttp 1 ++.SH NAME ++git-annex\-p2phttp \- HTTP server for the git-annex API ++.PP ++.SH SYNOPSIS ++git-annex p2phttp ++.PP ++.SH DESCRIPTION ++This is a HTTP server for the git-annex API. ++It is the git-annex equivilant of git\-http\-backend(1), for serving ++a repository over HTTP with write access for authenticated users. ++.PP ++This does not serve a git repository over HTTP, only the git-annex ++API. ++.PP ++By default, this serves the git-annex API for the git-annex repository ++in the current working directory. It can also serve more than one ++repository, see the \fB\-\-directory\fP parameter. ++.PP ++Typically a remote will have \fBremote.name.url\fP set to a http url ++as usual, and \fBremote.name.annexUrl\fP set to an annex+http url such as ++"annex+http://example.com/git-annex/". The annex+http url is ++served by this server, and uses port 9417 by default. ++.PP ++Note that, when \fBremote.name.url\fP and \fBremote.name.annexUrl\fP ++contain the same hostname, they are assumed by git-annex to ++support the same users and passwords. So, git-annex will use ++the password for the \fBremote.name.url\fP to log into the ++\fBremote.name.annexUrl\fP. ++.PP ++As well as serving the git-annex HTTP API, this server provides a ++convenient way to download the content of any key, by using the path ++"/git-annex/$uuid/$key". For example: ++.PP ++ $ curl http://example.com:9417/git-annex/f11773f0\-11e1\-45b2\-9805\-06db16768efe/key/SHA256E\-s6\-\-5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 ++ hello ++.PP ++.SH OPTIONS ++.IP "\fB\-\-directory=path\fP" ++.IP ++Serve each git-annex repository found in immediate ++subdirectories of a directory. ++.IP ++This option can be provided more than once to serve several directories ++full of git-annex repositories. ++.IP ++New git-annex repositories can be added to the directory, and will be ++noticed and served immediately. There is no need to restart the server. ++.IP ++When a git-annex repository is removed from the directory, the server ++will stop serving it as well. This may not be immediate, as some files ++in the deleted repository may still be open. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++This or annex.jobs must be set to configure the number of worker ++threads, per repository served, that serve connections to the webserver. ++.IP ++Since the webserver itself also uses one of these threads, ++this needs to be set to 2 or more. ++.IP ++A good choice is often one worker per CPU core: \fB\-\-jobs=cpus\fP ++.IP ++.IP "\fB\-\-proxyconnections=N\fP" ++When serving a repository that is configured to act as a proxy for some ++of its remotes, this is the maximum number of idle connections to keep ++open to proxied remotes. ++.IP ++The default is 1. ++.IP ++.IP "\fB\-\-clusterjobs=N\fP" ++When serving a repository that is a gateway for a cluster, ++this is the number of concurrent jobs to use to access nodes of the ++cluster, per connection to the webserver. ++.IP ++The default is 1. ++.IP ++A good choice for this will be a balance between the number of nodes ++in the cluster and the value of \fB\-\-jobs\fP. ++.IP ++For example, if the cluster has 4 nodes, and \fB\-\-jobs=4\fP, using ++\fB\-\-clusterjobs=4\fP will make all nodes in the cluster be accessed ++concurrently, which is often optimal. But around 20 cores can be needed ++when the webserver is busy. ++.IP ++.IP "\fB\-\-port=N\fP" ++Port to listen on. The default is port 9417, which is the default ++port used for an annex+http or annex+https url. ++.IP ++It is not recommended to run this command as root in order to ++use a low port like port 80. It will not drop permissions when run as ++root. ++.IP ++.IP "\fB\-\-bind=address\fP" ++What address to bind to. The default is to bind to all addresses. ++.IP ++.IP "\fB\-\-certfile=filename\fP " ++TLS certificate file to use. Combining this with \fB\-\-privatekeyfile\fP ++makes the server use HTTPS. ++.IP ++.IP "\fB\-\-privatekeyfile=filename\fP" ++TLS private key file to use. Combining this with \fB\-\-certfile\fP ++makes the server use HTTPS. ++.IP ++.IP "\fB\-\-chainfile=filename\fP" ++TLS chain file to use. This option can be repeated any number of times. ++.IP ++.IP "\fB\-\-authenv\fP" ++Allows users to be authenticated with a username and password. ++For security, this only allows authentication when the user connects over ++HTTPS. ++.IP ++To configure the passwords, set environment variables ++like \fBGIT_ANNEX_P2PHTTP_PASSWORD_alice=foo123\fP ++.IP ++The permissions of users can also be configured by setting ++environment variables like ++\fBGIT_ANNEX_P2PHTTP_PERMISSIONS_alice=readonly\fP. The value ++can be either "readonly" or "appendonly". When this is not set, ++the default is to give the user full read+write+remove access. ++.IP ++.IP "\fB\-\-authenv\-http\fP" ++Like \fB\-\-authenv\fP, but allows authentication when the user connects ++over HTTP. This is not secure, since HTTP basic authentication is not ++encrypted. ++.IP ++.IP "\fB\-\-unauth\-readonly\fP" ++Allows unauthenticated users to read the repository, but not make ++modifications to it. ++.IP ++This can be combined with \fB\-\-authenv\fP or \fB\-\-authenv\-http\fP to allow ++anonymous readonly access, and authenticated write access. ++.IP ++.IP "\fB\-\-unauth\-appendonly\fP" ++Allows unauthenticated users to read the repository, and store data in ++it, but not remove data from it. ++.IP ++This can be combined with \fB\-\-authenv\fP or \fB\-\-authenv\-http\fP to allow ++anonymous appendonly access, and authenticated remove access. ++.IP ++.IP "\fB\-\-unauth\-nolocking\fP" ++By default, when \fB\-\-unauth\-readonly\fP or \fB\-\-unauth\-appendonly\fP is used, ++unauthenticated users are allowed to lock content in the repository. ++This option prevents that. ++.IP ++Locking content prevents it from being dropped from the repository ++so it may be that an unauthenticated user abuses that, and this option ++can be used in such a situation. ++.IP ++Note that enabling this option will prevent unauthenticated users from ++dropping content from their other remotes in some cases. ++.IP ++.IP "\fB\-\-wideopen\fP" ++Gives unauthenticated users full read+write+remove access to the ++repository. ++.IP ++Please think carefully before enabling this option. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git\-http\-backend(1) ++.PP ++git-annex\-shell(1) ++.PP ++git-annex\-updateproxy(1) ++.PP ++git-annex\-initcluster(1) ++.PP ++git-annex\-updatecluster(1) ++.PP ++ ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++ ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-post-receive.1 +@@ -0,0 +1,39 @@ ++.TH git-annex-post-receive 1 ++.SH NAME ++git-annex-post\-receive \- run by git post\-receive hook ++.PP ++.SH SYNOPSIS ++git annex post\-receive ++.PP ++.SH DESCRIPTION ++This is meant to be called from git's post\-receive hook. \fBgit annex init\fP ++automatically creates a post\-receive hook using this. ++.PP ++When a repository is configured with receive.denyCurrentBranch=updateInstead, ++pushes to the repository update its work tree. However, that does not work ++for repositories that have an adjusted branch checked ++out. The hook updates the work tree when run in such a repository, ++the same as running \fBgit-annex merge\fP would. ++.PP ++When a repository is configured to proxy to a special remote with ++exporttree=yes, and the configured remote.name.annex\-tracking\-branch ++is received, the hook handles updating the tree exported to the ++special remote. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-adjust(1) ++.PP ++git-annex\-merge(1) ++.PP ++git-annex\-export(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-pre-commit.1 +@@ -0,0 +1,28 @@ ++.TH git-annex-pre-commit 1 ++.SH NAME ++git-annex-pre\-commit \- run by git pre\-commit hook ++.PP ++.SH SYNOPSIS ++git annex pre\-commit \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++This is meant to be called from git's pre\-commit hook. \fBgit annex init\fP ++automatically creates a pre\-commit hook using this. ++.PP ++Fixes up symlinks that are staged as part of a commit, to ensure they ++point to annexed content. ++.PP ++When in a view, updates metadata to reflect changes ++made to files in the view. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-preferred-content.1 +@@ -0,0 +1,411 @@ ++.TH git-annex-preferred-content 1 ++.SH NAME ++git-annex\-preferred\-content \- which files are wanted in a repository ++.PP ++.SH DESCRIPTION ++Each repository has a preferred content setting, which specifies content ++that the repository wants to have present. These settings can be configured ++using \fBgit annex vicfg\fP or \fBgit annex wanted\fP. ++They are used by the \fB\-\-auto\fP option, by \fBgit annex sync \-\-content\fP, ++by clusters, and by the git-annex assistant. ++.PP ++While preferred content expresses a preference, it can be overridden ++by simply using \fBgit annex drop\fP. On the other hand, required content ++settings are enforced; \fBgit annex drop\fP will refuse to drop a file if ++doing so would violate its required content settings. A repository's ++required content can be configured using \fBgit annex vicfg\fP or ++\fBgit annex required\fP. ++.PP ++.SH SYNTAX ++Preferred content expressions use a similar syntax to ++the git-annex\-matching\-options(1), without the dashes. ++For example: ++.PP ++ exclude=archive/* and (include=*.mp3 or smallerthan=1mb) ++.PP ++The idea is that you write an expression that files are matched against. If ++a file matches, the repository wants to store its content. If it doesn't, ++the repository wants to drop its content (if there are enough copies ++elsewhere to allow removing it). ++.PP ++An empty preferred content expression is treated the same as preferred ++content not being configured. ++.PP ++.SH EXPRESSIONS ++.IP "\fBinclude=glob\fP / \fBexclude=glob\fP" ++.IP ++Match files to include, or exclude. ++.IP ++While the command\-line options \-\-include=glob and \-\-exclude=glob match ++files relative to the current directory, preferred content expressions ++match files relative to the top of the git repository. ++.IP ++A glob is something like \fBfoo.*\fP or \fBb?r\fP. ++Globs can also contain character classes, ++like \fBfoo[Bb]ar\fP, as well as additional POSIX character classes like ++\fB[[:space:]]\fP. Which is useful, since a glob in a preferred content ++expression cannot contain spaces. See the \fBglob(7)\fP man page for more ++about globs. ++.IP ++For example, suppose you put files into \fBarchive\fP directories ++when you're done with them. Then you could configure your laptop to prefer ++to not retain those files, like this: \fBexclude=*/archive/*\fP ++.IP ++When a subdirectory is being exported or imported to a special remote (see ++git-annex\-export(1)) and git-annex\-import(1), these match relative ++to the top of the subdirectory. ++.IP ++Note that, when a command is run with the \fB\-\-all\fP option, or in a bare ++repository, there is no filename associated with an annexed object, ++and so "include=" and "exclude=" will not match. ++.IP ++.IP "\fBcopies=number\fP" ++Matches only files that git-annex believes to have the specified number ++of copies, or more. Note that it does not check remotes to verify that ++the copies still exist. ++.IP ++To decide if content should be dropped, git-annex evaluates the preferred ++content expression under the assumption that the content has *already* been ++dropped. If the content would not be wanted then, the drop can be done. ++So, for example, \fBcopies=2\fP in a preferred content expression lets ++content be dropped only when there are currently 3 copies of it, including ++the repo it's being dropped from. This is different than running git annex ++drop \-\-copies=2, which will drop files that currently have 2 copies. ++.IP ++.IP "\fBcopies=trustlevel:number\fP" ++Matches only files that git-annex believes have the specified number ++copies, on remotes with the specified trust level. For example, ++\fBcopies=trusted:2\fP ++.IP ++To match any trust level at or higher than a given level, ++use \fBtrustlevel+\fP. For example, \fBcopies=semitrusted+:2\fP ++.IP ++.IP "\fBcopies=groupname:number\fP" ++Matches only files that git-annex believes have the specified number of ++copies, on remotes in the specified group. For example, ++\fBcopies=archive:2\fP ++.IP ++Preferred content expressions have no equivalent to the \fB\-\-in\fP ++option, but groups can accomplish similar things. You can add ++repositories to groups, and match against the groups in a ++preferred content expression. So rather than \fB\-\-in=usbdrive\fP, ++put all the USB drives into a "transfer" group, and use ++\fBcopies=transfer:1\fP ++.IP ++.IP "\fBlackingcopies=number\fP" ++Matches only files that git-annex believes need the specified number or ++more additional copies to be made in order to satisfy their numcopies ++settings. ++.IP ++.IP "\fBapproxlackingcopies=number\fP" ++Like lackingcopies, but does not look at .gitattributes annex.numcopies ++settings. This makes it significantly faster. ++.IP ++.IP "\fBinbackend=backendname\fP" ++Matches only files whose content is stored using the specified key\-value ++backend. ++.IP ++See git-annex\-backends(1) for information about available backends. ++.IP ++.IP "\fBsecurehash\fP" ++Matches only files whose content is hashed using a cryptographically ++secure function. ++.IP ++.IP "\fBinallgroup=groupname\fP" ++Matches only files that git-annex believes are present in all repositories ++in the specified group. ++.IP ++.IP "\fBonlyingroup=groupname\fP" ++Matches files that git-annex believes are present in at least one ++repository that is in the specified group, and are not present in any ++repositories that are not in the specified group. ++.IP ++.IP "\fBsmallerthan=size\fP / \fBlargerthan=size\fP" ++Matches only files whose content is smaller than, or larger than the ++specified size. ++.IP ++The size can be specified with any commonly used units, for example, ++"0.5 gb" or "100 KiloBytes" ++.IP ++.IP "\fBmetadata=field=glob\fP" ++Matches only files that have a metadata field attached with a value that ++matches the glob. The values of metadata fields are matched case ++insensitively. ++.IP ++A glob is something like \fBfoo.*\fP or \fBb?r\fP. ++Globs can also contain character classes, ++like \fBfoo[Bb]ar\fP, as well as additional POSIX character classes like ++\fB[[:space:]]\fP. Which is useful, since a glob in a preferred content ++expression cannot contain spaces. See the \fBglob(7)\fP man page for more ++about globs. ++.IP ++To match a tag "done", use \fBmetadata=tag=done\fP ++.IP ++To match author metadata, use \fBmetadata=author=*Smith\fP ++.IP ++.IP "\fBmetadata=fieldnumber\fP " ++.IP "\fBmetadata=field<=number\fP / \fBmetadata=field>=number\fP" ++Matches only files that have a metadata field attached with a value that ++is a number and is less than or greater than the specified number. ++.IP ++To match PDFs with between 100 and 200 pages (assuming something has set ++that metadata), use \fBmetadata=pagecount>=100 and metadata=pagecount<=200\fP ++.IP ++.IP "\fBpresent\fP" ++Makes content be wanted if it's present, but not otherwise. ++.IP ++This leaves it up to you to use git-annex manually ++to move content around. You can use this to avoid preferred content ++settings from affecting a subdirectory. For example: ++\fBauto/* or (include=ad\-hoc/* and present)\fP ++.IP ++Note that \fBnot present\fP is not a reasonable thing to put in a preferred ++content expression. It says to get content that's not present, but then ++drop it! If that somehow gets into a preferred content expression, ++git-annex will recognize that the preferred content expression is not stable, ++and make it never match. ++.IP ++.IP "\fBinpreferreddir\fP" ++Makes content be preferred if it's in a directory (located anywhere ++in the tree) with a particular name. ++.IP ++The name of the directory can be configured using ++\fBgit annex enableremote $remote preferreddir=$dirname\fP ++.IP ++(If no directory name is configured, it uses "public" by default.) ++.IP ++Note that, when a command is run with the \fB\-\-all\fP option, or in a bare ++repository, there is no filename associated with an annexed object, ++and so "inpreferreddir" will not match. ++.IP ++.IP "\fBstandard\fP" ++git-annex comes with some built\-in preferred content expressions, that ++can be used with repositories that are in some standard groups ++such as "client" and "transfer". ++.IP ++When a repository is in exactly one such group, you can use the "standard" ++keyword in its preferred content expression, to match whatever content ++the group's expression matches. ++.IP ++Most often, the whole preferred content expression is simply "standard". ++But, you can do more complicated things, for example: ++\fBstandard or include=otherdir/*\fP ++.IP ++.IP "\fBgroupwanted\fP" ++The "groupwanted" keyword can be used to refer to a preferred content ++expression that is associated with a group, as long as there is exactly ++one such expression amoung the groups a repository is in. This is like ++the "standard" keyword, but you can configure the preferred content ++expressions using \fBgit annex groupwanted\fP. ++.IP ++When writing a groupwanted preferred content expression, ++you can use all the keywords documented here, including "standard". ++(But not "groupwanted".) ++.IP ++For example, to make a variant of the standard client preferred content ++expression that does not want files in the "out" directory, you ++could run: \fBgit annex groupwanted client "standard and exclude=out/*"\fP ++.IP ++Then repositories that are in the client group and have their preferred ++content expression set to "groupwanted" will use that, while ++other client repositories that have their preferred content expression ++set to "standard" will use the standard expression. ++.IP ++Or, you could make a new group, with your own custom preferred content ++expression tuned for your needs, and every repository you put in this ++group and make its preferred content be "groupwanted" will use it. ++.IP ++For example, the archive group only wants to archive 1 copy of each file, ++spread among every repository in the group. ++Here's how to configure a group named redundantarchive, that instead ++wants to contain 3 copies of each file: ++.IP ++ git annex groupwanted redundantarchive "not (copies=redundantarchive:3)" ++ for repo in foo bar baz; do ++ git annex group $repo redundantarchive ++ git annex wanted $repo groupwanted ++ done ++.IP ++.IP "\fBunused\fP" ++Matches only keys that \fBgit annex unused\fP has determined to be unused. ++.IP ++This is related the the \-\-unused option. ++However, putting \fBunused\fP in a preferred content expression ++doesn't make git-annex consider those unused keys. So when git-annex is ++only checking preferred content expressions against files in the ++repository (which are obviously used), \fBunused\fP in a preferred ++content expression won't match anything. ++.IP ++So when is \fBunused\fP useful in a preferred content expression? ++.IP ++Using \fBgit annex sync \-\-content \-\-all\fP will operate on all files, ++including unused ones, and take \fBunused\fP in preferred content expressions ++into account. ++.IP ++The git-annex assistant periodically scans for unused files, and ++moves them to some repository whose preferred content expression ++says it wants them. (Or, if annex.expireunused is set, it may just delete ++them.) ++.IP ++.IP "\fBbalanced=groupname[:number]\fP" ++Makes content be evenly balanced amoung repositories in the group. ++.IP ++The number is the number of repositories in the group that will ++want each file. When not specified, the default is 1. ++.IP ++For example, "balanced=backup:2", when there are 3 members of the backup ++group, will make each backup repository want 2/3rds of the files. ++.IP ++For this to work, each repository in the group should have its preferred ++content set to the same expression. Using \fBgroupwanted\fP is a good ++way to do that. ++.IP ++The sizes of files are not taken into account, so it's possible for ++one repository to get larger than usual files and so fill up before ++the other repositories. But files are only wanted by repositories that ++have enough free space to hold them. So once a repository is full, ++the remaining repositories will have any additional files balanced ++amoung them. For git-annex to know when a repository is full, ++you must use git-annex\-maxsize(1) to specify the size of each ++repository in the group. ++.IP ++This usually avoids moving files between repositories, even ++if that means that things are not optimally balanced. Some of the ways ++that it can get out of balance include adding a new repository to the ++group, or a file getting copied into more repositories in the ++group than the specified number, or some of the repositories filling up. ++.IP ++Running git-annex commands with the \fB\-\-rebalance\fP option will make this ++expression instead behave like the \fBfullybalanced\fP expression, which will ++make repositories want to move files around as necessary in order to get ++fully balanced. ++.IP ++Using this in a preferred content expression makes git-annex need to do ++some additional work to keep track of how full repositories are. Usually ++that won't affect performance much. However, the first time git-annex ++processes this expression in a given git repository, it will need to ++calculate the sizes of all repositories, which can be slow when there are ++a lot of files. When this causes git-annex to do a lot of work, it will ++display "(calculating repository sizes)". ++.IP ++Note that \fBnot balanced\fP not a reasonable thing to use in a preferred ++content expression for the same reasons as \fBnot present\fP. ++.IP ++.IP "\fBfullybalanced=groupname[:number]\fP" ++This is like \fBbalanced\fP, but allows moving content between repositories ++in the group at any time to keep it fully balanced. ++.IP ++Normally "balanced=groupname:number" is the same as ++"(fullybalanced=groupname:number and not copies=groupname:number) or present" ++.IP ++When the \fB\-\-rebalance\fP option is used, \fBbalanced\fP is the same as ++\fBfullybalanced\fP. ++.IP ++When the specified number is greater than 1, and too many repositories ++in the group are more than 90% full (as configured by ++annex.fullybalancedthreshhold), this behaves like \fBfullysizebalanced\fP. ++.IP ++For example, \fBfullybalanced=foo:3\fP, when group foo has 5 repositories, ++two 50% full and three 99% full, will make some content move from the ++full repositories to the others. Moving content like that is expensive, ++but it allows new files to continue to be stored on the specified number ++of repositories. ++.IP ++.IP "\fBsizebalanced=groupname:number\fP" ++Distributes content amoung repositories in the group, keeping ++repositories proportionally full. ++.IP ++The number is the number of repositories in the group that will ++want each file. When not specified, the default is 1. ++.IP ++For this to work, you must use git-annex\-maxsize(1) to specify ++the size of each repository in the group. When a repository's ++maxsize has not been specified, it will not want any files. ++.IP ++For example, if one repository in the group has a maximum size of ++100 gb with 60 gb used, and another has a maximum size of 50 gb with ++25 gb used, the smaller one will want files (that fit in it), ++and the larger one won't want any files ++(that would fit in the smaller one) ++until the smaller one gets equally full. ++.IP ++Note that, once a repository contains a file, it will continue to want ++it, even if it's more full than other repositories. This is to avoid ++churn in moving files around. ++.IP ++This is more likely to get out of balance than the \fBbalanced=\fP expression ++is, because git-annex does not always have a consistent knowledge of ++how full repositories are. Consider for example if a laptop and a desktop ++are each sending a new file to the group. They will both pick whichever ++repository was least full, but that means both files go to the same ++repository, when a better solution might have been to send the smaller ++file to a different repository. When using \fBbalanced=\fP in the same ++situation, it's less likely that a repository will want both files. ++.IP ++Running git-annex commands with the \fB\-\-rebalance\fP option will make this ++expression instead behave like the \fBfullysizebalanced\fP expression, which ++will make repositories want to move files around as necessary in order to ++get fully balanced. ++.IP ++Note that \fBnot sizebalanced\fP not a reasonable thing to use in a preferred ++content expression for the same reasons as \fBnot present\fP. ++.IP ++.IP "\fBfullysizebalanced=groupname:number\fP" ++This is like \fBsizebalanced\fP, but allows moving content between repositories ++in the group at any time to keep it fully balanced. ++.IP ++Normally "sizebalanced=groupname:number" is the same as ++"(fullysizebalanced=groupname:number and not copies=groupname:number) or present" ++.IP ++When the \fB\-\-rebalance\fP option is used, \fBsizebalanced\fP is the same as ++\fBfullysizebalanced\fP. ++.IP ++.IP "\fBanything\fP" ++Always matches. ++.IP ++.IP "\fBnothing\fP" ++Never matches. (Same as "not anything") ++.IP ++.IP "\fBnot expression\fP" ++Inverts what the expression matches. For example, \fBnot include=archive/*\fP ++is the same as \fBexclude=archive/*\fP ++.IP ++.IP "\fBand\fP / \fBor\fP / \fB( expression )\fP" ++These can be used to build up more complicated expressions. ++.IP ++.SH TESTING ++To check at the command line which files are matched by a repository's ++preferred content settings, you can use the \-\-want\-get and \-\-want\-drop ++options. ++.PP ++For example, git annex find \-\-want\-get \-\-not \-\-in . will find all the files ++that git annex get \-\-auto will want to get, and git annex find \-\-want\-drop \-\-in ++\&. will find all the files that git annex drop \-\-auto will want to drop. ++.PP ++The \-\-explain option can be used to understand why a complex preferred ++content expression matches or fails to match. The expression will ++be displayed, with each term followed by "[TRUE]" or "[FALSE]" to indicate ++the value. Irrelevant terms will be ommitted from the explanation, ++for example \fB"exclude=* and copies=1"\fP will be displayed as ++\fB"exclude=*[FALSE]"\fP ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-vicfg(1) ++.PP ++git-annex\-wanted(1) ++.PP ++git-annex\-maxsize(1) ++.PP ++ ++.PP ++ ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++ ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-proxy.1 +@@ -0,0 +1,22 @@ ++.TH git-annex-proxy 1 ++.SH NAME ++git-annex-proxy \- safely bypass direct mode guard (deprecated) ++.PP ++.SH SYNOPSIS ++git annex proxy \fB\-\- git cmd [options]\fP ++.PP ++.SH DESCRIPTION ++This command was for use in a direct mode repository, and such ++repositories are automatically updated to use an adjusted unlocked branch. ++So, there's no reason to use this command any longer. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-direct(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-pull.1 +@@ -0,0 +1,139 @@ ++.TH git-annex-pull 1 ++.SH NAME ++git-annex-pull \- pull content from remotes ++.PP ++.SH SYNOPSIS ++git annex pull \fB[remote ...]\fP ++.PP ++.SH DESCRIPTION ++This command pulls content from remotes. It downloads ++both git repository content, and the content of annexed files. ++Like \fBgit pull\fP, it merges changes into the current branch. ++.PP ++You can use \fBgit pull\fP and \fBgit-annex get\fP by hand to do the same thing as ++this command, but this command handles several details, including making ++sure that the git-annex branch is fetched from the remote. ++.PP ++Some special remotes contain a tree of files that can be imported, ++and this command can be used to pull from those remotes as ++well as regular git remotes. See git-annex\-import(1) for details ++about how those special remotes work. In order for this command to import ++from a special remote, \fBremote..annex\-tracking\-branch\fP also must ++be configured, and have the same value as the currently checked out branch. ++.PP ++When git-annex\-adjust(1) has been used to check out an adjusted branch, ++this command will also pull changes from the parent branch. ++.PP ++When git-annex\-view(1) has been used to check out a view branch, ++this command will update the view branch to reflect any changes ++to the parent branch or metadata. ++.PP ++When git-annex\-migrate(1) has been used in other repositories, ++this updates the content in the local repository for those migrations as well. ++.PP ++Normally this tries to download the content of each annexed file, ++from any remote that it's pulling from that has a copy. ++To control which files it downloads, configure the preferred ++content of the local repository. It will also drop files from a ++remote that are not preferred content of the remote. ++See git-annex\-preferred\-content(1). ++.PP ++.SH OPTIONS ++.IP "\fB[remote]\fP" ++.IP ++By default this command pulls from all available remotes, except for remotes ++that have \fBremote..annex\-pull\fP (or \fBremote..annex\-sync\fP) ++set to false. ++.IP ++By specifying the names of remotes (or remote groups), you can control ++which ones to pull from. ++.IP ++.IP "\fB\-\-fast\fP" ++Only pull with the remotes with the lowest annex\-cost value configured. ++.IP ++When a list of remotes (or remote groups) is provided, it picks from ++among those, otherwise it picks from among all remotes. ++.IP ++.IP "\fB\-\-only\-annex\fP \fB\-a\fP, \fB\-\-not\-only\-annex\fP" ++Only pull the git-annex branch and annexed content from remotes, ++not other git branches. ++.IP ++The \fBannex.synconlyannex\fP configuration can be set to true to make ++this be the default behavior. To override such a setting, use ++\fB\-\-not\-only\-annex\fP. ++.IP ++When this is combined with \-\-no\-content, only the git-annex branch ++will be pulled. ++.IP ++.IP "\fB\-\-no\-content\fP, \fB\-g\fP, \fB\-\-content\fP" ++Use \fB\-\-no\-content\fP or \fB\-g\fP to avoid downloading (and dropping) ++the content of annexed files, and also prevent doing any migrations of ++content. ++.IP ++If you often use \fB\-\-no\-content\fP, you can set the \fBannex.synccontent\fP ++configuration to false to prevent downloading content by default. ++The \fB\-\-content\fP option overrides that configuration. ++.IP ++To only prevent only migrations of content, you can set the ++\fBannex.syncmigrations\fP configuration to false. ++The \fB\-\-content\fP option overrides that configuration as well. ++.IP ++.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" ++Only download (and drop) annexed files in the given path. ++.IP ++This option can be repeated multiple times with different paths. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Usually this command operates on annexed files in the current branch. ++This option makes it operate on all available versions of all annexed files ++(when preferred content settings allow). ++.IP ++Note that preferred content settings that use \fBinclude=\fP or \fBexclude=\fP ++will only match the version of files currently in the work tree, but not ++past versions of files. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel pulling with up to the specified number of jobs ++running at once. For example: \fB\-J10\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++(Note that git pulls are not done in parallel because that tends to be ++less efficient.) ++.IP ++.IP "\fB\-\-allow\-unrelated\-histories\fP, \fB\-\-no\-allow\-unrelated\-histories\fP" ++Passed on to \fBgit merge\fP, to control whether or not to merge ++histories that do not share a common ancestor. ++.IP ++.IP "\fB\-\-resolvemerge\fP, \fB\-\-no\-resolvemerge\fP" ++By default, merge conflicts are automatically handled by this command. ++When two conflicting versions of a file have been committed, both will ++be added to the tree, under different filenames. For example, file "foo" ++would be replaced with "foo.variant\-A" and "foo.variant\-B". (See ++git-annex\-resolvemerge(1) for details.) ++.IP ++Use \fB\-\-no\-resolvemerge\fP to disable this automatic merge conflict ++resolution. It can also be disabled by setting \fBannex.resolvemerge\fP ++to false. ++.IP ++.IP "\fB\-\-backend\fP" ++Specifies which key\-value backend to use when importing from a ++special remote. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-push(1) ++.PP ++git-annex\-sync(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++git-annex\-satisfy(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-push.1 +@@ -0,0 +1,135 @@ ++.TH git-annex-push 1 ++.SH NAME ++git-annex-push \- push content to remotes ++.PP ++.SH SYNOPSIS ++git annex push \fB[remote ...]\fP ++.PP ++.SH DESCRIPTION ++This command pushes content to remotes. It uploads ++both git repository content, and the content of annexed files. ++.PP ++You can use \fBgit push\fP and \fBgit-annex copy\fP by hand to do the same thing as ++this command, but this command handles several details, including making ++sure that the git-annex branch is pushed to the remote. ++.PP ++When using git-annex, often remotes are not bare repositories, because ++it's helpful to add remotes for nearby machines that you want ++to access the same annexed content. Pushing to a non\-bare remote will ++not normally update the remote's current branch with changes from the local ++repository. (Unless the remote is configured with ++receive.denyCurrentBranch=updateInstead.) ++.PP ++To make working with such non\-bare remotes easier, this command pushes not ++only local \fBmaster\fP to remote \fBmaster\fP, but also to remote \fBsynced/master\fP ++(and similar with other branches). When \fBgit-annex pull\fP (or git-annex ++sync\fB) is later run on the remote, it will merge the \fPsynced/ branches ++that were pushed to it. ++.PP ++Some special remotes allow exporting a tree of files to them ++(\fBexporttree=yes\fP), ++and this command can be used to push to those remotes as well ++as regular git remotes. See git-annex\-export(1) for details ++about how those special remotes work. In order for this command to export ++to a special remote, \fBremote..annex\-tracking\-branch\fP also must ++be configured, and have the same value as the currently checked out branch. ++.PP ++When git-annex\-adjust(1) has been used to check out an adjusted branch, ++this command will propagate changes that have been made back to the ++parent branch, without propagating the adjustments. ++.PP ++Normally this tries to upload the content of each annexed file that is ++in the working tree, to any remote that it's pushing to that does not have ++a copy. To control which files are uploaded to a remote, configure the preferred ++content of the remote. When a file is not the preferred content of a remote, ++or of the local repository, this command will try to drop the file's content. ++See git-annex\-preferred\-content(1). ++.PP ++.SH OPTIONS ++.IP "\fB[remote]\fP" ++.IP ++By default, this command pushes to all available remotes, except for remotes ++that have \fBremote..annex\-push\fP (or \fBremote..annex\-sync\fP) ++set to false or \fBremote..annex\-readonly\fP set to true. ++.IP ++By specifying the names of remotes (or remote groups), you can control which ++ones to push to. ++.IP ++.IP "\fB\-\-fast\fP" ++Only push to the remotes with the lowest annex\-cost value configured. ++.IP ++When a list of remotes (or remote groups) is provided, it picks from ++amoung those, otherwise it picks from amoung all remotes. ++.IP ++.IP "\fB\-\-only\-annex\fP \fB\-a\fP, \fB\-\-not\-only\-annex\fP" ++Only push the git-annex branch and annexed content to remotes, ++not other git branches. ++.IP ++The \fBannex.synconlyannex\fP configuration can be set to true to make ++this be the default behavior. To override such a setting, use ++\fB\-\-not\-only\-annex\fP. ++.IP ++When this is combined with \-\-no\-content, only the git-annex branch ++will be pushed. ++.IP ++.IP "\fB\-\-no\-content\fP, \fB\-g\fP, \fB\-\-content\fP" ++Use \fB\-\-no\-content\fP or \fB\-g\fP to avoid uploading (and dropping) the content ++of annexed files. ++.IP ++If you often use \fB\-\-no\-content\fP, you can set the \fBannex.synccontent\fP ++configuration to false to prevent uploading content by default. ++The \fB\-\-content\fP option overrides that configuration. ++.IP ++.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" ++Only upload (or drop) annexed files in the given path. ++.IP ++This option can be repeated multiple times with different paths. ++.IP ++Note that this option does not prevent exporting other files to an ++"exporttree=yes" remote. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Usually this command operates on annexed files in the current branch. ++This option makes it operate on all available versions of all annexed files ++(when preferred content settings allow). ++.IP ++Note that preferred content settings that use \fBinclude=\fP or \fBexclude=\fP ++will only match the version of files currently in the work tree, but not ++past versions of files. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel pushing with up to the specified number of jobs ++running at once. For example: \fB\-J10\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-cleanup\fP" ++Removes the local and remote \fBsynced/\fP branches, which were created ++and pushed by \fBgit-annex push\fP or \fBgit-annex sync\fP. This option ++prevents all other activities. ++.IP ++This can come in handy when you've pushed a change to remotes and now ++want to reset your master branch back before that change. So you ++run \fBgit reset\fP and force\-push the master branch to remotes, only ++to find that the next \fBgit annex merge\fP or \fBgit annex pull\fP brings the ++changes back. Why? Because the \fBsynced/master\fP branch is hanging ++around and still has the change in it. Cleaning up the \fBsynced/\fP branches ++prevents that problem. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-pull(1) ++.PP ++git-annex\-sync(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++git-annex\-satisfy(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-readpresentkey.1 +@@ -0,0 +1,28 @@ ++.TH git-annex-readpresentkey 1 ++.SH NAME ++git-annex-readpresentkey \- read records of where key is present ++.PP ++.SH SYNOPSIS ++git annex readpresentkey \fBkey uuid\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command reads git-annex's records about whether ++the specified key's content is present in the remote with the specified ++uuid. ++.PP ++It exits 0 if the key is recorded to be present and 1 if not. ++.PP ++Note that this does not do an active check to verify if the key ++is present. To do such a check, use git-annex\-checkpresentkey(1) ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-recompute.1 +@@ -0,0 +1,65 @@ ++.TH git-annex-recompute 1 ++.SH NAME ++git-annex-recompute \- recompute computed files ++.PP ++.SH SYNOPSIS ++git-annex recompute [path ...] ++.PP ++.SH DESCRIPTION ++This updates computed files that were added with ++git-annex\-addcomputed(1). ++.PP ++By default, this only recomputes files whose input files have changed. ++The new contents of the input files are used to re\-run the computation. ++.PP ++When the output of the computation is different, the computed file is ++updated with the new content. The updated file is staged in git. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-original\fP" ++.IP ++Re\-run the computation with the original input files content. ++.IP ++.IP "\fB\-\-remote=name\fP" ++Only recompute files that were computed by this compute remote. ++.IP ++When this option is not used, all computed files are recomputed using ++whatever compute remote was originally used to add them. (In cases where ++a file can be computed by multiple remotes, the one with the lowest ++configured cost is used.) ++.IP ++.IP "\fB\-\-unreproducible\fP, \fB\-u\fP" ++Indicate that the computation is not expected to be fully reproducible. ++It can vary, in ways that produce files that equivilant enough to ++be interchangeable, but are not necessarily identical. ++.IP ++This is the default unless the compute remote indicates that it produces ++reproducible output. ++.IP ++.IP "\fB\-\-reproducible\fP, \fB\-r\fP" ++Indicate that the computation is expected to be fully reproducible. ++.IP ++This is the default when the compute remote indicates that it produces ++reproducible output. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "matching options" ++The git-annex\-matching\-options(1) can be used to control what ++files to recompute. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-addcomputed(1) ++.PP ++git-annex\-findcomputed(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-registerurl.1 +@@ -0,0 +1,68 @@ ++.TH git-annex-registerurl 1 ++.SH NAME ++git-annex-registerurl \- registers an url for a key ++.PP ++.SH SYNOPSIS ++git annex registerurl \fB[key url]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command can be used to register urls where a ++key can be downloaded from. ++.PP ++No verification is performed of the url's contents. ++.PP ++Normally the key is a git-annex formatted key. However, to make it easier ++to use this to add urls, if the key cannot be parsed as a key, and is a ++valid url, an URL key is constructed from the url. ++.PP ++Registering an url also makes git-annex treat the key as present in the ++special remote that claims it. (Usually the web special remote.) ++.PP ++.SH OPTIONS ++.IP "\fB\-\-remote=name|uuid\fP" ++.IP ++Indicate that the url is expected to be claimed by the specified remote. ++If some other remote claims the url instead, registering it will fail. ++.IP ++Note that \fB\-\-remote=web\fP will prevent any other remote from claiming ++the url. ++.IP ++.IP "\fB\-\-batch\fP" ++In batch input mode, lines are read from stdin, and each line ++should contain a key and url, separated by a single space. ++.IP ++For backwards compatability with old git-annex before this option ++was added, when no key and url pair are specified on the command line, ++batch input is used, the same as if the \-\-batch option were ++specified. It is however recommended to use \-\-batch. ++.IP ++.IP "\fB\-z\fP" ++When in batch mode, the input is delimited by nulls instead of the usual ++newlines. ++.IP ++(Note that for this to be used, you have to explicitly enable batch mode ++with \fB\-\-batch\fP) ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-addurl(1) ++.PP ++git-annex\-unregisterurl(1) ++.PP ++git-annex\-reregisterurl(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-reinit.1 +@@ -0,0 +1,46 @@ ++.TH git-annex-reinit 1 ++.SH NAME ++git-annex-reinit \- initialize repository, reusing old UUID ++.PP ++.SH SYNOPSIS ++git annex reinit \fBuuid|description\fP ++.PP ++.SH DESCRIPTION ++Normally, initializing a repository generates a new, unique identifier ++(UUID) for that repository. Occasionally it may be useful to reuse a ++UUID \-\- for example, if a repository got deleted, and you're ++setting it back up. ++.PP ++Use this with caution; it can be confusing to have two existing ++repositories with the same UUID. ++.PP ++Make sure you run \fBgit annex fsck\fP after changing the UUID of a ++repository to make sure location tracking information is recorded ++correctly. ++.PP ++Like \fBgit annex init\fP, this attempts to enable any special remotes ++that are configured with autoenable=true. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-init(1) ++.PP ++git-annex\-fsck(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-reinject.1 +@@ -0,0 +1,88 @@ ++.TH git-annex-reinject 1 ++.SH NAME ++git-annex-reinject \- inject content of file back into annex ++.PP ++.SH SYNOPSIS ++git annex reinject \fB[src dest]\fP ++.PP ++git annex reinject \-\-known \fB[src]\fP ++.PP ++.SH DESCRIPTION ++Moves the content of the src file or files into the annex. ++Only known file contents will be reinjected. Any unknown src files will ++be left unchanged. ++.PP ++This can be useful if you have obtained the content of a file from ++elsewhere and want to put it in the local annex. For example, if a file's ++content has been lost and you have a backup, you can restore the backup and ++reinject it into your local repository. ++.PP ++There are two ways to use this command. Specifying a src file and the name ++of a dest file (located inside the repository's working tree) ++injects the src file as the content of the dest file. ++.PP ++ git annex reinject /tmp/foo.iso foo.iso ++.PP ++Or the \fB\-\-known\fP option can be used to reinject all known src files, without ++needing to specify the dest file. ++.PP ++ git annex reinject \-\-known /tmp/*.iso ++.PP ++.SH OPTIONS ++.IP "\fB\-\-known\fP" ++.IP ++With this option, each specified src file is hashed using the default ++key\-value backend (or the one specified with \fB\-\-backend\fP), and if git-annex ++has a record of the resulting key having been in the annex before, the ++content is reinjected. ++.IP ++Note that, when using a key\-value backend that includes the filename ++extension in the key, this will only work if the src files have the same ++extensions as the files with the same content that was originally added ++to git-annex. ++.IP ++Note that this will reinject old versions of files that have been ++modified or deleted from the current git branch. ++Use git-annex\-unused(1) to detect when such old and potentially ++unused files have been reinjected. ++.IP ++.IP "\fB\-\-backend\fP" ++Specify the key\-value backend to use when checking if a file is known ++with the \fB\-\-known\fP option. ++.IP ++.IP "\fB\-\-guesskeys\fP" ++With this option, each specified source file is checked to see if it ++has the name of a git-annex key, and if so it is imported as the content ++of that key. ++.IP ++This can be used to pluck git-annex objects out of \fBlost+found\fP, ++as long as the original filename has not been lost, ++and is particularly useful when using key\-value backends that don't hash ++to the content of a file. ++.IP ++When the key\-value backend does support hashing, the content of the file ++is verified before importing it. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-add(1) ++.PP ++git-annex\-unused(1) ++.PP ++git-annex\-fsck(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-rekey.1 +@@ -0,0 +1,50 @@ ++.TH git-annex-rekey 1 ++.SH NAME ++git-annex-rekey \- change keys used for files ++.PP ++.SH SYNOPSIS ++git annex rekey \fB[file key ...]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command is similar to migrate, but you specify ++both the file, and the new key to use for it. ++.PP ++Multiple pairs of file and key can be given in a single command line. ++.PP ++Note that, unlike \fBgit-annex migrate\fP, this does not copy over metadata, ++urls, and other such information from the old to the new key ++.PP ++.SH OPTIONS ++.IP "\fB\-\-force\fP" ++.IP ++Allow rekeying of even files whose content is not currently available. ++Use with caution. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which lines are read from stdin. ++Each line should contain the file, and the new key to use for that file, ++separated by a single space. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-migrate(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-remotedaemon.1 +@@ -0,0 +1,53 @@ ++.TH git-annex-remotedaemon 1 ++.SH NAME ++git-annex-remotedaemon \- persistent communication with remotes ++.PP ++.SH SYNOPSIS ++git annex remotedaemon ++.PP ++.SH DESCRIPTION ++The remotedaemon provides persistent communication with remotes. ++.PP ++Several types of remotes are supported: ++.PP ++For ssh remotes, the remotedaemon tries to maintain a connection to the ++remote git repository, and uses git-annex\-shell notifychanges to detect ++when the remote git repository has changed, and fetches changes from it. ++For this to work, the git remote must have git-annex\-shell(1) ++installed, with notifychanges support. The first version of git-annex\-shell ++that supports it is 5.20140405. ++.PP ++For tor\-annex remotes, the remotedaemon runs a tor hidden service, ++accepting connections from other nodes and serving up the contents of the ++repository. This is only done if you first run \fBgit annex enable\-tor\fP. ++Use \fBgit annex p2p\fP to configure access to tor\-annex remotes. ++.PP ++Note that when \fBremote..annex\-pull\fP is set to false, the remotedaemon ++will avoid fetching changes from that remote. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-foreground\fP" ++.IP ++Don't fork to the background, and communicate on stdin/stdout using a ++simple textual protocol. The assistant runs the remotedaemon this way. ++.IP ++Commands in the protocol include LOSTNET, which tells the remotedaemon ++that the network connection has been lost, and causes it to stop any TCP ++connctions. That can be followed by RESUME when the network connection ++comes back up. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-assistant(1) ++.PP ++git-annex\-enable\-tor(1) ++.PP ++git-annex\-p2p(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-renameremote.1 +@@ -0,0 +1,43 @@ ++.TH git-annex-renameremote 1 ++.SH NAME ++git-annex-renameremote \- changes name of a special remote ++.PP ++.SH SYNOPSIS ++git annex renameremote \fBname|uuid|desc newname\fP ++.PP ++.SH DESCRIPTION ++Changes the name that is used to enable a special remote. ++.PP ++Normally the current name is used to identify the special remote to rename, ++but its uuid or description can also be used. ++.PP ++This is especially useful when an old special remote used a name, and now you ++want to use that name for a new special remote. \fBgit annex initremote\fP ++won't let you create a remote with a conflicting name, so rename the old ++remote first. ++.PP ++ git annex renameremote phone lost\-phone ++ git annex initremote phone ... ++.PP ++This only updates the name that git-annex has stored for use ++by \fBgit annex enableremote\fP. It does not update the git config stanza ++for the special remote to use the new name, but of course you can edit ++the git config if you want to rename it there. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-initremote(1) ++.PP ++git-annex\-enableremote(1) ++.PP ++git-annex\-configremote(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-repair.1 +@@ -0,0 +1,54 @@ ++.TH git-annex-repair 1 ++.SH NAME ++git-annex-repair \- recover broken git repository ++.PP ++.SH SYNOPSIS ++git annex repair ++.PP ++.SH DESCRIPTION ++This can repair many of the problems with git repositories that \fBgit fsck\fP ++detects, but does not itself fix. It's useful if a repository has become ++badly damaged. One way this can happen is if a repository used by git-annex ++is on a removable drive that gets unplugged at the wrong time. ++.PP ++This command can actually be used inside git repositories that do not ++use git-annex at all; when used in a repository using git-annex, it ++does additional repairs of the git-annex branch. ++.PP ++It works by deleting any corrupt objects from the git repository, and ++retrieving all missing objects it can from the remotes of the repository. ++.PP ++If that is not sufficient to fully recover the repository, it can also ++reset branches back to commits before the corruption happened, delete ++branches that are no longer available due to the lost data, and remove any ++missing files from the index. It will only do this if run with the ++\fB\-\-force\fP option, since that rewrites history and throws out missing data. ++Note that the \fB\-\-force\fP option never touches tags, even if they are no ++longer usable due to missing data. ++.PP ++After running this command, you will probably want to run \fBgit fsck\fP to ++verify it fixed the repository. Note that fsck may still complain about ++objects referenced by the reflog, or the stash, if they were unable to be ++recovered. This command does not try to clean up either the reflog or the ++stash. ++.PP ++It is also a good idea to run \fBgit annex fsck \-\-fast\fP after this command, ++to make sure that the git-annex branch reflects reality. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-force\fP" ++.IP ++Enable repair actions that involve deleting data that has been ++lost due to git repository corruption. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-fsck(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-required.1 +@@ -0,0 +1,49 @@ ++.TH git-annex-required 1 ++.SH NAME ++git-annex-required \- get or set required content expression ++.PP ++.SH SYNOPSIS ++git annex required \fBrepository [expression]\fP ++.PP ++.SH DESCRIPTION ++When run with an expression, configures the content that is required ++to be held in the repository. ++.PP ++Without an expression, displays the current required content setting ++of the repository. ++.PP ++While git-annex\-wanted(1) is just a preference, this designates content ++that should really not be removed. For example a file that is \fBwanted\fP can ++be removed with \fBgit annex drop\fP, but if that file is \fBrequired\fP, it would ++need to be removed with \fBgit annex drop \-\-force\fP. ++.PP ++Also, \fBgit-annex fsck\fP will warn about required contents that are not ++present. ++.PP ++For example: ++.PP ++ git annex required here "include=*.mp3 or include=*.ogg" ++.PP ++To return a repository to the original default behavior, use an empty ++value for the expression, eg: ++.PP ++git-annex required here "" ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH NOTES ++The \fBrequired\fP command was added in git-annex 5.20150420. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-wanted(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-reregisterurl.1 +@@ -0,0 +1,55 @@ ++.TH git-annex-reregisterurl 1 ++.SH NAME ++git-annex-reregisterurl \- updates url registration information ++.PP ++.SH SYNOPSIS ++git annex reregisterurl \fB[key]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command updates information about the urls that are ++registered for a key. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-move\-from=name|uuid\fP" ++.IP ++For each key, update any urls that are currently claimed by the ++specified remote to be instead used by the web special remote. ++.IP ++This could be used eg, when a special remote was needed to provide ++authorization to get an url, but the url has now become publically ++available and so the web special remote can be used. ++.IP ++Note that, like \fBgit-annex unregisterurl\fP, using this option unregisters ++an url from a special remote, but it does not mark the content as not ++present in that special remote. However, like \fBgit-annex registerurl\fP, ++this option does mark content as being present in the web special remote. ++.IP ++.IP "\fB\-\-batch\fP" ++In batch input mode, lines are read from stdin, and each line ++should contain a key. ++.IP ++.IP "\fB\-z\fP" ++When in batch mode, the input is delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-registerurl(1) ++.PP ++git-annex\-unregisterurl(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-resolvemerge.1 +@@ -0,0 +1,65 @@ ++.TH git-annex-resolvemerge 1 ++.SH NAME ++git-annex-resolvemerge \- resolve merge conflicts ++.PP ++.SH SYNOPSIS ++git annex resolvemerge ++.PP ++.SH DESCRIPTION ++Automatically resolves a conflicted merge. This is done ++automatically when using \fBgit annex sync\fP or \fBgit annex merge\fP. ++.PP ++When two trees being merged contain conflicting versions of an annexed ++file, the merge conflict will be resolved by adding both versions to the ++tree, using variants of the filename. ++.PP ++When one tree modified the file, and the other tree deleted the file, ++the merge conflict will be resolved by adding the modified file using a ++variant of the filename, leaving the original filename deleted. ++.PP ++When the merge conflict involves a file that is annexed in one ++tree, but is not annexed in the other tree, it is ++resolved by keeping the non\-annexed file as\-is, and adding the annexed ++version using a variant of the filename. ++.PP ++Note that only merge conflicts that involve one or more annexed files ++are resolved. Merge conflicts between two files that are not annexed ++will not be automatically resolved. ++.PP ++.SH EXAMPLES ++Suppose Alice commits a change to annexed file \fBfoo\fP, and Bob commits ++a different change to the same file \fBfoo\fP. ++.PP ++Merging between them will then fail, and git will present the ++merge conflict as a file \fBfoo\fP pointing to one version of the ++git-annex symlink, with \fBgit status\fP indicating that \fBfoo\fP has an ++unresolved conflict. ++.PP ++Running \fBgit annex resolvemerge\fP in this situation will resolve the merge ++conflict, by replacing the file \fBfoo\fP with files named like ++\fBfoo.variant\-c696\fP and \fBfoo.variant\-f16a\fP. One of the files has the content ++that Alice committed, and the other has the content that Bob committed. ++.PP ++The user can then examine the two variants of the file, and either merge ++the two changes into a single file, or rename one of them back to \fBfoo\fP ++and delete the other. ++.PP ++Now suppose Alice commits a change to annexed file \fBbar\fP, while Bob commits ++a deletion of the same file \fBbar\fP. Merging will fail. Running ++\fBgit annex resolvemerge\fP in this situation will resolve the merge conflict ++by making a file with a name like \fBbar.variant\-421f\fP containing Alice's ++version. The \fBbar\fP file remains deleted. The user can later examine the ++variant of the file and either rename it back to \fBbar\fP, or decide to delete ++it too. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-restage.1 +@@ -0,0 +1,31 @@ ++.TH git-annex-restage 1 ++.SH NAME ++git-annex-restage \- restages unlocked files in the git index ++.PP ++.SH SYNOPSIS ++git annex restage ++.PP ++.SH DESCRIPTION ++Since getting or dropping an unlocked file modifies the file in the work ++tree, git needs to be told that the modification does not change the ++content that it has recorded (the annex pointer). Restaging the file ++accomplishes that. ++.PP ++You do not normally need to run this command, because usually git-annex ++is able to restage unlocked files itself. There are some situations ++where git-annex needs to restage a file, but the git index is locked, ++and so it cannot. It will then display a warning suggesting you run this ++command. ++.PP ++It's safe to run this command even after you have made a modification to an ++unlocked file. ++.PP ++.SH SEE ALSO ++git-annex(1) ++git-annex\-smudge(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-rmurl.1 +@@ -0,0 +1,45 @@ ++.TH git-annex-rmurl 1 ++.SH NAME ++git-annex-rmurl \- record file is not available at url ++.PP ++.SH SYNOPSIS ++git annex rmurl \fB[file url ..]\fP ++.PP ++.SH DESCRIPTION ++Record that the file is no longer available at the url. ++.PP ++Removing the last web url will make git-annex no longer treat content as being ++present in the web special remote. If some other special remote ++claims the url, unregistering the url will not update presence information ++for it, because the content may still be present on the remote. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-batch\fP" ++.IP ++Enables batch mode, in which lines are read from stdin. ++Each line should contain the file, and the url to remove from that file, ++separated by a single space. ++.IP ++.IP "\fB\-z\fP" ++Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-addurl(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-satisfy.1 +@@ -0,0 +1,66 @@ ++.TH git-annex-satisfy 1 ++.SH NAME ++git-annex-satisfy \- transfer and drop content as configured ++.PP ++.SH SYNOPSIS ++git annex satisfy \fB[remote ...]\fP ++.PP ++.SH DESCRIPTION ++This transfers and drops content of annexed files to work toward satisfying ++the preferred content settings of the local repository and remotes. ++.PP ++It does the same thing as \fBgit-annex sync \-\-content\fP without the pulling ++and pushing of git repositories, and without changing the trees that are ++imported to or exported from special remotes. ++.PP ++Note that it (like git-annex\-sync or git-annex\-assist) does not work ++specifically towards satisfying the git-annex\-numcopies setting, ++unless the preferred content setting of the local repository is written to ++do so by using eg \fBapproxlackingcopies=1\fP. ++.PP ++.SH OPTIONS ++.IP "\fB[remote]\fP" ++.IP ++By default this command operates on all remotes, except for remotes ++that have \fBremote..annex\-sync\fP set to false. ++.IP ++By specifying the names of remotes (or remote groups), you can control ++which ones to operate on. ++.IP ++.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" ++Operate on only files in the specified path. The default is to operate on ++all files in the working tree. ++.IP ++This option can be repeated multiple times with different paths. ++.IP ++Note that this option does not prevent exporting other files to an ++"exporttree=yes" remote. ++.IP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++Enables parallel processing with up to the specified number of jobs ++running at once. For example: \fB\-J10\fP ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Usually this command operates on annexed files in the current branch. ++This option makes it operate on all available versions of all annexed files ++(when preferred content settings allow). ++.IP ++Note that preferred content settings that use \fBinclude=\fP or \fBexclude=\fP ++will only match the version of files currently in the work tree, but not ++past versions of files. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-sync(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-schedule.1 +@@ -0,0 +1,50 @@ ++.TH git-annex-schedule 1 ++.SH NAME ++git-annex-schedule \- get or set scheduled jobs ++.PP ++.SH SYNOPSIS ++git annex schedule \fBrepository [expression]\fP ++.PP ++.SH DESCRIPTION ++The git-annex\-assistant(1) daemon can be configured to run scheduled jobs. ++This is similar to cron and anacron (and you can use them if you prefer), ++but has the advantage of being integrated into git-annex, and so being able ++to e.g., fsck a repository on a removable drive when the drive gets ++connected. ++.PP ++When run with an expression, configures scheduled jobs to run at a ++particular time. This can be used to make the assistant periodically run ++incremental fscks. ++.PP ++When run without an expression, outputs the current scheduled jobs for ++the repository. ++.PP ++.SH EXPRESSIONS ++These actions are available: "fsck self", "fsck UUID" (where UUID ++is the UUID of a remote to fsck). After the action comes the duration ++to allow the action to run, and finally the schedule of when to run it. ++.PP ++To schedule multiple jobs, separate them with "; ". ++.PP ++Some examples: ++.PP ++ fsck self 30m every day at any time ++ fsck self 1h every month at 3 AM ++ fsck self 1h on day 1 of every month at any time ++ fsck self 1h every week divisible by 2 at any time ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-assistant(1) ++.PP ++git-annex\-expire(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-semitrust.1 +@@ -0,0 +1,40 @@ ++.TH git-annex-semitrust 1 ++.SH NAME ++git-annex-semitrust \- return repository to default trust level ++.PP ++.SH SYNOPSIS ++git annex semitrust \fB[repository ...]\fP ++.PP ++.SH DESCRIPTION ++Returns a repository to the default semi trusted state. ++.PP ++Repositories can be specified using their remote name, their ++description, or their UUID. For the current repository, use "here". ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-trust(1) ++.PP ++git-annex\-untrust(1) ++.PP ++git-annex\-dead(1) ++.PP ++git-annex\-expire(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-setkey.1 +@@ -0,0 +1,29 @@ ++.TH git-annex-setkey 1 ++.SH NAME ++git-annex-setkey \- sets annexed content for a key ++.PP ++.SH SYNOPSIS ++git annex setkey key file ++.PP ++.SH DESCRIPTION ++This plumbing\-level command makes the content of the specified key ++be set to the specified file. The file is moved into the annex. ++.PP ++It's generally a better idea to use git-annex\-reinject(1) instead of ++this command. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-reinject(1) ++.PP ++git-annex\-dropkey(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-setpresentkey.1 +@@ -0,0 +1,37 @@ ++.TH git-annex-setpresentkey 1 ++.SH NAME ++git-annex-setpresentkey \- change records of where key is present ++.PP ++.SH SYNOPSIS ++git annex setpresentkey \fBkey uuid [1|0]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command changes git-annex's records about whether ++the specified key's content is present in a remote with the specified uuid. ++.PP ++Use 1 to indicate the key is present, or 0 to indicate the key is ++not present. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-batch\fP" ++.IP ++Enables batch mode, in which lines are read from stdin. ++The line format is "key uuid [1|0]" ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-shell.1 +@@ -0,0 +1,174 @@ ++.TH git-annex-shell 1 ++.SH NAME ++git-annex\-shell \- Restricted login shell for git-annex only SSH access ++.PP ++.SH SYNOPSIS ++git-annex\-shell [\-c] command [params ...] ++.PP ++.SH DESCRIPTION ++git-annex\-shell is a restricted shell, similar to git\-shell, which ++can be used as a login shell for SSH accounts. ++.PP ++Since its syntax is identical to git\-shell's, it can be used as a drop\-in ++replacement anywhere git\-shell is used. For example it can be used as a ++user's restricted login shell. ++.PP ++.SH COMMANDS ++Any command not listed below is passed through to git\-shell. ++.PP ++Note that the directory parameter should be an absolute path, otherwise ++it is assumed to be relative to the user's home directory. Also the ++first "/~/" or "/~user/" is expanded to the specified home directory. ++.PP ++.IP "configlist directory" ++This outputs a subset of the git configuration, in the same form as ++\fBgit config \-\-list\fP. This is used to get the annex.uuid of the remote ++repository. ++.IP ++When run in a repository that does not yet have an annex.uuid, one ++will be created, as long as a git-annex branch has already been pushed to ++the repository, or if the autoinit=1 flag is used to indicate ++initialization is desired. ++.IP ++.IP "p2pstdio directory uuid" ++This causes git-annex\-shell to communicate using the git-annex p2p ++protocol over stdio. ++.IP ++The uuid is the one belonging to the repository that will be ++communicating with git-annex\-shell. ++.IP ++.IP "notifychanges directory" ++This is used by \fBgit-annex remotedaemon\fP to be notified when ++refs in the remote repository are changed. ++.IP ++.IP "gcryptsetup directory gcryptid" ++Sets up a repository as a gcrypt repository. ++.IP ++.IP "inannex directory [key ...]" ++This checks if all specified keys are present in the annex, ++and exits zero if so. ++.IP ++Exits 1 if the key is certainly not present in the annex. ++Exits 100 if it's unable to tell (perhaps the key is in the process of ++being removed from the annex). ++.IP ++Used only by the gcrypt special remote. ++.IP ++.IP "recvkey directory key" ++This runs rsync in server mode to receive the content of a key, ++and stores the content in the annex. ++.IP ++Used only by the gcrypt special remote. ++.IP ++.IP "sendkey directory key" ++This runs rsync in server mode to transfer out the content of a key. ++.IP ++Used only by the gcrypt special remote. ++.IP ++.IP "dropkey directory [key ...]" ++This drops the annexed data for the specified keys. ++.IP ++Used only by the gcrypt special remote. ++.IP ++.SH OPTIONS ++.IP "\-\-uuid=UUID" ++.IP ++git-annex uses this to specify the UUID of the repository it was expecting ++git-annex\-shell to access. This is both a sanity check, and allows ++git-annex shell to proxy access to remotes, when configured ++by git-annex\-update\-proxy. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.IP "\-\- fields=val fields=val.. \-\-" ++Additional fields may be specified this way, to retain compatibility with ++past versions of git-annex\-shell (that ignore these, but would choke ++on new dashed options). ++.IP ++Currently used fields are autoinit= and remoteuuid= ++.IP ++.SH HOOK ++After content is received or dropped from the repository by git-annex\-shell, ++it runs a hook, \fB.git/hooks/annex\-content\fP (or \fBhooks/annex\-content\fP on a bare ++repository). The hook is not currently passed any information about what ++changed. ++.PP ++.SH ENVIRONMENT ++.IP "GIT_ANNEX_SHELL_READONLY" ++.IP ++If set, disallows any action that could modify the git-annex ++repository. ++.IP ++Note that this does not prevent passing commands on to git\-shell. ++For that, you also need ... ++.IP ++.IP "GIT_ANNEX_SHELL_LIMITED" ++If set, disallows running git\-shell to handle unknown commands. ++.IP ++.IP "GIT_ANNEX_SHELL_APPENDONLY" ++If set, allows data to be written to the git-annex repository, ++but does not allow data to be removed from it. ++.IP ++Note that this does not prevent passing commands on to git\-shell, ++so you will have to separately configure git to reject pushes that ++overwrite branches or are otherwise not appends. The git pre\-receive ++hook may be useful for accomplishing this. ++.IP ++It's a good idea to enable annex.securehashesonly in a repository ++that's set up this way. ++.IP ++.IP "GIT_ANNEX_SHELL_DIRECTORY" ++If set, git-annex\-shell will refuse to run commands that do not operate ++on the specified directory. ++.IP ++.SH EXAMPLES ++To make a \fB~/.ssh/authorized_keys\fP file that only allows git-annex\-shell ++to be run, and not other commands, pass the original command to the \-c ++option: ++.PP ++ command="git-annex\-shell \-c \\"$SSH_ORIGINAL_COMMAND\\"",no\-agent\-forwarding,no\-port\-forwarding,no\-X11\-forwarding ssh\-rsa AAAAB3NzaC1y[...] user@example.com ++.PP ++To further restrict git-annex\-shell to a particular repository, ++and fully lock it down to read\-only mode: ++.PP ++ command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_LIMITED=true GIT_ANNEX_SHELL_READONLY=true git-annex\-shell \-c \\"$SSH_ORIGINAL_COMMAND\\"",restrict ssh\-rsa AAAAB3NzaC1y[...] user@example.com ++.PP ++Obviously, \fBssh\-rsa AAAAB3NzaC1y[...] user@example.com\fP needs to ++replaced with your SSH key. The above also assumes \fBgit-annex\-shell\fP ++is available in your \fB$PATH\fP, use an absolute path if it is not the ++case. Also note how the above uses the \fBrestrict\fP option instead of an ++explicit list of functionality to disallow. This only works in certain ++OpenSSH releases, starting from 7.1p2. ++.PP ++To only allow adding new objects to the repository, the ++\fBGIT_ANNEX_SHELL_APPENDONLY\fP variable can be used as well: ++.PP ++command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_APPENDONLY=true git-annex\-shell \-c \\"$SSH_ORIGINAL_COMMAND\\"",restrict ssh\-rsa AAAAB3NzaC1y[...] user@example.com ++.PP ++This will not keep an attacker from destroying the git history, as ++explained above. For this you might want to disallow certain ++operations, like branch deletion and force\-push, with options from ++git\-config(1). For example: ++.PP ++git config receive.denyDeletes true ++git config receive.denyNonFastForwards true ++.PP ++With this configuration, git commits can still remove files, ++but they will still be available in the git history and git-annex will ++retain their contents. Changes to \fBgit-annex\fP branch, however, can ++negatively impact git-annex's location tracking information and might ++cause data loss. To work around this problem, more complex hooks ++are required, see for example the \fBupdate\-paranoid\fP hook in the git ++source distribution. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git\-shell(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++ ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-sim.1 +@@ -0,0 +1,374 @@ ++.TH git-annex-sim 1 ++.SH NAME ++git-annex-sim \- simulate a network of repositories ++.PP ++.SH SYNOPSIS ++git annex sim start [my.sim] ++.PP ++git annex sim command ++.PP ++git annex sim show ++.PP ++git annex sim end ++.PP ++git annex sim run my.sim ++.PP ++.SH DESCRIPTION ++This command simulates the behavior of git-annex in a network of ++repositories, determining which files would reach which repositories ++according to the configuration of preferred content, numcopies, ++trust level, etc. ++.PP ++The input to the simulation is a sim file, and/or sim commands that are ++run after starting it. These are in the form "git annex sim command" ++with the command in the same format used in the sim file (see sim commands ++list below). For example, "git annex sim step 1" runs the simulation one step. ++.PP ++The simulation keeps a log as it runs, which contains the ++entire simulation input, as well as the actions performed in the ++simulation, and the results of the simulation. Use "git-annex sim show" ++to display the log. This allows re\-running the same simulation later, ++as well as analyzing the results of the simulation. ++.PP ++Use "git annex sim end" to finish the simulation, and clean up. ++.PP ++As a convenience, to run a sim from a file, and then stop it, use ++"git-annex sim run". If there is a problem running the sim, it will be ++shown before it is stopped. ++.PP ++Note that interrupting this command while it is running may leave the ++simulation in an inconsistent state. And running multiple sim commands at ++the same time can as well, although it is safe to run "git annex sim visit" ++while running other sim commands. ++.PP ++.SH THE SIM FILE ++This text file is used to configure the simulation and also to report on ++the results of the simulation. Each line takes the form of a command ++followed by parameters to the command. Lines starting with "#" or "\-\-" ++are comments. ++.PP ++Here is an example sim file: ++.PP ++ # add repositories to the simulation and connect them as remotes ++ init foo ++ init bar ++ connect foo <\-> bar ++ ++ # add a special remote ++ initremote baz ++ connect foo \-> baz <\- bar ++ ++ # configure repositories ++ numcopies 2 ++ group foo client ++ wanted foo standard ++ group bar archive ++ wanted bar standard ++ wanted baz include=*.mp3 ++ ++ # add annexed files in the working tree to the simulation, as if they ++ # were just added to repository foo ++ addtree foo include=*.mp3 ++ addtree foo include=*.jpg ++ addtree foo include=bigfiles/ ++ ++ # add simulated annexed files ++ add bigfile 100gb bar ++ add hugefile 10tb foo ++ ++ # run the simulation forward by ten steps ++ step 10 ++ ++ # remove foo's remote bar and see if a new file added to foo reaches bar ++ disconnect foo \-> bar ++ add foo.mp3 2mb foo ++ step 5 ++.PP ++.SH SIM COMMANDS ++This is the full set of commands that can be used in the sim file as well ++as passed to "git annex sim" while a simulation is running. ++.PP ++.IP "\fBinit name\fP" ++Initialize a simulated repository, giving it a name that will be used ++in the simulation. ++.IP ++.IP "\fBinitremote name\fP" ++Initialize a simulated special remote. ++.IP ++.IP "\fBuse name here|remote|description|uuid\fP" ++Use an existing repository in the simulation, with its existing ++configuration (trust level, groups, preferred and required content, ++maxsize, and the groupwanted configuration of its groups). ++.IP ++The repository is given a name for the purposes of the simulation. ++The repository to use can be specified by remote name, uuid, etc. ++Example: "use myrepo here" ++.IP ++.IP "\fBvisit repo [command]\fP" ++Runs the specified shell command inside the simulated repository, ++and waits for it to exit. ++.IP ++When no shell command is specified, it runs an interactive shell. ++.IP ++The command is run in a git repository whosegit-annex branch contains ++the state of that simulated repository. This allows running any ++git-annex commands, such as \fBgit-annex whereis\fP to examine the ++state of the simulation. You should avoid making any changes to ++git-annex state. ++.IP ++.IP "\fBconnect repo [<\-|\->|<\->] repo [...]\fP" ++Add a connection between two or more repositories. The arrow indicates ++which direction the connection runs, and it can be bidirectional. For ++example, "connect foo \-> bar" makes bar be a remote of foo, while ++"connect foo <\-> bar" makes each be the remote of the other. A chain ++of connections can extend to many repositories, eg ++"connect foo \-> bar \-> baz \-> foo" ++.IP ++.IP "\fBdisconnect repo [<\-|\->|<\->] repo [...]\fP" ++Removes connections between repositories. ++.IP ++For example, "disconnect foo \-> bar" makes foo no longer have bar as a ++remote. ++.IP ++.IP "\fBaddtree repo expression\fP" ++Adds annexed files from the git repository to the simulation making them ++be present in the specified repository. ++.IP ++The expression is a preferred content expression ++(see git-annex\-preferred\-content(1)) specifying which annexed files ++to add. While it is possible to include all or a large number of files ++this way, note that often it's more efficient to simulate a small ++quantity of files that have the particular properties you are interested ++in. ++.IP ++When run in a subdirectory of the repository, only files in that ++subdirectory are considered for addition. ++.IP ++This can be used with the same files more than once, to make multiple ++repositories in the simulation contain the same files. ++.IP ++.IP "\fBadd filename size repo [repo ...]\fP" ++Create a simulated annexed file with the specified filename and size, ++that is present in the specified repository, or repositories. ++.IP ++The size can be specified using any usual units, eg "10mb" or ++"3.3terabytes" ++.IP ++The filename cannot contain a space. ++.IP ++This stages a file in the index, so that regular git-annex commands can ++be used to query the state of the simulated annexed file. If there is ++already an annexed file by that name, it will be overwritten with the new ++file. ++.IP ++Note that the simulation does not cover adding conflicting files to ++different repositories. The files in the simulation are the same across ++all simulated repositories. ++.IP ++.IP "addmulti N suffix minsize maxsize repo [repo ...]" ++Add multiple simulated annexed files, with random sizes in the range ++between minsize and maxsize. ++.IP ++The files are named by combining the number, which starts at 1 and goes ++up to N, with the suffix. ++.IP ++For example: ++.IP ++ addmulti 100 testfile.jpg 100kb 10mb foo ++.IP ++That adds files named "1testfile.jpg", 2testfile.jpg", etc. ++.IP ++Note that adding a large number of files to the simulation can slow it ++down and make it use a lot of memory. ++.IP ++.IP "\fBstep N\fP" ++Run the simulation forward by this many steps. ++.IP ++On each step of the simulation, one file is either transferred ++or dropped, according to the preferred content and other configuration. ++.IP ++If there are no more files that can be either transferred or dropped ++according to the current configuration, a message will be displayed ++to indicate that the simulation has stabilized. ++.IP ++This also simulates git pull and git push being run in each repository, ++as needed in order to find additional things to do. ++.IP ++.IP "\fBstepstable N\fP" ++Run the simulation forward by this many steps, at which point it is ++expected to have stabilized. ++.IP ++If the simulation does not stabilize, the command will exit with a ++nonzero exit state. ++.IP ++.IP "\fBaction repo getwanted remote\fP" ++Simulate the repository getting files it wants from the remote. ++.IP ++.IP "\fBaction repo dropunwanted\fP" ++Simulate the repository dropping files it does not want, ++when it is able to verify enough copies exist on remotes. ++.IP ++.IP "\fBaction repo dropunwantedfrom remote\fP" ++Simulate the repository dropping files from the remote that the remote ++does not want, when it is able to verify enouh copies exist. ++.IP ++.IP "\fBaction repo sendwanted remote\fP" ++Simulate the repository sending files that the remote wants to it. ++.IP ++.IP "\fBaction repo gitpush remote\fP" ++Simulate the repository pushing the git-annex branch to the remote. ++.IP ++.IP "\fBaction repo gitpull remote\fP" ++Simulate the repository pulling the git-annex branch from the remote. ++.IP ++.IP "\fBaction repo pull remote\fP" ++Simulate the equivilant of git-annex\-pull(1), by combining ++the actions gitpull, getwanted, and dropunwanted. ++.IP ++.IP "\fBaction repo push remote\fP" ++Simulate the equivilant of git-annex\-push(1) by combining ++the actions sendwanted, dropunwantedfrom, and gitpush. ++.IP ++.IP "\fBaction repo sync remote\fP" ++Simulate the equivilant of git-annex\-sync(1) by combining ++the actions gitpull, getwanted, sendwanted, dropunwanted, and gitpush. ++.IP ++.IP "\fBaction [...] while action [...]\fP" ++Simulate running the two actions concurrently. While the simulation only ++actually simulates one thing happening at a time, when the actions each ++operate on multiple files, they will be interleaved randomly. ++.IP ++Any number of actions can be combined this way. ++.IP ++For example: ++.IP ++ action foo dropunwanted while action bar getwanted foo ++.IP ++In this example, bar may or may not get a file before foo drops it. ++.IP ++.IP "\fBseed N\fP" ++Sets the random seed to a given number. Using this should make the ++results of the simulation deterministic. The output sim file ++always has the random seed included in it, so it can be used to replay ++the simulation. ++.IP ++.IP "\fBpresent repo file\fP" ++This indicates the expected state of the simulation at this point. The ++repository should contain the content of the file. If it does not, the ++discrepancy will be indicated on standard error, and the \fBgit-annex sim\fP ++command will eventually exit nonzero. ++.IP ++This is added to the output sim file as the simulation runs. ++.IP ++.IP "\fBnotpresent repo file\fP " ++This indicates the expected state of the simulation at this point. The ++repository should not contain the content of the file. If it does, the ++discrepancy will be indicated on standard error, and the \fBgit-annex sim\fP ++command will eventually exit nonzero. ++.IP ++This is added to the output sim file as the simulation runs. ++.IP ++.IP "\fBnumcopies N\fP" ++Sets the desired number of copies. This is equivilant to ++git-annex\-numcopies(1). ++.IP ++Note that other configuration that sets numcopies, such as .gitattributes ++files, is not used by the simulation. ++.IP ++.IP "\fBmincopies N\fP" ++Sets the minimum number of copies. This is equivilant to ++git-annex\-mincopies(1). ++.IP ++.IP "\fBtrustlevel repo trusted|untrusted|semitrusted|dead\fP" ++Sets the trust level of the repository. This is equivilant to ++git-annex\-trust(1), git-annex\-untrust(1), etc. ++.IP ++.IP "\fBwanted repo expression\fP" ++Configure the preferred content of a repository. This is equivilant ++to git-annex\-wanted(1). ++.IP ++.IP "\fBrequired repo expression\fP" ++Configure the required content of a repository. This is equivilant ++to git-annex\-required(1). ++.IP ++.IP "\fBgroupwanted group expression\fP" ++Configure the groupwanted expression. This is equivilant to ++git-annex\-groupwanted(1). ++.IP ++.IP "\fBrandomwanted repo term...\fP" ++Configure the preferred content of a repository to a random expression ++generated by combining a random selection of the provided terms with ++"and", "or", and "not". ++.IP ++For example, "randomwanted foo exclude=*.x include=*.x largerthan=100kb" ++might generate an expression of "exclude=*.x or not largerthan=100kb and include=*.x" ++or it might generate an expression of "include=*.x and exclude=*.x" ++.IP ++.IP "\fBrandomrequired repo term...\fP" ++Configure the required content of a repository to a random expression. ++.IP ++.IP "\fBrandomgroupwanted group term...\fP" ++Configure the groupwanted to a random expression. ++.IP ++.IP "\fBgroup repo group\fP" ++Add a repository to a group. This is equivilant to ++git-annex\-group(1). ++.IP ++.IP "\fBungroup repo group\fP" ++Remove a repository from a group. This is equivilant to ++git-annex\-ungroup(1). ++.IP ++.IP "\fBmetadata filename expression\fP" ++Change the metadata of the simulated file. The expression is ++in the same format as the \-\-set option of the git-annex\-metadata ++command. For example: \fBmetadata foo year=2025\fP ++.IP ++.IP "\fBmaxsize repo size\fP" ++Configure the maximum size of a repository. This is equivilant to ++git-annex\-maxsize(1). ++.IP ++.IP "\fBrebalance [on|off]\fP" ++Setting "rebalance on" is the equivilant of passing the \-\-rebalance ++option to git-annex. Setting "rebalance off" undoes that. ++.IP ++For example: ++.IP ++ maxsize foo 1tb ++ rebalance on ++ step 100 ++ rebalance off ++.IP ++.IP "\fBclusternode name repo\fP" ++Simulate a repository being a node of a cluster, which can be referred to ++using the specified name. ++.IP ++Rather than a cluster gateway being simulated as a separate entity, any ++connection to a cluster node with that name is treated as accessing that ++repository via the same cluster gateway. ++.IP ++Since a cluster gateway knows about all changes that are made to nodes ++via it, every repository that has a connection to a cluster node will ++immediately know about changes that are made via that node, without ++needing a simulated git pull. ++.IP ++To simulate a repository being a node of more than one cluster, or behind ++multiple gateways in the same cluster, use this command to give it ++multiple names. ++.IP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH EXAMPLES ++git-annex includes a collection of sim files, ++at ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-test(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-smudge.1 +@@ -0,0 +1,62 @@ ++.TH git-annex-smudge 1 ++.SH NAME ++git-annex-smudge \- git filter driver for git-annex ++.PP ++.SH SYNOPSIS ++git annex smudge [\-\-clean] file ++.PP ++git annex smudge \-\-update ++.PP ++.SH DESCRIPTION ++This command lets git-annex be used as a git filter driver which lets ++annexed files in the git repository to be unlocked, instead ++of being symlinks, and lets \fBgit add\fP store files in the annex. ++.PP ++When adding a file with \fBgit add\fP, the annex.largefiles config is ++consulted to decide if a given file should be added to git as\-is, ++or if its content are large enough to need to use git-annex. ++The annex.gitaddtoannex setting overrides that; setting it to false ++prevents \fBgit add\fP from adding files to the annex. ++.PP ++However, if git-annex can tell that a file was annexed before, ++it will still be added to the annex even when those configs would normally ++prevent it. Two examples of this are adding a modified version of an ++annexed file, and moving an annexed file to a new filename and adding that. ++.PP ++The git configuration to use this command as a filter driver is as follows. ++This is normally set up for you by git-annex init, so you should ++not need to configure it manually. ++.PP ++ [filter "annex"] ++ smudge = git-annex smudge %f ++ clean = git-annex smudge \-\-clean %f ++.PP ++To make git use that filter driver, it needs to be configured in ++the \fB.gitattributes\fP file or in \fB.git/info/attributes\fP. The latter ++is normally configured when a repository is initialized, with the following ++contents: ++.PP ++ * filter=annex ++.PP ++The smudge filter does not provide git with the content of annexed files, ++because that would be slow and triggers memory leaks in git. Instead, ++it records which worktree files need to be updated, and ++\fBgit annex smudge \-\-update\fP later updates the work tree to contain ++the content. That is run by several git hooks, including post\-checkout ++and post\-merge. However, a few git commands, notably \fBgit stash\fP and ++\fBgit cherry\-pick\fP, do not run any hooks, so after using those commands ++you can manually run \fBgit annex smudge \-\-update\fP to update the working ++tree. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++git-annex\-filter\-process(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-status.1 +@@ -0,0 +1,39 @@ ++.TH git-annex-status 1 ++.SH NAME ++git-annex-status \- show the working tree status (deprecated) ++.PP ++.SH SYNOPSIS ++git annex status \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Similar to \fBgit status \-\-short\fP, this command displays the status of the files ++in the working tree. ++.PP ++Show files that are not checked into git (?), deleted (D), ++modified (M), added but not committed (A), and type changed/unlocked (T). ++.PP ++.SH OPTIONS ++.IP "\fB\-\-ignore\-submodules=when\fP" ++.IP ++This option is passed on to git status, see its man page for ++details. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git\-status(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-sync.1 +@@ -0,0 +1,82 @@ ++.TH git-annex-sync 1 ++.SH NAME ++git-annex-sync \- synchronize local repository with remotes ++.PP ++.SH SYNOPSIS ++git annex sync \fB[remote ...]\fP ++.PP ++.SH DESCRIPTION ++This command synchronizes the local repository with its remotes. ++.PP ++This command first commits any local changes to files that have ++previously been added to the repository. Then it does the equivilant of ++git-annex\-pull(1) followed by git-annex\-push(1). ++.PP ++However, unlike those commands, this command does not transfer annexed ++content by default. That will change in a future version of git-annex, ++when syncing with repositories that have preferred content configured. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-content\fP, \fB\-\-no\-content\fP, \fB\-g\fP" ++.IP ++The \-\-content option causes the content of annexed files ++to also be pulled and pushed. ++.IP ++The \-\-no\-content and \-g options cause the content of annexed files to ++not be pulled and pushed. ++.IP ++The \fBannex.synccontent\fP configuration can be set to true to make ++\fB\-\-content\fP be enabled by default. ++.IP ++.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" ++This option causes the content of annexed files in the given ++path to also be pulled and pushed. ++.IP ++This option can be repeated multiple times with different paths. ++.IP ++Note that this option does not prevent exporting other files to an ++"exporttree=yes" remote. ++.IP ++.IP "\fB\-\-commit\fP, \fB\-\-no\-commit\fP" ++A commit is done by default (unless \fBannex.autocommit\fP is set to false). ++.IP ++Use \-\-no\-commit to avoid committing local changes. ++.IP ++.IP "\fB\-\-message=msg\fP \fB\-m msg\fP" ++Use this option to specify a commit message. ++.IP ++If multiple \-m options are given, their values are concatenated ++as separate paragraphs. ++.IP ++.IP "\fB\-\-pull\fP, \fB\-\-no\-pull\fP" ++Use this option to disable pulling. ++.IP ++When \fBremote..annex\-sync\fP is set to false, pulling is disabled ++for that remote, and using \fB\-\-pull\fP will not enable it. ++.IP ++.IP "\fB\-\-push\fP, \fB\-\-no\-push\fP " ++Use this option to disable pushing. ++.IP ++When \fBremote..annex\-sync\fP is set to false, pushing is disabled for ++that remote, and using \fB\-\-push\fP will not enable it. ++.IP ++.IP "Also all options supported by git-annex\-pull(1) and" ++git-annex\-push(1) can be used. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-pull(1) ++.PP ++git-annex\-push(1) ++.PP ++git-annex\-assist(1) ++.PP ++git-annex\-satisfy(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-test.1 +@@ -0,0 +1,63 @@ ++.TH git-annex-test 1 ++.SH NAME ++git-annex-test \- run built\-in test suite ++.PP ++.SH SYNOPSIS ++git annex test ++.PP ++.SH DESCRIPTION ++This runs git-annex's built\-in test suite. ++.PP ++The test suite runs in the \fB.t\fP subdirectory of the current directory. ++.PP ++It can be useful to run the test suite on different filesystems, ++or to verify your local installation of git-annex. ++.PP ++.SH OPTIONS ++There are several options, provided by Haskell's tasty test ++framework. Pass \-\-help for details about those. ++.PP ++.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" ++How many tests to run in parallel. The default is "cpus", which will ++runs one job per CPU core. ++.IP ++.IP "\fB\-\-keep\-failures\fP" ++When there are test failures, leave the \fB.t\fP directory populated with ++repositories that demonstate the failures, for later analysis. ++.IP ++.IP "\fB\-\-test\-git\-config name=value\fP" ++The test suite prevents git from reading any git configuration files. ++Usually it is a good idea to run the test suite with a standard ++git configuration. However, this option can be useful to see what ++effect a git configuration setting has on the test suite. ++.IP ++Some configuration settings will break the test suite, in ways that are ++due to a bug in git-annex. But it is possible that changing a ++configuration can find a legitimate bug in git-annex. ++.IP ++One valid use of this is to change a git configuration to a value that ++is planned to be the new default in a future version of git. ++.IP ++Also, some things can only be tested with a git configuration. For ++example, annex.shared\-sop\-command has to be set for the test suite to ++test using that command. ++.IP ++.IP "\fB\-\-test\-debug\fP" ++Normally output of commands run by the test suite is hidden, so even ++when annex.debug or \-\-debug is enabled, it will not be displayed. ++This option makes the full output of commands run by the test suite be ++displayed. It also makes the test suite run git-annex with \-\-debug. ++.IP ++It's a good idea to use \fB\-J1\fP in combinaton with this, otherwise ++the output of concurrent tests will be mixed together. ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-testremote(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-testremote.1 +@@ -0,0 +1,53 @@ ++.TH git-annex-testremote 1 ++.SH NAME ++git-annex-testremote \- test transfers to/from a remote ++.PP ++.SH SYNOPSIS ++git annex testremote \fBremote\fP ++.PP ++.SH DESCRIPTION ++This tests a remote by sending objects to it, downloading objects from it, ++etc. ++.PP ++It's safe to run in an existing repository (the repository contents are ++not altered), although it may perform expensive data transfers. ++.PP ++It's best to make a new remote for testing purposes. While the test ++tries to clean up after itself, if the remote being tested had a bug, ++the cleanup might fail, leaving test data in the remote. Also, ++some special remotes don't support removal of data that has been stored ++in them, so test data won't be able to be cleaned up when testing those. ++.PP ++Testing will use the remote's configuration, automatically varying ++the chunk sizes, and with simple shared encryption disabled and enabled, ++and exporttree disabled and enabled. If the remote is readonly, testing ++is limited to checking various properties of downloading from it. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-fast\fP" ++.IP ++Perform a smaller set of tests. ++.IP ++.IP "\fB\-\-test\-readonly=file\fP" ++Normally, random objects are generated for the test and are sent to the ++remote. When a readonly remote is being tested, that cannot be done, ++and so you need to specify some annexed files to use in the testing, ++using this option. Their content needs to be present in the readonly remote ++being tested, and in the local repository. ++.IP ++This option can be repeated. ++.IP ++.IP "\fB\-\-size=NUnits\fP" ++Tune the base size of generated objects. The default is 1MiB. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-test(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-transferkey.1 +@@ -0,0 +1,32 @@ ++.TH git-annex-transferkey 1 ++.SH NAME ++git-annex-transferkey \- transfers a key from or to a remote ++.PP ++.SH SYNOPSIS ++git annex transferkey \fBkey [\-\-from=remote|\-\-to=remote]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command is used to request a single key be ++transferred. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-from=remote\fP" ++.IP ++Download the content of the key from the remote. ++.IP ++.IP "\fB\-\-to=remote\fP" ++Upload the content of the key to the remote. ++.IP ++.IP "\fB\-\-file=name\fP" ++Provides a hint about the name of the file associated with the key. ++(This name is only used in progress displays.) ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-transferkeys.1 +@@ -0,0 +1,27 @@ ++.TH git-annex-transferkeys 1 ++.SH NAME ++git-annex-transferkeys \- transfers keys (deprecated) ++.PP ++.SH SYNOPSIS ++git annex transferkeys ++.PP ++.SH DESCRIPTION ++This plumbing\-level command is used to transfer data, by the assistant ++in git-annex version 8.20201127 and older. It is still included only ++to prevent breakage during upgrades. ++.PP ++It is a long\-running process, which is fed instructions about the keys ++to transfer using an internal stdio protocol, which is ++intentionally not documented (as it may change at any time). ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-transferrer.1 +@@ -0,0 +1,24 @@ ++.TH git-annex-transferrer 1 ++.SH NAME ++git-annex-transferrer \- transfers content ++.PP ++.SH SYNOPSIS ++git annex transferrer ++.PP ++.SH DESCRIPTION ++This plumbing\-level command is used to transfer data. ++It is a long\-running process, which is fed instructions about ++what to transfer using an internal stdio protocol, which is ++intentionally not documented (as it may change at any time). ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-trust.1 +@@ -0,0 +1,46 @@ ++.TH git-annex-trust 1 ++.SH NAME ++git-annex-trust \- trust a repository ++.PP ++.SH SYNOPSIS ++git annex trust \fB[repository ...]\fP ++.PP ++.SH DESCRIPTION ++Records that a repository is trusted to not unexpectedly lose ++content. Use with care. ++.PP ++Repositories can be specified using their remote name, their ++description, or their UUID. To trust the current repository, use "here". ++.PP ++Before trusting a repository, consider this scenario. Repository A ++is trusted and B is not; both contain the same content. \fBgit-annex drop\fP ++is run on repository A, which checks that B still contains the content, ++and so the drop proceeds. Then \fBgit-annex drop\fP is run on repository B, ++which trusts A to still contain the content, so the drop succeeds. Now ++the content has been lost. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-semitrust(1) ++.PP ++git-annex\-untrust(1) ++.PP ++git-annex\-dead(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-unannex.1 +@@ -0,0 +1,48 @@ ++.TH git-annex-unannex 1 ++.SH NAME ++git-annex-unannex \- undo accidental add command ++.PP ++.SH SYNOPSIS ++git annex unannex \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Use this to undo an accidental \fBgit annex add\fP command. It puts the ++file back how it was before the add. ++.PP ++Note that for safety, the content of the file remains in the annex, ++until you use \fBgit annex unused\fP and \fBgit annex dropunused\fP. ++.PP ++This is not the command you should use if you intentionally added a ++file some time ago, and don't want its contents any more. In that ++case you should use \fBgit annex drop\fP instead, and you can also ++\fBgit rm\fP the file. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-fast\fP" ++.IP ++Normally this does a slow copy of the file. In \fB\-\-fast\fP mode, it ++instead makes a hard link from the file to the content in the annex. ++But use \-\-fast mode with caution, because editing the file will ++change the content in the annex. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "file matching options" ++The git-annex\-matching\-options(1) ++can be used to specify files to unannex. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-undo.1 +@@ -0,0 +1,43 @@ ++.TH git-annex-undo 1 ++.SH NAME ++git-annex-undo \- undo last change to a file or directory ++.PP ++.SH SYNOPSIS ++git annex \fB[filename|directory] ...\fP ++.PP ++.SH DESCRIPTION ++When passed a filename, undoes the last change that was made to that ++file. ++.PP ++When passed a directory, undoes the last change that was made to the ++contents of that directory. ++.PP ++Running undo a second time will undo the undo, returning the working ++tree to the same state it had before. To support undoing an undo of ++staged changes, any staged changes are first committed by the ++undo command. ++.PP ++Note that this does not undo get/drop of a file's content; it only ++operates on the file tree committed to git. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "The git-annex\-common\-options(1) can also be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-add(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-ungroup.1 +@@ -0,0 +1,23 @@ ++.TH git-annex-ungroup 1 ++.SH NAME ++git-annex-ungroup \- remove a repository from a group ++.PP ++.SH SYNOPSIS ++git annex ungroup \fBrepository groupname\fP ++.PP ++.SH DESCRIPTION ++Removes a repository from a group. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-group(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-uninit.1 +@@ -0,0 +1,35 @@ ++.TH git-annex-uninit 1 ++.SH NAME ++git-annex-uninit \- de\-initialize git-annex and clean out repository ++.PP ++.SH SYNOPSIS ++git annex uninit ++.PP ++.SH DESCRIPTION ++Use this to stop using git annex. It will unannex every file in the ++repository, and remove all of git-annex's other data, leaving you with a ++git repository plus the previously annexed files. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-unannex(1) ++.PP ++git-annex\-init(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-unlock.1 +@@ -0,0 +1,71 @@ ++.TH git-annex-unlock 1 ++.SH NAME ++git-annex-unlock \- unlock files for modification ++.PP ++.SH SYNOPSIS ++git annex unlock \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Normally, the content of annexed files is protected from being changed. ++Unlocking an annexed file allows it to be modified. When no files are ++specified, all annexed files in the current directory are unlocked. ++.PP ++Unlocking a file changes how it is stored in the git repository (from a ++symlink to a pointer file), so this command will make a change that you ++can commit. ++.PP ++The content of an unlocked file is still stored in git-annex, not git, ++and when you commit modifications to the file, the modifications will also ++be stored in git-annex, with only the pointer file stored in git. ++.PP ++If you use \fBgit add\fP to add a file to the annex, it will be added in unlocked form from ++the beginning. This allows workflows where a file starts out unlocked, is ++modified as necessary, and is locked once it reaches its final version. ++.PP ++Normally, unlocking a file requires a copy to be made of its content, so ++that its original content is preserved, while the copy can be modified. To ++use less space, annex.thin can be set to true; this makes a hard link to ++the content be made instead of a copy. (Only when supported by the file ++system.) While this can save considerable disk space, any modification made ++to a file will cause the old version of the file to be lost from the local ++repository. So, enable annex.thin with care. ++.PP ++.SH EXAMPLES ++ # git annex unlock disk\-image ++ # git commit \-m "unlocked to allow VM to make changes as it runs" ++.PP ++ # git annex unlock photo.jpg ++ # gimp photo.jpg ++ # git annex add photo.jpg ++ # git annex lock photo.jpg ++ # git commit \-m "redeye removal" ++.PP ++.SH OPTIONS ++.IP "file matching options" ++.IP ++The git-annex\-matching\-options(1) ++can be used to specify files to unlock. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-edit(1) ++.PP ++git-annex\-add(1) ++.PP ++git-annex\-lock(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-unregisterurl.1 +@@ -0,0 +1,59 @@ ++.TH git-annex-unregisterurl 1 ++.SH NAME ++git-annex-unregisterurl \- unregisters an url for a key ++.PP ++.SH SYNOPSIS ++git annex unregisterurl \fB[key url]\fP ++.PP ++.SH DESCRIPTION ++This plumbing\-level command can be used to unregister urls when keys can ++no longer be downloaded from them. ++.PP ++Normally the key is a git-annex formatted key. However, if the key cannot be ++parsed as a key, and is a valid url, an URL key is constructed from the url. ++.PP ++Unregistering a key's last web url will make git-annex no longer treat content ++as being present in the web special remote. If some other special remote ++claims the url, unregistering the url will not update presence information ++for it, because the content may still be present on the remote. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-remote=name|uuid\fP" ++.IP ++Indicate that the url is expected to be claimed by the specified remote. ++If some other remote claims the url instead, unregistering it will fail. ++.IP ++Note that \fB\-\-remote=web\fP will prevent any other remote from claiming ++the url. ++.IP ++.IP "\fB\-\-batch\fP" ++In batch input mode, lines are read from stdin, and each line ++should contain a key and url, separated by a single space. ++.IP ++.IP "\fB\-z\fP" ++When in batch mode, the input is delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-registerurl(1) ++.PP ++git-annex\-reregisterurl(1) ++.PP ++git-annex\-rmurl(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-untrust.1 +@@ -0,0 +1,39 @@ ++.TH git-annex-untrust 1 ++.SH NAME ++git-annex-untrust \- do not trust a repository ++.PP ++.SH SYNOPSIS ++git annex untrust \fB[repository ...]\fP ++.PP ++.SH DESCRIPTION ++Records that a repository is not trusted and could lose content ++at any time. ++.PP ++Repositories can be specified using their remote name, their ++description, or their UUID. To untrust the current repository, use "here". ++.PP ++.SH OPTIONS ++.IP "\fB\-\-json\fP" ++.IP ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-trust(1) ++.PP ++git-annex\-semitrust(1) ++.PP ++git-annex\-dead(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-unused.1 +@@ -0,0 +1,100 @@ ++.TH git-annex-unused 1 ++.SH NAME ++git-annex-unused \- look for unused file content ++.PP ++.SH SYNOPSIS ++git annex unused ++.PP ++.SH DESCRIPTION ++Checks the annex for data that does not correspond to any files present ++in any tag or branch, or in the git index, and prints a numbered list ++of the data. ++.PP ++After running this command, you can use the \fB\-\-unused\fP option with many ++other git-annex commands to operate on all the unused data that was found. ++.PP ++For example, to move all unused data to origin: ++.PP ++ git annex unused; git annex move \-\-unused \-\-to origin ++.PP ++.SH OPTIONS ++.IP "\fB\-\-fast\fP" ++.IP ++Only show unused temp and bad files. ++.IP ++.IP "\fB\-\-from=repository\fP" ++Check for unused data that is located in a repository. ++.IP ++The repository should be specified using the name of a configured remote, ++or the UUID or description of a repository. ++.IP ++.IP "\fB\-\-used\-refspec=+ref:\-ref\fP" ++By default, any data that the git index uses, or that any refs in the git ++repository point to is considered to be used. If you only want to use ++some refs, you can use this option to specify the ones to use. Data that ++is not in the specified refs (and not used by the index) will then be ++considered unused. ++.IP ++See REFSPEC FORMAT below for details of the format of this setting. ++.IP ++The git configuration annex.used\-refspec can be used to configure ++this in a more permanent fashion. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH REFSPEC FORMAT ++The refspec format for \-\-used\-refspec and annex.used\-refspec is ++a colon\-separated list of additions and removals of refs. ++A somewhat contrived example: ++.PP ++ +refs/heads/*:+HEAD^:+refs/tags/*:\-refs/tags/old\-tag:reflog ++.PP ++This adds all refs/heads/ refs, as well as the previous version ++of HEAD. It also adds all tags, except for old\-tag. And it adds ++all refs from the reflog. ++.PP ++The default behavior is equivilant to \fB\-\-used\-refspec=+refs/*:+HEAD\fP ++.PP ++The refspec is processed by starting with an empty set of refs, ++and walking the list in order from left to right. ++.PP ++Each + using a glob is matched against all relevant refs ++(a subset of \fBgit show\-ref\fP) and all matching refs are added ++to the set. ++For example, "+refs/remotes/*" adds all remote refs. ++.PP ++Each + without a glob adds the literal value to the set. ++For example, "+HEAD^" adds "HEAD^". ++.PP ++Each \- is matched against the set of refs accumulated so far. ++Any refs with names that match are removed from the set. ++.PP ++"reflog" adds all the refs from the reflog. This will make past versions ++of files not be considered to be unused until the ref expires from the ++reflog (by default for 90 days). Note that this may make git-annex unused ++take some time to complete, it if needs to check every ref from the ++reflog. ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-dropunused(1) ++.PP ++git-annex\-addunused(1) ++.PP ++git-annex\-whereused(1) ++.PP ++git-annex\-oldkeys(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-updatecluster.1 +@@ -0,0 +1,38 @@ ++.TH git-annex-updatecluster 1 ++.SH NAME ++git-annex-updatecluster \- update records of cluster nodes ++.PP ++.SH SYNOPSIS ++git-annex updatecluster ++.PP ++.SH DESCRIPTION ++This command is used to record the nodes of a cluster in the git-annex ++branch, and set up proxying to the nodes. It should be run in the ++repository that will serve as a gateway to the cluster. ++.PP ++It looks at the git config \fBremote.name.annex\-cluster\-node\fP of ++each remote. When that is set to the name of a cluster that has been ++initialized with \fBgit-annex initcluster\fP, the node will be recorded in the ++git-annex branch. ++.PP ++To remove a node from a cluster, unset \fBremote.name.annex\-cluster\-node\fP ++and run this command. ++.PP ++To add additional gateways to a cluster, after running this command, ++use git-annex\-extendcluster. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++.IP "git-annex(1)" ++.IP "git-annex\-initcluster(1)" ++.IP "git-annex\-extendcluster(1)" ++.IP "git-annex\-updateproxy(1)" ++.IP "" ++.IP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-updateproxy.1 +@@ -0,0 +1,52 @@ ++.TH git-annex-updateproxy 1 ++.SH NAME ++git-annex-updateproxy \- update records with proxy configuration ++.PP ++.SH SYNOPSIS ++git annex updateproxy ++.PP ++.SH DESCRIPTION ++A git-annex repository can act as a proxy for its remotes. That allows ++annexed content to be stored and removed from the proxy's remotes, by ++repositories that do not have a direct connection to the remotes. ++.PP ++By default, no proxying is done. To configure the local repository to act ++as a proxy for its remote named "foo", run \fBgit config remote.foo.annex\-proxy\fP ++true. ++.PP ++After setting or unsetting \fBremote..annex\-proxy\fP git configurations, ++run \fBgit-annex updateproxy\fP to record the proxy configuration in the ++git-annex branch. That tells other repositories about the proxy ++configuration. ++.PP ++Suppose, for example, that remote "work" has had this command run in ++it. Then after pulling from "work", git-annex will know about an ++additional remote, "work\-foo". That remote will be accessed using "work" as ++a proxy. ++.PP ++Proxies can only be accessed via ssh or by an annex+http url. ++.PP ++To set up proxying to a special remote that is configured with ++exporttree=yes, its necessary for it to also be configured with ++annexobjects=yes. And, "remote..annex\-tracking\-branch" needs to ++be configured to the branch that will be exported to the special remote. ++When that branch is pushed to the proxy, it will update the tree exported ++to the special remote. When files are copied to the remote via the proxy, ++it will also update the exported tree. ++.PP ++Note that proxying for a special remote can temporarily use disk space ++in the repository, to temporarily hold the content of annexed files. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++.IP "git-annex(1)" ++.IP "git-annex\-updatecluster(1)" ++.IP "git-annex\-export(1)" ++.IP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-upgrade.1 +@@ -0,0 +1,53 @@ ++.TH git-annex-upgrade 1 ++.SH NAME ++git-annex-upgrade \- upgrade repository ++.PP ++.SH SYNOPSIS ++git annex upgrade ++.PP ++.SH DESCRIPTION ++Upgrades the repository to the latest version. ++.PP ++Each git-annex repository has an annex.version in its git configuration, ++that indicates the repository version. When an old repository version ++becomes deprecated, git-annex will automatically upgrade it ++(unless annex.autoupgraderepository is set to false). To manually upgrade, ++you can use this command. ++.PP ++Sometimes there's a newer repository version that is not the default yet, ++and then you can use this command to upgrade to it. ++.PP ++Currently, git-annex supports upgrades all the way back to version 0, which ++was only used by its author. It's expected that git-annex will always ++support upgrading from all past repository versions \-\- this is necessary to ++allow archives to be taken offline for years and later used. ++.PP ++.SH OPTIONS ++.IP "\-\-autoonly" ++.IP ++Only do whatever automatic upgrade can be done, don't necessarily ++upgrade to the latest version. This is used internally by git-annex. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-migrate(1) ++.PP ++Upgrades procedures and history: ++.PP ++News and release notes: ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-vadd.1 +@@ -0,0 +1,38 @@ ++.TH git-annex-vadd 1 ++.SH NAME ++git-annex-vadd \- add subdirs to current view ++.PP ++.SH SYNOPSIS ++git annex vadd \fB[field=glob ...] [field=value ...] [tag ...] [?tag ...] [field?=glob]\fP ++.PP ++.SH DESCRIPTION ++Changes the current view, adding an additional level of directories ++to categorize the files. ++.PP ++For example, when the view is by author/tag, \fBvadd year=*\fP will ++change it to year/author/tag. ++.PP ++So will \fBvadd year=2014 year=2013\fP, but limiting the years in view ++to only those two. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-metadata(1) ++.PP ++git-annex\-view(1) ++.PP ++git-annex\-vpop(1) ++.PP ++git-annex\-vfilter(1) ++.PP ++git-annex\-vcycle(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-vcycle.1 +@@ -0,0 +1,34 @@ ++.TH git-annex-vcycle 1 ++.SH NAME ++git-annex-vcycle \- switch view to next layout ++.PP ++.SH SYNOPSIS ++git annex vcycle ++.PP ++.SH DESCRIPTION ++When a view involves nested subdirectories, this cycles the order. ++.PP ++For example, when the view is by year/author/tag, \fBvcycle\fP will switch ++it to author/tag/year. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-metadata(1) ++.PP ++git-annex\-view(1) ++.PP ++git-annex\-vpop(1) ++.PP ++git-annex\-vadd(1) ++.PP ++git-annex\-vfilter(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-version.1 +@@ -0,0 +1,33 @@ ++.TH git-annex-version 1 ++.SH NAME ++git-annex-version \- show version info ++.PP ++.SH SYNOPSIS ++git annex version ++.PP ++.SH DESCRIPTION ++Shows the version of git-annex, as well as repository version information. ++.PP ++git-annex's version is in the form MAJOR.DATE, where MAJOR is a number ++like 5, which corresponds to the current repository version, and DATE ++is the date of the last release, like 20150320. ++.PP ++Daily builds of git-annex will append a "\-gREF" to the version, which ++corresponds to the git ref from git-annex's source repository that was ++built. Therefore, "5.20150320\-gdd35cf3" is a daily build, and ++"5.20150401" is an April 1st release made a bit later. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-raw\fP" ++.IP ++Causes only git-annex's version to be output, and nothing else. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-vfilter.1 +@@ -0,0 +1,32 @@ ++.TH git-annex-vfilter 1 ++.SH NAME ++git-annex-vfilter \- filter current view ++.PP ++.SH SYNOPSIS ++git annex vfilter \fB[tag ...] [field=value ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]\fP ++.PP ++.SH DESCRIPTION ++Filters the current view to only the files that have the ++specified field values and tags. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-metadata(1) ++.PP ++git-annex\-view(1) ++.PP ++git-annex\-vpop(1) ++.PP ++git-annex\-vadd(1) ++.PP ++git-annex\-vcycle(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-vicfg.1 +@@ -0,0 +1,28 @@ ++.TH git-annex-vicfg 1 ++.SH NAME ++git-annex-vicfg \- edit configuration in git-annex branch ++.PP ++.SH SYNOPSIS ++git annex vicfg ++.PP ++.SH DESCRIPTION ++Opens EDITOR on a temp file containing all of git-annex's ++configuration settings that are stored in the git-annex branch, ++and when it exits, stores any changes made back to the git-annex branch. ++.PP ++Unlike git config settings, these configuration settings can be seen ++by all clones of the repository. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git\-config(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-view.1 +@@ -0,0 +1,73 @@ ++.TH git-annex-view 1 ++.SH NAME ++git-annex-view \- enter a view branch ++.PP ++.SH SYNOPSIS ++git annex view \fB[tag ...] [field=value ...] [field=glob ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]\fP ++.PP ++.SH DESCRIPTION ++Uses metadata to build a view branch of the files in the current branch, ++and checks out the view branch. Only files in the current branch whose ++metadata matches all the specified field values and tags will be ++shown in the view. ++.PP ++Multiple values for a metadata field can be specified, either by using ++a glob (\fBfield="*"\fP) or by listing each wanted value. The resulting view ++will put files in subdirectories according to the value of their fields. ++.PP ++Once within such a view, you can make additional directories, and ++copy or move files into them. When you commit, the metadata will ++be updated to correspond to your changes. Deleting files and committing ++also updates the metadata. ++.PP ++As well as the usual metadata, there are fields available corresponding ++to the path to the file. So a file "foo/bar/baz/file" has fields "/=foo", ++"foo/=bar", and "foo/bar/=baz". These location fields can be used the ++same as other metadata to construct the view. ++.PP ++For example, \fB/=foo\fP will only include files from the foo ++directory in the view, while \fBfoo/=*\fP will preserve the ++subdirectories of the foo directory in the view. ++.PP ++To enter a view containing only files that lack a given metadata ++value or tag, specify field!=value or !tag. (Globs cannot be used here.) ++.PP ++\fBfield?=*\fP is like \fBfield=*\fP but adds an additional directory named \fB_\fP (by ++default) that contains files that do not have the field set to any value. ++Similarly, \fB?tag\fP adds an additional directory named \fB_\fP that contains ++files that do not have any tags set. Moving files from the \fB_\fP directory to ++another directory and committing will set the metadata. And moving files ++into the \fB_\fP directory and committing will unset the metadata. ++.PP ++The name of the \fB_\fP directory can be changed using the annex.viewunsetdirectory ++git config. ++.PP ++Filenames in the view branch include their path within the original branch, to ++ensure that they are unique. The path comes after the main filename, and ++before any extensions. For example, "foo/bar.baz" will have a name ++like "bar_%foo%.baz". annex.maxextensionlength can be used to configure ++what is treated as an extension. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-metadata(1) ++.PP ++git-annex\-vpop(1) ++.PP ++git-annex\-vfilter(1) ++.PP ++git-annex\-vadd(1) ++.PP ++git-annex\-vcycle(1) ++.PP ++git-annex\-adjust(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-vpop.1 +@@ -0,0 +1,34 @@ ++.TH git-annex-vpop 1 ++.SH NAME ++git-annex-vpop \- switch back to previous view ++.PP ++.SH SYNOPSIS ++git annex vpop \fB[N]\fP ++.PP ++.SH DESCRIPTION ++Switches from the currently active view back to the previous view. ++Or, from the first view back to original branch. ++.PP ++The optional number tells how many views to pop. ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-metadata(1) ++.PP ++git-annex\-view(1) ++.PP ++git-annex\-vfilter(1) ++.PP ++git-annex\-vadd(1) ++.PP ++git-annex\-vcycle(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-wanted.1 +@@ -0,0 +1,40 @@ ++.TH git-annex-wanted 1 ++.SH NAME ++git-annex-wanted \- get or set preferred content expression ++.PP ++.SH SYNOPSIS ++git annex wanted \fBrepository [expression]\fP ++.PP ++.SH DESCRIPTION ++When run with an expression, configures the content that is preferred ++to be held in the repository. See git-annex\-preferred\-content(1) ++.PP ++For example: ++.PP ++ git annex wanted here "include=*.mp3 or include=*.ogg" ++.PP ++Without an expression, displays the current preferred content setting ++of the repository. ++.PP ++To return a repository to the original default behavior, use an empty ++value for the expression, eg: ++.PP ++git-annex wanted here "" ++.PP ++.SH OPTIONS ++.IP "The git-annex\-common\-options(1) can be used." ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-required(1) ++.PP ++git-annex\-preferred\-content(1) ++.PP ++git-annex\-groupwanted(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-watch.1 +@@ -0,0 +1,41 @@ ++.TH git-annex-watch 1 ++.SH NAME ++git-annex-watch \- daemon to watch for changes ++.PP ++.SH SYNOPSIS ++git annex watch ++.PP ++.SH DESCRIPTION ++Watches for changes to files in the current directory and its subdirectories, ++and takes care of automatically adding new files, as well as dealing with ++deleted, copied, and moved files. With this running as a daemon in the ++background, you no longer need to manually run git commands when ++manipulating your files. ++.PP ++By default, all new files in the directory will be added to the repository. ++(Including dotfiles.) To block some files from being added, use ++\fB.gitignore\fP files. ++.PP ++By default, all files that are added are added to the annex, the same ++as when you run \fBgit annex add\fP. If you configure annex.largefiles, ++files that it does not match will instead be added with \fBgit add\fP. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-foreground\fP" ++.IP ++Avoid forking to the background. ++.IP ++.IP "\fB\-\-stop\fP" ++Stop a running daemon in the current repository. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-assistant(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-webapp.1 +@@ -0,0 +1,53 @@ ++.TH git-annex-webapp 1 ++.SH NAME ++git-annex-webapp \- launch webapp ++.PP ++.SH SYNOPSIS ++git annex webapp ++.PP ++.SH DESCRIPTION ++Opens a web app, that allows easy setup of a git-annex repository, ++and control of the git-annex assistant. If the assistant is not ++already running, it will be started. This will cause new files to ++be added and syncing operations to be performed. ++.PP ++By default, the webapp can only be accessed from localhost, and running ++it opens a browser window. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-listen=address\fP" ++.IP ++Useful for using the webapp on a remote computer. This makes the webapp ++listen on the specified IP address. (Or on the address that a specified ++hostname resolves to.) ++.IP ++This disables running a local web browser, and outputs the url you ++can use to open the webapp. ++.IP ++Set annex.listen in the git config to make the webapp always ++listen on an IP address. ++.IP ++.IP "\fB\-\-port=number\fP" ++Use this option to specify a port for the webapp. ++By default, the webapp picks an unused port. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH USING HTTPS ++When using the webapp on a remote computer, you'll almost certainly ++want to enable HTTPS. The webapp will use HTTPS if it finds ++a .git/annex/privkey.pem and .git/annex/certificate.pem. Here's ++one way to generate those files, using a self\-signed certificate: ++.PP ++ openssl genrsa \-out .git/annex/privkey.pem 4096 ++ openssl req \-new \-x509 \-key .git/annex/privkey.pem > .git/annex/certificate.pem ++.PP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-assistant(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-whereis.1 +@@ -0,0 +1,107 @@ ++.TH git-annex-whereis 1 ++.SH NAME ++git-annex-whereis \- lists repositories that have file content ++.PP ++.SH SYNOPSIS ++git annex whereis \fB[path ...]\fP ++.PP ++.SH DESCRIPTION ++Displays information about where the contents of files are located. ++.PP ++For example: ++.PP ++ # git annex whereis ++ whereis my_cool_big_file (1 copy) ++ 0c443de8\-e644\-11df\-acbf\-f7cd7ca6210d \-\- laptop ++ whereis other_file (3 copies) ++ 0c443de8\-e644\-11df\-acbf\-f7cd7ca6210d \-\- laptop ++ 62b39bbe\-4149\-11e0\-af01\-bb89245a1e61 \-\- usb drive [here] ++ 7570b02e\-15e9\-11e0\-adf0\-9f3f94cb2eaa \-\- backup drive ++.PP ++Note that this command does not contact remotes to verify if they still ++have the content of files. It only reports on the last information that was ++received from remotes. ++.PP ++.SH OPTIONS ++.IP "matching options" ++.IP ++The git-annex\-matching\-options(1) ++can be used to control what to act on. ++.IP ++.IP "\fB\-\-key=keyname\fP" ++Show where a particular git-annex key is located. ++.IP ++.IP "\fB\-\-all\fP \fB\-A\fP" ++Show whereis information for all known keys. ++.IP ++(Except for keys that have been marked as dead, ++see git-annex\-dead(1).) ++.IP ++.IP "\fB\-\-branch=ref\fP" ++Show whereis information for files in the specified branch or treeish. ++.IP ++.IP "\fB\-\-unused\fP" ++Show whereis information for files found by last run of git-annex unused. ++.IP ++.IP "\fB\-\-batch\fP" ++Enables batch mode, in which a file is read in a line from stdin, ++its information displayed, and repeat. ++.IP ++Note that if the file is not an annexed file, or does not match ++specified matching options, an empty line will be ++output instead. ++.IP ++.IP "\fB\-\-batch\-keys\fP" ++This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. ++.IP ++.IP "\fB\-z\fP" ++Makes batch input be delimited by nulls instead of the usual ++newlines. ++.IP ++.IP "\fB\-\-json\fP" ++Enable JSON output. This is intended to be parsed by programs that use ++git-annex. Each line of output is a JSON object. ++.IP ++.IP "\fB\-\-json\-error\-messages\fP" ++Messages that would normally be output to standard error are included in ++the JSON instead. ++.IP ++.IP "\fB\-\-format=value\fP" ++Use custom output formatting. ++.IP ++The value is a format string, in which '${var}' is expanded to the ++value of a variable. To right\-justify a variable with whitespace, ++use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; ++to escape unusual characters (including control characters) ++in a variable, use '${escaped_var}' ++.IP ++These variables are available for use in formats: file, key, uuid, ++url, backend, bytesize, humansize, keyname, hashdirlower, hashdirmixed, ++mtime (for the mtime field of a WORM key). ++.IP ++Also, '\\n' is a newline, '\\000' is a NULL, etc. ++.IP ++When the format contains the uuid variable, it will be expanded in turn ++for each repository that contains the file content. For example, ++with \-\-format="${file} ${uuid}\\n", output will look like: ++.IP ++ foo 00000000\-0000\-0000\-0000\-000000000001 ++ foo a7f7ddd0\-9a08\-11ea\-ab66\-8358e4209d30 ++ bar a7f7ddd0\-9a08\-11ea\-ab66\-8358e4209d30 ++.IP ++The same applies when the url variable is used and a file has multiple ++recorded urls. ++.IP ++.IP "Also the git-annex\-common\-options(1) can be used." ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-find(1) ++.PP ++git-annex\-list(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex-whereused.1 +@@ -0,0 +1,47 @@ ++.TH git-annex-whereused 1 ++.SH NAME ++git-annex-whereused \- find what files use or used a key ++.PP ++.SH SYNOPSIS ++git annex whereused \fB\-\-key=keyname|\-\-unused\fP ++.PP ++.SH DESCRIPTION ++Finds what files use or used a key. ++.PP ++For each file in the working tree that uses a key, this outputs one line, ++starting with the key, then a space, and then the name of the file. ++When multiple files use the same key, they will all be listed. When ++nothing is found that uses the key, there will be no output. ++.PP ++The default is to find only files in the current working tree that use a ++key. The \fB\-\-historical\fP option makes it also find past versions of files. ++.PP ++.SH OPTIONS ++.IP "\fB\-\-key=keyname\fP" ++.IP ++Operate on this key. ++.IP ++.IP "\fB\-\-unused\fP" ++Operate on keys found by last run of git-annex unused. ++.IP ++Usually these keys won't be used by any files in the current working ++tree, or any tags or branches. Combining this option with \fB\-\-historical\fP ++will find past uses of the keys. ++.IP ++.IP "\fB\-\-historical\fP" ++When no files in the current working tree use a key, this causes more ++work to be done, looking at past versions of the current branch, other ++branches, tags, and the reflog, to find somewhere that the key was used. ++It stops after finding one use of the key, and outputs a git rev that ++refers to where it was used, eg "HEAD@{40}:somefile" ++.IP ++.SH SEE ALSO ++git-annex(1) ++.PP ++git-annex\-unused(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-annex.1 +@@ -0,0 +1,2138 @@ ++.TH git-annex 1 ++.SH NAME ++git-annex \- manage files with git, without checking their contents in ++.PP ++.SH SYNOPSIS ++git annex command [params ...] ++.PP ++.SH DESCRIPTION ++git-annex allows managing files with git, without checking the file ++contents into git. While that may seem paradoxical, it is useful when ++dealing with files larger than git can currently easily handle, whether due ++to limitations in memory, checksumming time, or disk space. ++.PP ++Even without file content tracking, being able to manage files with git, ++move files around and delete files with versioned directory trees, and use ++branches and distributed clones, are all very handy reasons to use git. And ++annexed files can co\-exist in the same git repository with regularly ++versioned files, which is convenient for maintaining documents, Makefiles, ++etc that are associated with annexed files but that benefit from full ++revision control. ++.PP ++When a file is annexed, its content is moved into a key\-value store, and ++a symlink is made that points to the content. These symlinks are checked into ++git and versioned like regular files. You can move them around, delete ++them, and so on. Pushing to another git repository will make git-annex ++there aware of the annexed file, and it can be used to retrieve its ++content from the key\-value store. ++.PP ++.SH EXAMPLES ++ # git annex get video/hackity_hack_and_kaxxt.mov ++ get video/hackity_hack_and_kaxxt.mov (not available) ++ I was unable to access these remotes: server ++ Try making some of these repositories available: ++ 5863d8c0\-d9a9\-11df\-adb2\-af51e6559a49 \-\- my home file server ++ 58d84e8a\-d9ae\-11df\-a1aa\-ab9aa8c00826 \-\- portable USB drive ++ ca20064c\-dbb5\-11df\-b2fe\-002170d25c55 \-\- backup SATA drive ++ failed ++ # sudo mount /media/usb ++ # git remote add usbdrive /media/usb ++ # git annex get video/hackity_hack_and_kaxxt.mov ++ get video/hackity_hack_and_kaxxt.mov (from usbdrive...) ok ++ ++ # git annex add iso ++ add iso/Debian_5.0.iso ok ++ ++ # git annex drop iso/Debian_4.0.iso ++ drop iso/Debian_4.0.iso ok ++ ++ # git annex move iso \-\-to=usbdrive ++ move iso/Debian_5.0.iso (moving to usbdrive...) ok ++.PP ++.SH COMMONLY USED COMMANDS ++.IP "\fBhelp\fP" ++.IP ++Display built\-in help. ++.IP ++For help on a specific command, use \fBgit annex help command\fP ++.IP ++.IP "\fBadd [path ...]\fP" ++Adds files to the annex. ++.IP ++See git-annex\-add(1) for details. ++.IP ++.IP "\fBget [path ...]\fP" ++Makes the content of annexed files available in this repository. ++.IP ++See git-annex\-get(1) for details. ++.IP ++.IP "\fBdrop [path ...]\fP" ++Drops the content of annexed files from this repository. ++.IP ++See git-annex\-drop(1) for details. ++.IP ++.IP "\fBmove [path ...] [\-\-from=remote|\-\-to=remote]\fP" ++Moves the content of files from or to another remote. ++.IP ++See git-annex\-move(1) for details. ++.IP ++.IP "\fBcopy [path ...] [\-\-from=remote|\-\-to=remote]\fP" ++Copies the content of files from or to another remote. ++.IP ++See git-annex\-copy(1) for details. ++.IP ++.IP "\fBstatus [path ...]\fP" ++Show the working tree status. (deprecated) ++.IP ++See git-annex\-status(1) for details. ++.IP ++.IP "\fBunlock [path ...]\fP" ++Unlock annexed files for modification. ++.IP ++See git-annex\-unlock(1) for details. ++.IP ++.IP "\fBedit [path ...]\fP" ++This is an alias for the unlock command. May be easier to remember, ++if you think of this as allowing you to edit an annexed file. ++.IP ++.IP "\fBlock [path ...]\fP" ++Use this to undo an unlock command if you don't want to modify ++the files, or have made modifications you want to discard. ++.IP ++See git-annex\-lock(1) for details. ++.IP ++.IP "\fBpull [remote ...]\fP" ++Pull content from remotes. ++.IP ++See git-annex\-pull(1) for details. ++.IP ++.IP "\fBpush [remote ...]\fP" ++Push content to remotes. ++.IP ++See git-annex\-push(1) for details. ++.IP ++.IP "\fBsync [remote ...]\fP" ++Synchronize local repository with remotes. ++.IP ++See git-annex\-sync(1) for details. ++.IP ++.IP "\fBassist [remote ...]\fP" ++Add files and sync changes with remotes. ++.IP ++See git-annex\-assist(1) for details. ++.IP ++.IP "\fBsatisfy [remote ...]\fP" ++Satisfy preferred content settings by transferring and dropping content. ++.IP ++See git-annex\-satisfy(1) for details. ++.IP ++.IP "\fBmirror [path ...] [\-\-to=remote|\-\-from=remote]\fP" ++Mirror content of files to/from another repository. ++.IP ++See git-annex\-mirror(1) for details. ++.IP ++.IP "\fBaddurl [url ...]\fP" ++Downloads each url to its own file, which is added to the annex. ++.IP ++See git-annex\-addurl(1) for details. ++.IP ++.IP "\fBrmurl file url\fP" ++Record that the file is no longer available at the url. ++.IP ++See git-annex\-rmurl(1) for details. ++.IP ++.IP "\fBimport \-\-from remote branch[:subdir] | [path ...]\fP" ++Add a tree of files to the repository. ++.IP ++See git-annex\-import(1) for details. ++.IP ++.IP "\fBimportfeed [url ...]\fP" ++Imports the contents of podcast feeds into the annex. ++.IP ++See git-annex\-importfeed(1) for details. ++.IP ++.IP "\fBexport treeish \-\-to remote\fP" ++Export content to a remote. ++.IP ++See git-annex\-export(1) for details. ++.IP ++.IP "\fBundo [filename|directory] ...\fP" ++Undo last change to a file or directory. ++.IP ++See git-annex\-undo(1) for details. ++.IP ++.IP "\fBaddcomputed\fP" ++Adds computed files to the repository. ++.IP ++See git-annex\-addcomputed(1) for details. ++.IP ++.IP "\fBrecompute\fP" ++Recomputes computed files. ++.IP ++See git-annex\-recompute(1) for details. ++.IP ++.IP "\fBfindcomputed\fP" ++Lists computed files. ++.IP ++See git-annex\-findcomputed(1) for details. ++.IP ++.IP "\fBmulticast\fP" ++Multicast file distribution. ++.IP ++See git-annex\-multicast(1) for details. ++.IP ++.IP "\fBwatch\fP" ++Daemon to watch for changes and autocommit. ++.IP ++See git-annex\-watch(1) for details. ++.IP ++.IP "\fBassistant\fP" ++Daemon to automatically sync changes. ++.IP ++See git-annex\-assistant(1) for details. ++.IP ++.IP "\fBwebapp\fP" ++Opens a web app, that allows easy setup of a git-annex repository, ++and control of the git-annex assistant. If the assistant is not ++already running, it will be started. ++.IP ++See git-annex\-webapp(1) for details. ++.IP ++.IP "\fBp2phttp\fP" ++Allows a git-annex repository to be accessed over HTTP using git-annex ++p2p protocol. ++.IP ++See git-annex\-p2phttp(1) for details. ++.IP ++.IP "\fBremotedaemon\fP" ++Persistant communication with remotes. ++.IP ++See git-annex\-remotedaemon(1) for details. ++.IP ++.SH REPOSITORY SETUP COMMANDS ++.IP "\fBinit [description]\fP" ++.IP ++Until a repository (or one of its remotes) has been initialized, ++git-annex will refuse to operate on it, to avoid accidentally ++using it in a repository that was not intended to have an annex. ++.IP ++See git-annex\-init(1) for details. ++.IP ++.IP "\fBdescribe repository description\fP" ++Changes the description of a repository. ++.IP ++See git-annex\-describe(1) for details. ++.IP ++.IP "\fBinitremote name type=value [param=value ...]\fP" ++Creates a new special remote, and adds it to \fB.git/config\fP. ++.IP ++See git-annex\-initremote(1) for details. ++.IP ++.IP "\fBenableremote name [param=value ...]\fP" ++Enables use of an existing special remote in the current repository. ++.IP ++See git-annex\-enableremote(1) for details. ++.IP ++.IP "\fBconfigremote name [param=value ...]\fP" ++Changes configuration of an existing special remote. ++.IP ++See git-annex\-configremote(1) for details. ++.IP ++.IP "\fBrenameremote\fP" ++Renames a special remote. ++.IP ++See git-annex\-renameremote(1) for details. ++.IP ++.IP "\fBenable\-tor\fP" ++Sets up tor hidden service. ++.IP ++See git-annex\-enable\-tor(1) for details. ++.IP ++.IP "\fBnumcopies [N]\fP" ++Configure desired number of copies. ++.IP ++See git-annex\-numcopies(1) for details. ++.IP ++.IP "\fBmincopies [N]\fP" ++Configure minimum number of copies. ++.IP ++See git-annex\-mincopies(1) for details. ++.IP ++.IP "\fBtrust [repository ...]\fP" ++Records that a repository is trusted to not unexpectedly lose ++content. Use with care. ++.IP ++See git-annex\-trust(1) for details. ++.IP ++.IP "\fBuntrust [repository ...]\fP" ++Records that a repository is not trusted and could lose content ++at any time. ++.IP ++See git-annex\-untrust(1) for details. ++.IP ++.IP "\fBsemitrust [repository ...]\fP" ++Returns a repository to the default semi trusted state. ++.IP ++See git-annex\-semitrust(1) for details. ++.IP ++.IP "\fBgroup repository groupname\fP" ++Add a repository to a group. ++.IP ++See git-annex\-group(1) for details. ++.IP ++.IP "\fBungroup repository groupname\fP" ++Removes a repository from a group. ++.IP ++See git-annex\-ungroup(1) for details. ++.IP ++.IP "\fBwanted repository [expression]\fP" ++Get or set preferred content expression. ++.IP ++See git-annex\-wanted(1) for details. ++.IP ++.IP "\fBgroupwanted groupname [expression]\fP" ++Get or set groupwanted expression. ++.IP ++See git-annex\-groupwanted(1) for details. ++.IP ++.IP "\fBrequired repository [expression]\fP" ++Get or set required content expression. ++.IP ++See git-annex\-required(1) for details. ++.IP ++.IP "\fBmaxsize repository [size]\fP" ++Get or set maximum size of repository. ++.IP ++.IP "\fBinitcluster\fP" ++Initializes a new cluster. ++.IP ++See git-annex\-initcluster(1) for details. ++.IP ++.IP "\fBupdatecluster\fP" ++Update records of cluster nodes. ++.IP ++See git-annex\-updatecluster(1) for details. ++.IP ++.IP "\fBextendcluster\fP" ++Adds an additional gateway to a cluster. ++.IP ++See git-annex\-extendcluster(1) for details. ++.IP ++.IP "\fBupdateproxy\fP" ++Update records with proxy configuration. ++.IP ++See git-annex\-updateproxy(1) for details. ++.IP ++.IP "\fBschedule repository [expression]\fP" ++Get or set scheduled jobs. ++.IP ++See git-annex\-schedule(1) for details. ++.IP ++.IP "\fBconfig\fP" ++Get and set other configuration stored in git-annex branch. ++.IP ++See git-annex\-config(1) for details. ++.IP ++.IP "\fBvicfg\fP" ++Opens EDITOR on a temp file containing most of the above configuration ++settings, as well as a few others, and when it exits, stores any changes ++made back to the git-annex branch. ++.IP ++See git-annex\-vicfg(1) for details. ++.IP ++.IP "\fBadjust\fP" ++Switches a repository to use an adjusted branch, which can automatically ++unlock all files, etc. ++.IP ++See git-annex\-adjust(1) for details. ++.IP ++.IP "\fBdirect\fP" ++Switches a repository to use direct mode. (deprecated) ++.IP ++See git-annex\-direct(1) for details. ++.IP ++.IP "\fBindirect\fP" ++Switches a repository to use indirect mode. (deprecated) ++.IP ++See git-annex\-indirect(1) for details. ++.IP ++.SH REPOSITORY MAINTENANCE COMMANDS ++.IP "\fBfsck [path ...]\fP" ++.IP ++Checks the annex consistency, and warns about or fixes any problems found. ++This is a good complement to \fBgit fsck\fP. ++.IP ++See git-annex\-fsck(1) for details. ++.IP ++.IP "\fBexpire [repository:]time ...\fP" ++Expires repositories that have not recently performed an activity ++(such as a fsck). ++.IP ++See git-annex\-expire(1) for details. ++.IP ++.IP "\fBunused\fP" ++Checks the annex for data that does not correspond to any files present ++in any tag or branch, and prints a numbered list of the data. ++.IP ++See git-annex\-unused(1) for details. ++.IP ++.IP "\fBdropunused [number|range ...]\fP" ++Drops the data corresponding to the numbers, as listed by the last ++\fBgit annex unused\fP ++.IP ++See git-annex\-dropunused(1) for details. ++.IP ++.IP "\fBaddunused [number|range ...]\fP" ++Adds back files for the content corresponding to the numbers or ranges, ++as listed by the last \fBgit annex unused\fP. ++.IP ++See git-annex\-addunused(1) for details. ++.IP ++.IP "\fBfix [path ...]\fP" ++Fixes up symlinks that have become broken to again point to annexed content. ++.IP ++See git-annex\-fix(1) for details. ++.IP ++.IP "\fBmerge\fP" ++Automatically merge changes from remotes. ++.IP ++See git-annex\-merge(1) for details. ++.IP ++.IP "\fBupgrade\fP" ++Upgrades the repository. ++.IP ++See git-annex\-upgrade(1) for details. ++.IP ++.IP "\fBdead [repository ...] [\-\-key key]\fP" ++Indicates that a repository or a single key has been irretrievably lost. ++.IP ++See git-annex\-dead(1) for details. ++.IP ++.IP "\fBforget\fP" ++Causes the git-annex branch to be rewritten, throwing away historical ++data about past locations of files. ++.IP ++See git-annex\-forget(1) for details. ++.IP ++.IP "\fBfilter\-branch\fP" ++Produces a filtered version of the git-annex branch. ++.IP ++See git-annex\-filter\-branch(1) for details. ++.IP ++.IP "\fBrepair\fP" ++This can repair many of the problems with git repositories that \fBgit fsck\fP ++detects, but does not itself fix. It's useful if a repository has become ++badly damaged. One way this can happen is if a repository used by git-annex ++is on a removable drive that gets unplugged at the wrong time. ++.IP ++See git-annex\-repair(1) for details. ++.IP ++.IP "\fBp2p\fP" ++Configure peer\-2\-Peer links between repositories. ++.IP ++See git-annex\-p2p(1) for details. ++.IP ++.SH QUERY COMMANDS ++.IP "\fBfind [path ...]\fP" ++.IP ++Outputs a list of annexed files in the specified path. With no path, ++finds files in the current directory and its subdirectories. ++.IP ++See git-annex\-find(1) for details. ++.IP ++.IP "\fBwhereis [path ...]\fP" ++Displays information about where the contents of files are located. ++.IP ++See git-annex\-whereis(1) for details. ++.IP ++.IP "\fBlist [path ...]\fP" ++Displays a table of remotes that contain the contents of the specified ++files. This is similar to whereis but a more compact display. ++.IP ++See git-annex\-list(1) for details. ++.IP ++.IP "\fBwhereused\fP" ++Finds what files use or used a key. ++.IP ++.IP "\fBlog [path ...]\fP" ++Displays the location log for the specified file or files, ++showing each repository they were added to ("+") and removed from ("\-"). ++.IP ++See git-annex\-log(1) for details. ++.IP ++.IP "\fBoldkeys [path ...]\fP" ++List keys used for old versions of files. ++.IP ++See git-annex\-oldkeys(1) for details. ++.IP ++.IP "\fBinfo [directory|file|remote|uuid ...]\fP" ++Displays statistics and other information for the specified item, ++which can be a directory, or a file, or a remote, or the uuid of a ++repository. ++.IP ++When no item is specified, displays statistics and information ++for the repository as a whole. ++.IP ++See git-annex\-info(1) for details. ++.IP ++.IP "\fBversion\fP" ++Shows the version of git-annex, as well as repository version information. ++.IP ++See git-annex\-version(1) for details. ++.IP ++.IP "\fBmap\fP" ++Generate map of repositories. ++.IP ++See git-annex\-map(1) for details. ++.IP ++.IP "\fBinprogress\fP" ++Access files while they're being downloaded. ++.IP ++See git-annex\-inprogress(1) for details. ++.IP ++.IP "\fBfindkeys\fP" ++Similar to \fBgit-annex find\fP, but operating on keys. ++.IP ++See git-annex\-findkeys(1) for details. ++.IP ++.SH METADATA COMMANDS ++.IP "\fBmetadata [path ...]\fP" ++.IP ++The content of an annexed file can have any number of metadata fields ++attached to it to describe it. Each metadata field can in turn ++have any number of values. ++.IP ++This command can be used to set metadata, or show the currently set ++metadata. ++.IP ++See git-annex\-metadata(1) for details. ++.IP ++.IP "\fBview [tag ...] [field=value ...] [field=glob ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]\fP" ++Uses metadata to build a view branch of the files in the current branch, ++and checks out the view branch. Only files in the current branch whose ++metadata matches all the specified field values and tags will be ++shown in the view. ++.IP ++See git-annex\-view(1) for details. ++.IP ++.IP "\fBvpop [N]\fP" ++Switches from the currently active view back to the previous view. ++Or, from the first view back to original branch. ++.IP ++See git-annex\-vpop(1) for details. ++.IP ++.IP "\fBvfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]\fP" ++Filters the current view to only the files that have the ++specified field values and tags. ++.IP ++See git-annex\-vfilter(1) for details. ++.IP ++.IP "\fBvadd [field=glob ...] [field=value ...] [tag ...]\fP" ++Changes the current view, adding an additional level of directories ++to categorize the files. ++.IP ++See git-annex\-vfilter(1) for details. ++.IP ++.IP "\fBvcycle\fP" ++When a view involves nested subdirectories, this cycles the order. ++.IP ++See git-annex\-vcycle(1) for details. ++.IP ++.SH UTILITY COMMANDS ++.IP "\fBmigrate [path ...]\fP" ++.IP ++Changes the specified annexed files to use a different key\-value backend. ++.IP ++See git-annex\-migrate(1) for details. ++.IP ++.IP "\fBreinject src dest\fP" ++Moves the src file into the annex as the content of the dest file. ++This can be useful if you have obtained the content of a file from ++elsewhere and want to put it in the local annex. ++.IP ++See git-annex\-reinject(1) for details. ++.IP ++.IP "\fBunannex [path ...]\fP" ++Use this to undo an accidental \fBgit annex add\fP command. It puts the ++file back how it was before the add. ++.IP ++See git-annex\-unannex(1) for details. ++.IP ++.IP "\fBuninit\fP" ++De\-initialize git-annex and clean out repository. ++.IP ++See git-annex\-uninit(1) for details. ++.IP ++.IP "\fBreinit uuid|description\fP" ++Initialize repository, reusing old UUID. ++.IP ++See git-annex\-reinit(1) for details. ++.IP ++.SH PLUMBING COMMANDS ++.IP "\fBpre\-commit [path ...]\fP" ++.IP ++This is meant to be called from git's pre\-commit hook. \fBgit annex init\fP ++automatically creates a pre\-commit hook using this. ++.IP ++See git-annex\-pre\-commit(1) for details. ++.IP ++.IP "\fBpost\-receive\fP" ++This is meant to be called from git's post\-receive hook. \fBgit annex init\fP ++automatically creates a post\-receive hook using this. ++.IP ++See git-annex\-post\-receive(1) for details. ++.IP ++.IP "\fBlookupkey [file ...]\fP" ++Looks up key used for file. ++.IP ++See git-annex\-lookupkey(1) for details. ++.IP ++.IP "\fBcalckey [file ...]\fP" ++Calculates the key that would be used to refer to a file. ++.IP ++See git-annex\-calckey(1) for details. ++.IP ++.IP "\fBcontentlocation [key ..]\fP" ++Looks up location of annexed content for a key. ++.IP ++See git-annex\-contentlocation(1) for details. ++.IP ++.IP "\fBexaminekey [key ...]\fP" ++Print information that can be determined purely by looking at the key. ++.IP ++See git-annex\-examinekey(1) for details. ++.IP ++.IP "\fBmatchexpression\fP" ++Checks if a preferred content expression matches provided data. ++.IP ++See git-annex\-matchexpression(1) for details. ++.IP ++.IP "\fBfromkey [key file]\fP" ++Manually set up a file in the git repository to link to a specified key. ++.IP ++See git-annex\-fromkey(1) for details. ++.IP ++.IP "\fBregisterurl [key url]\fP" ++Registers an url for a key. ++.IP ++See git-annex\-registerurl(1) for details. ++.IP ++.IP "\fBunregisterurl [key url]\fP" ++Unregisters an url for a key. ++.IP ++See git-annex\-unregisterurl(1) for details. ++.IP ++.IP "\fBreregisterurl [key url]\fP" ++Updates url registration information. ++.IP ++See git-annex\-reregisterurl(1) for details. ++.IP ++.IP "\fBsetkey key file\fP" ++Moves a file into the annex as the content of a key. ++.IP ++See git-annex\-setkey(1) for details. ++.IP ++.IP "\fBdropkey [key ...]\fP" ++Drops annexed content for specified keys. ++.IP ++See git-annex\-dropkey(1) for details. ++.IP ++.IP "\fBtransferkey key [\-\-from=remote|\-\-to=remote]\fP" ++Transfers a key from or to a remote. ++.IP ++See git-annex\-transferkey(1) for details. ++.IP ++.IP "\fBtransferrer\fP" ++Used internally by git-annex to transfer content. ++.IP ++See git-annex\-transferrer(1) for details. ++.IP ++.IP "\fBtransferkeys\fP" ++Used internally by old versions of the assistant. ++.IP ++See git-annex\-transferkey(1) for details. ++.IP ++.IP "\fBsetpresentkey key uuid [1|0]\fP" ++This plumbing\-level command changes git-annex's records about whether ++the specified key's content is present in a remote with the specified uuid. ++.IP ++See git-annex\-setpresentkey(1) for details. ++.IP ++.IP "\fBreadpresentkey key uuid\fP" ++Read records of where key is present. ++.IP ++See git-annex\-readpresentkey(1) for details. ++.IP ++.IP "\fBcheckpresentkey key remote\fP" ++Check if key is present in remote. ++.IP ++See git-annex\-checkpresentkey(1) for details. ++.IP ++.IP "\fBrekey [file key ...]\fP" ++Change keys used for files. ++.IP ++See git-annex\-rekey(1) for details. ++.IP ++.IP "\fBresolvemerge\fP" ++Resolves a conflicted merge, by adding both conflicting versions of the ++file to the tree, using variants of their filename. This is done ++automatically when using \fBgit annex sync\fP or \fBgit-annex pull\fP ++or \fBgit annex merge\fP. ++.IP ++See git-annex\-resolvemerge(1) for details. ++.IP ++.IP "\fBdiffdriver\fP" ++This can be used to make \fBgit diff\fP diff the content of annexed files. ++.IP ++See git-annex\-diffdriver(1) for details. ++.IP ++.IP "\fBsmudge\fP" ++This command lets git-annex be used as a git filter driver, allowing ++annexed files in the git repository to be unlocked regular files instead ++of symlinks. ++.IP ++See git-annex\-smudge(1) for details. ++.IP ++.IP "\fBfilter\-process\fP" ++An alternative implementation of a git filter driver, that is faster ++in some situations and slower in others than \fBgit-annex smudge\fP. ++.IP ++See git-annex\-filter\-process(1) for details. ++.IP ++.IP "\fBrestage\fP" ++Restages unlocked files in the git index. ++.IP ++See git-annex\-restage(1) for details. ++.IP ++.IP "\fBfindref [ref]\fP" ++Lists files in a git ref. (deprecated) ++.IP ++See git-annex\-findref(1) for details. ++.IP ++.IP "\fBproxy \-\- git cmd [options]\fP" ++Bypass direct mode guard. (deprecated) ++.IP ++See git-annex\-proxy(1) for details. ++.IP ++.SH TESTING COMMANDS ++.IP "\fBtest\fP" ++.IP ++This runs git-annex's built\-in test suite. ++.IP ++See git-annex\-test(1) for details. ++.IP ++.IP "\fBtestremote remote\fP" ++This tests a remote by generating some random objects and sending them to ++the remote, then redownloading them, removing them from the remote, etc. ++.IP ++It's safe to run in an existing repository (the repository contents are ++not altered), although it may perform expensive data transfers. ++.IP ++See git-annex\-testremote(1) for details. ++.IP ++.IP "\fBsim\fP" ++This simulates a network of git-annex repositories. It can be used to ++test a configuration before using it in the real world. ++.IP ++See git-annex\-sim(1) for details. ++.IP ++.IP "\fBfuzztest\fP" ++Generates random changes to files in the current repository, ++for use in testing the assistant. ++.IP ++See git-annex\-fuzztest(1) for details. ++.IP ++.IP "\fBbenchmark\fP" ++This runs git-annex's built\-in benchmarks, if it was built with ++benchmarking support. ++.IP ++See git-annex\-benchmark(1) for details. ++.IP ++.SH ADDON COMMANDS ++In addition to all the commands listed above, more commands can be added to ++git-annex by dropping commands named like "git-annex\-foo" into a directory ++in the PATH. ++.PP ++.SH CONFIGURATION ++Like other git commands, git-annex is configured via \fB.git/config\fP. ++These settings, as well as relevant git config settings, are ++the ones git-annex uses. ++.PP ++(Some of these settings can also be set, across all clones of the ++repository, using git-annex\-config. See its man page for a list.) ++.PP ++.IP "\fBannex.uuid\fP" ++A unique UUID for this repository (automatically set). ++.IP ++.IP "\fBannex.backend\fP" ++Name of the default key\-value backend to use when adding new files ++to the repository. See git-annex\-backends(1) for information about ++available backends. ++.IP ++This is overridden by annex annex.backend configuration in the ++\&.gitattributes files, and by the \-\-backend option. ++.IP ++(This used to be named \fBannex.backends\fP, and that will still be used ++if set.) ++.IP ++.IP "\fBannex.securehashesonly\fP" ++Set to true to indicate that the repository should only use ++cryptographically secure hashes (SHA2, SHA3) and not insecure ++hashes (MD5, SHA1) for content. ++.IP ++When this is set, the contents of files using cryptographically ++insecure hashes will not be allowed to be added to the repository. ++.IP ++Also, \fBgit-annex fsck\fP will complain about any files present in ++the repository that use insecure hashes. And, ++\fBgit-annex import \-\-no\-content\fP will refuse to import files ++from special remotes using insecure hashes. ++.IP ++To configure the behavior in new clones of the repository, ++this can be set using git-annex\-config. ++.IP ++.IP "\fBannex.maxextensionlength\fP" ++Maximum length, in bytes, of what is considered a filename extension. ++This is used when adding a file to a backend that preserves filename extensions, ++and also when generating a view branch. ++.IP ++The default length is 4, which allows extensions like "jpeg". The dot before ++the extension is not counted part of its length. ++.IP ++.IP "\fBannex.maxextensions\fP" ++Maximum number of filename extensions to preserve when using a backend ++that preserves filename extensions, and also when generating a view ++branch. ++.IP ++The default is 2, which allows for compound extensions like ".tar.gz". ++When set to 1, it will only preserve the last extension, eg ".gz". ++.IP ++.IP "\fBannex.diskreserve\fP" ++Amount of disk space to reserve. Disk space is checked when transferring ++annexed content to avoid running out, and additional free space can be ++reserved via this option, to make space for other data (such as git ++commit logs). Can be specified with any commonly used units, for ++example, "0.5 gb", "500M", or "100 KiloBytes" ++.IP ++The default reserve is 100 megabytes. ++.IP ++.IP "\fBannex.fullybalancedthreshhold\fP" ++Configures the percent full a repository must be in order for ++the "fullybalanced" preferred content expression to consider it ++to be full. The default is 90. ++.IP ++.IP "\fBannex.skipunknown\fP" ++Set to true to make commands like "git-annex get" silently skip over ++items that are listed in the command line, but are not checked into git. ++.IP ++Set to false to make it an error for commands like "git-annex get" ++to be asked to operate on files that are not checked into git. ++(This is the default in recent versions of git-annex.) ++.IP ++Note that, when annex.skipunknown is false, a command like "git-annex get ++\&." will fail if no files in the current directory are checked into git. ++Commands like "git-annex get foo/" will fail if no files in the directory ++are checked into git, but if at least one file is, it will ignore other ++files that are not. This is all the same as the behavior of "git\-ls files ++\-\-error\-unmatch". ++.IP ++Also note that git-annex skips files that are checked into git, but are ++not annexed files; this setting does not affect that. ++.IP ++.IP "\fBannex.largefiles\fP" ++Used to configure which files are large enough to be added to the annex. ++It is an expression that matches the large files, eg ++"\fBinclude=*.mp3 or largerthan=500kb\fP" ++See git-annex\-matching\-expression(1) for details on the syntax. ++.IP ++Overrides any annex.largefiles attributes in \fB.gitattributes\fP files. ++.IP ++To configure a default annex.largefiles for all clones of the repository, ++this can be set in git-annex\-config(1). ++.IP ++This configures the behavior of both git-annex and git when adding ++files to the repository. By default, \fBgit-annex add\fP adds all files ++to the annex (except dotfiles and files in dotdirs), and \fBgit add\fP ++adds files to git (unless they were added to the annex previously). ++When annex.largefiles is configured, both ++\fBgit annex add\fP and \fBgit add\fP will add matching large files to the ++annex, and the other files to git. ++.IP ++Other git-annex commands also honor annex.largefiles, including ++\fBgit annex import\fP, \fBgit annex addurl\fP, \fBgit annex importfeed\fP, ++\fBgit-annex assist\fP, and the \fBgit-annex assistant\fP. ++.IP ++.IP "\fBannex.dotfiles\fP" ++Normally, dotfiles and files inside dotdirs are assumed to be ++configuration files like .gitignore, whose content should always ++be part of the git repository, so they will not be added to the annex. ++Setting annex.dotfiles to true makes these files be added to the ++annex the same as any other file. ++.IP ++To annex only some dotfiles, set this and configure annex.largefiles ++to match the ones you want. For example, to match only dotfiles ending ++in ".big" ++.IP ++ git config annex.largefiles "(include=.*.big or include=*/.*.big) or (exclude=.* and exclude=*/.*)" ++ git config annex.dotfiles true ++.IP ++To configure a default annex.dotfiles for all clones of the repository, ++this can be set in git-annex\-config(1). ++.IP ++.IP "\fBannex.gitaddtoannex\fP" ++Setting this to false will prevent \fBgit add\fP from adding ++files to the annex, despite the annex.largefiles configuration. ++.IP ++.IP "\fBannex.addsmallfiles\fP" ++Controls whether small files (files not matching annex.largefiles, or ++dotfiles) should be checked into git by \fBgit annex add\fP. Defaults to true; ++set to false to instead make small files be skipped. ++.IP ++.IP "\fBannex.addunlocked\fP" ++Commands like \fBgit-annex add\fP default to adding files to the repository ++in locked form. This can make them add the files in unlocked form, ++the same as if git-annex\-unlock(1) were run on the files. ++.IP ++This can be set to "true" to add everything unlocked, or it can be a more ++complicated expression that matches files by name, size, or content. See ++git-annex\-matching\-expression(1) for details. ++.IP ++To configure a default annex.addunlocked for all clones of the repository, ++this can be set in git-annex\-config(1). ++.IP ++(Using \fBgit add\fP always adds files in unlocked form and it is not ++affected by this setting.) ++.IP ++When a repository has core.symlinks set to false, or has an adjusted ++unlocked branch checked out, this setting is ignored, and files are ++always added to the repository in unlocked form. ++.IP ++.IP "\fBannex.numcopies\fP" ++This is a deprecated setting. You should instead use the ++\fBgit annex numcopies\fP command to configure how many copies of files ++are kept across all repositories, or the annex.numcopies .gitattributes ++setting. ++.IP ++This config setting is only looked at when \fBgit annex numcopies\fP has ++never been configured, and when there's no annex.numcopies setting in the ++\&.gitattributes file. ++.IP ++.IP "\fBannex.genmetadata\fP" ++Set this to \fBtrue\fP to make git-annex automatically generate some metadata ++when adding files to the repository. ++.IP ++In particular, it stores year, month, and day metadata, from the file's ++modification date. ++.IP ++When importfeed is used, it stores additional metadata from the feed, ++such as the author, title, etc. ++.IP ++.IP "\fBannex.used\-refspec\fP" ++This controls which refs \fBgit-annex unused\fP considers to be used. ++See REFSPEC FORMAT in git-annex\-unused(1) for details. ++.IP ++.IP "\fBannex.jobs\fP" ++Configure the number of concurrent jobs to run. Default is 1. ++.IP ++Only git-annex commands that support the \-\-jobs option will ++use this. ++.IP ++Setting this to "cpus" will run one job per CPU core. ++.IP ++When the \fB\-\-batch\fP option is used, this configuration is ignored. ++.IP ++.IP "\fBannex.adjustedbranchrefresh\fP" ++When git-annex\-adjust(1) is used to set up an adjusted branch ++that needs to be refreshed after getting or dropping files, this config ++controls how frequently the branch is refreshed. ++.IP ++Refreshing the branch takes some time, so doing it after every file ++can be too slow. (It also can generate a lot of dangling git objects.) ++The default value is 0 (or false), which does not ++refresh the branch. Setting 1 (or true) will refresh only once, ++after git-annex has made other changes. Setting 2 refreshes after every ++file, 3 after every other file, and so on; setting 100 refreshes after ++every 99 files. ++.IP ++(If git-annex gets faster in the future, refresh rates will increase ++proportional to the speed improvements.) ++.IP ++.IP "\fBannex.queuesize\fP" ++git-annex builds a queue of git commands, in order to combine similar ++commands for speed. By default the size of the queue is limited to ++10240 commands; this can be used to change the size. If you have plenty ++of memory and are working with very large numbers of files, increasing ++the queue size can speed it up. ++.IP ++.IP "\fBannex.bloomcapacity\fP" ++The \fBgit annex unused\fP and \fBgit annex sync \-\-content\fP commands use ++a bloom filter to determine what files are present in eg, the work tree. ++The default bloom filter is sized to handle ++up to 500000 files. If your repository is larger than that, ++you should increase this value. Larger values will ++make \fBgit-annex unused\fP and \fBgit annex sync \-\-content\fP consume more memory; ++run \fBgit annex info\fP for memory usage numbers. ++.IP ++.IP "\fBannex.bloomaccuracy\fP" ++Adjusts the accuracy of the bloom filter used by ++\fBgit annex unused\fP and \fBgit annex sync \-\-content\fP. ++The default accuracy is 10000000 \-\- 1 unused file out of 10000000 ++will be missed by \fBgit annex unused\fP. Increasing the accuracy will make ++\fBgit annex unused\fP consume more memory; run \fBgit annex info\fP ++for memory usage numbers. ++.IP ++.IP "\fBannex.sshcaching\fP" ++By default, git-annex caches ssh connections using ssh's ++ControlMaster and ControlPersist settings ++(if built using a new enough ssh). To disable this, set to \fBfalse\fP. ++.IP ++.IP "\fBannex.adviceNoSshCaching\fP" ++When git-annex is unable to use ssh connection caching, or has been ++configured not to, and concurrency is enabled, it will warn that ++this might result in multiple ssh processes prompting for passwords ++at the same time. To disable that warning, eg if you have configured ssh ++connection caching yourself, or have ssh agent caching passwords, ++set this to \fBfalse\fP. ++.IP ++.IP "\fBannex.alwayscommit\fP" ++By default, git-annex automatically commits data to the git-annex branch ++after each command is run. If you have a series ++of commands that you want to make a single commit, you can ++run the commands with \fB\-c annex.alwayscommit=false\fP. You can later ++commit the data by running \fBgit annex merge\fP (or by automatic merges) ++or \fBgit annex sync\fP. ++.IP ++.IP "\fBannex.commitmessage\fP" ++When git-annex updates the git-annex branch, it usually makes up ++its own commit message (eg "update"), since users rarely look at or ++care about changes to that branch. If you do care, you can ++specify this setting by running commands with ++\fB\-c annex.commitmessage=whatever\fP ++.IP ++This works well in combination with annex.alwayscommit=false, ++to gather up a set of changes and commit them with a message you specify. ++.IP ++.IP "\fBannex.commitmessage\-command\fP" ++This command is run and its output is used as the commit message to the ++git-annex branch. ++.IP ++Alternatively, a hook script can be installed in ++\fB.git/hooks/commitmessage\-annex\fP ++.IP ++.IP "\fBannex.post\-update\-command\fP" ++This command is run after git-annex updates the git-annex branch. ++.IP ++When publishing a git-annex repository by http, this can be used to run ++\fBgit update\-server\-info\fP ++.IP ++Alternatively, a hook script can be installed in ++\fB.git/hooks/post\-update\-annex\fP ++.IP ++.IP "\fBannex.pre\-commit\-command\fP" ++This command is run whenever a commit is made to the HEAD branch of ++the git repository, either by git commit, or by git-annex. ++.IP ++Alternatively, a hook script can be installed in ++\fB.git/hooks/pre\-commit\-annex\fP ++.IP ++.IP "\fBannex.pre\-init\-command\fP" ++This command is run before the repository is initialized, either by ++\fBgit-annex init\fP, or automatic initialization. It can configure ++the repository in any way needed. If it exits nonzero, the repository ++initialization will fail. ++.IP ++Alternatively, a hook script can be installed in ++\fB.git/hooks/pre\-init\-annex\fP ++.IP ++.IP "\fBannex.alwayscompact\fP" ++By default, git-annex compacts data it records in the git-annex branch. ++Setting this to false avoids doing that compaction in some cases, which ++can speed up operations that populate the git-annex branch with a lot ++of data. However, when used with operations that overwrite old values in ++the git-annex branch, that may cause the git-annex branch to use more disk ++space, and so slow down reading data from it. ++.IP ++An example of a command that can be sped up by using ++\fB\-c annex.alwayscompact=false\fP is \fBgit-annex registerurl \-\-batch\fP, ++when adding a large number of urls to the same key. ++.IP ++This option was first supported by git-annex version 10.20220724. ++It is not entirely safe to set this option in a repository that may also ++be used by an older version of git-annex at the same time as a version ++that supports this option. ++.IP ++.IP "\fBannex.allowsign\fP" ++By default git-annex avoids gpg signing commits that it makes when ++they're not the purpose of a command, but only a side effect. ++That default avoids lots of gpg password prompts when ++commit.gpgSign is set. A command like \fBgit annex sync\fP or \fBgit annex merge\fP ++will gpg sign its commit, but a command like \fBgit annex get\fP, ++that updates the git-annex branch, will not. The assistant also avoids ++signing commits. ++.IP ++Setting annex.allowsign to true lets all commits be signed, as ++controlled by commit.gpgSign and other git configuration. ++.IP ++.IP "\fBannex.merge\-annex\-branches\fP" ++By default, git-annex branches that have been pulled from remotes ++are automatically merged into the local git-annex branch, so that ++git-annex has the most up\-to\-date possible knowledge. ++.IP ++To avoid that merging, set this to "false". ++.IP ++This can be useful particularly when you don't have write permission ++to the repository. While git-annex is mostly able to work in a read\-only ++repository with unmerged git-annex branches, some things do not work, ++and when it does work it will be slower due to needing to look at each of ++the unmerged branches. ++.IP ++.IP "\fBannex.private\fP" ++When this is set to true, no information about the repository will be ++recorded in the git-annex branch. ++.IP ++For example, to make a repository without any mention of it ever ++appearing in the git-annex branch: ++.IP ++ git init myprivate ++ cd myprivaterepo ++ git config annex.private true ++ git annex init ++.IP ++.IP "\fBannex.hardlink\fP" ++Set this to \fBtrue\fP to make file contents be hard linked between the ++repository and its remotes when possible, instead of a more expensive copy. ++.IP ++Use with caution \-\- This can invalidate numcopies counting, since ++with hard links, fewer copies of a file can exist. So, it is a good ++idea to mark a repository using this setting as untrusted. ++.IP ++When a repository is set up using \fBgit clone \-\-shared\fP, git-annex init ++will automatically set annex.hardlink and mark the repository as ++untrusted. ++.IP ++When \fBannex.thin\fP is also set, setting \fBannex.hardlink\fP has no effect. ++.IP ++.IP "\fBannex.thin\fP" ++Set this to \fBtrue\fP to make unlocked files be a hard link to their content ++in the annex, rather than a second copy. This can save considerable ++disk space, but when a modification is made to a file, you will lose the ++local (and possibly only) copy of the old version. Any other, locked ++files in the repository that pointed to that content will get broken ++as well (\fBgit-annex fsck\fP will detect and clean up after that). ++So, enable this with care. ++.IP ++After setting (or unsetting) this, you should run \fBgit annex fix\fP to ++fix up the annexed files in the work tree to be hard links (or copies). ++.IP ++Note that this has no effect when the filesystem does not support hard links. ++And when multiple files in the work tree have the same content, only ++one of them gets hard linked to the annex. ++.IP ++.IP "\fBannex.supportunlocked\fP" ++By default git-annex supports unlocked files as well as locked files, ++so this defaults to true. If set to false, git-annex will only support ++locked files. That will avoid doing the work needed to support unlocked ++files. ++.IP ++Note that setting this to false does not prevent a repository from ++having unlocked files added to it, and in that case the content of the ++files will not be accessible until they are locked. ++.IP ++After changing this config, you need to re\-run \fBgit-annex init\fP for it ++to take effect. ++.IP ++.IP "\fBannex.url\fP" ++When a remote has a http url, the first time git-annex uses the remote ++it will check if it can download its \fB.git/config\fP file. If it is able ++to, and the file has this config set to an "annex+http" or "annex+https" ++url, that url will be copied into \fBremote..annexUrl\fP. ++.IP ++.IP "\fBannex.resolvemerge\fP" ++Set to false to prevent merge conflicts in the checked out branch ++being automatically resolved by the \fBgit-annex assitant\fP, ++\fBgit-annex assist\fP, \fBgit-annex sync\fP, \fBgit-annex pull\fP, \fBgit-annex merge\fP, ++and the git-annex post\-receive hook. ++.IP ++To configure the behavior in all clones of the repository, ++this can be set in git-annex\-config(1). ++.IP ++.IP "\fBannex.synccontent\fP" ++Set to true to make \fBgit-annex sync\fP default to transferring ++annexed content. ++.IP ++Set to false to prevent \fBgit-annex assist\fP, \fBgit-annex pull\fP and ++\fBgit-annex push\fP from transferring annexed content. ++.IP ++To configure the behavior in all clones of the repository, ++this can be set in git-annex\-config(1). ++.IP ++.IP "\fBannex.synconlyannex\fP" ++Set to true to make \fBgit-annex assist\fP, \fBgit-annex sync\fP, ++\fBgit-annex pull\fP, and \fBgit-annex push\fP default to only operating ++on the git-annex branch and annexed content. ++.IP ++To configure the behavior in all clones of the repository, ++this can be set in git-annex\-config(1). ++.IP ++.IP "\fBannex.syncmigrations\fP" ++Set to false to prevent \fBgit-annex sync\fP and \fBgit-annex pull\fP ++from scanning for migrations and updating the local ++repository for those migrations. ++.IP ++.IP "\fBannex.viewunsetdirectory\fP" ++This configures the name of a directory that is used in a view to contain ++files that do not have metadata set. The default name for the directory ++is \fB"_"\fP. See git-annex\-view(1) for details. ++.IP ++.IP "\fBannex.debug\fP" ++Set to true to enable debug logging by default. ++.IP ++.IP "\fBannex.debugfilter\fP" ++Set to configure which debug messages to display (when debug message ++display has been enabled by annex.debug or \-\-debug). The value is one ++or more module names, separated by commas. ++.IP ++.IP "\fBannex.version\fP" ++The current version of the git-annex repository. This is ++maintained by git-annex and should never be manually changed. ++.IP ++.IP "\fBannex.autoupgraderepository\fP" ++When an old git-annex repository version is no longer supported, ++git-annex will normally automatically upgrade the repository to ++the new version. It may also sometimes upgrade from an old repository ++version that is still supported but that is not as good as a later ++version. ++.IP ++If this is set to false, git-annex won't automatically upgrade the ++repository. If the repository version is not supported, git-annex ++will instead exit with an error message. If it is still supported, ++git-annex will continue to work. ++.IP ++You can run \fBgit annex upgrade\fP yourself when you are ready to upgrade the ++repository. ++.IP ++.IP "\fBannex.crippledfilesystem\fP" ++Set to true if the repository is on a crippled filesystem, such as FAT, ++which does not support symbolic links, or hard links, or unix permissions. ++This is automatically probed by "git annex init". ++.IP ++.IP "\fBannex.pidlock\fP" ++Normally, git-annex uses fine\-grained lock files to allow multiple ++processes to run concurrently without getting in each others' way. ++That works great, unless you are using git-annex on a filesystem that ++does not support POSIX fcntl locks. This is sometimes the case when ++using NFS or Lustre filesystems. ++.IP ++To support such situations, you can set annex.pidlock to true, and it ++will fall back to a single top\-level pid file lock. ++.IP ++Although, often, you'd really be better off fixing your networked ++filesystem configuration to support POSIX locks.. And, some networked ++filesystems are so inconsistent that one node can't reliably tell when ++the other node is holding a pid lock. Caveat emptor. ++.IP ++.IP "\fBannex.pidlocktimeout\fP" ++git-annex will wait up to this many seconds for the pid lock ++file to go away, and will then abort if it cannot continue. Default: 300 ++.IP ++When using pid lock files, it's possible for a stale lock file to get ++left behind by previous run of git-annex that crashed or was interrupted. ++This is mostly avoided, but can occur especially when using a network ++file system. This timeout prevents git-annex waiting forever in such a ++situation. ++.IP ++.IP "\fBannex.dbdir\fP" ++The directory where git-annex should store its sqlite databases. ++The default location is inside \fB.git/annex/\fP. ++.IP ++Certian filesystems, such as cifs, may not support locking operations ++that sqlite needs, and setting this to a directory on another filesystem ++can work around such a problem. ++.IP ++This can safely be set to the same directory in the configuration of ++multiple repositories; each repository will use a subdirectory for its ++sqlite database. ++.IP ++.IP "\fBannex.cachecreds\fP" ++When "true" (the default), git-annex will cache credentials used to ++access special remotes in files in .git/annex/creds/ ++that only you can read. To disable that caching, set to "false", ++and credentials will only be read from the environment, or if ++they have been embedded in encrypted form in the git repository, will ++be extracted and decrypted each time git-annex needs to access the ++remote. ++.IP ++.IP "\fBannex.secure\-erase\-command\fP" ++This can be set to a command that should be run whenever git-annex ++removes the content of a file from the repository. ++.IP ++In the command line, %file is replaced with the file that should be ++erased. ++.IP ++For example, to use the wipe command, set it to \fBwipe \-f %file\fP. ++.IP ++Alternatively to setting the git config, a hook script can be installed ++in \fB.git/hooks/secure\-erase\-annex\fP. The hook is passed the file to be ++erased as its only parameter. ++.IP ++.IP "\fBannex.freezecontent\-command\fP, \fBannex.thawcontent\-command\fP" ++Usually the write permission bits are unset to protect annexed objects ++from being modified or deleted. Freezecontent is run after ++git-annex has removed (or attempted to remove) the write bit, and can ++be used to prevent writing in some other way. ++Thawcontent should undo its effect, and is run before ++git-annex restores the write bit. ++.IP ++In the command line, %path is replaced with the file or directory to ++operate on. ++.IP ++(When annex.crippledfilesystem is set, git-annex will not try to ++remove/restore the write bit, but it will still run freezecontent and ++thawcontent.) ++.IP ++Alternatively to setting the git config, hook scripts can be installed ++in \fB.git/hooks/freezecontent\-annex\fP and \fB.git/hooks/thawcontent\-annex\fP. ++The hook is passed the file or directory to operate on as its only ++parameter. ++.IP ++.IP "\fBannex.tune.objecthash1\fP, \fBannex.tune.objecthashlower\fP, \fBannex.tune.branchhash1\fP" ++These can be passed to \fBgit annex init\fP to tune the repository. ++They cannot be safely changed in a running repository and should never be ++set in global git configuration. ++For details, see . ++.IP ++.IP "\fBannex.cluster.\fP" ++This is set to make the repository be a gateway to a cluster. ++The value is the cluster UUID. Note that cluster UUIDs are not ++the same as repository UUIDs, and a repository UUID cannot be used here. ++.IP ++Usually this is set up by running git-annex\-initcluster or ++git-annex\-extendcluster. ++.IP ++.SH CONFIGURATION OF REMOTES ++Remotes are configured using these settings in \fB.git/config\fP. ++.PP ++.IP "\fBremote..annex\-cost\fP" ++When determining which repository to ++transfer annexed files from or to, ones with lower costs are preferred. ++The default cost is 100 for local repositories, and 200 for remote ++repositories. ++.IP ++.IP "\fBremote..annex\-cost\-command\fP" ++If set, the command is run, and the number it outputs is used as the cost. ++This allows varying the cost based on e.g., the current network. ++.IP ++.IP "\fBremote..annex\-start\-command\fP" ++A command to run when git-annex begins to use the remote. This can ++be used to, for example, mount the directory containing the remote. ++.IP ++The command may be run repeatedly when multiple git-annex processes ++are running concurrently. ++.IP ++.IP "\fBremote..annex\-stop\-command\fP" ++A command to run when git-annex is done using the remote. ++.IP ++The command will only be run once *all* running git-annex processes ++are finished using the remote. ++.IP ++.IP "\fBremote..annex\-shell\fP" ++Specify an alternative git-annex\-shell executable on the remote ++instead of looking for "git-annex\-shell" on the PATH. ++.IP ++This is useful if the git-annex\-shell program is outside the PATH ++or has a non\-standard name. ++.IP ++.IP "\fBremote..annex\-ignore\fP" ++If set to \fBtrue\fP, prevents git-annex from storing or retrieving annexed ++file contents on this remote by default. ++(You can still request it be used with the \fB\-\-from\fP and \fB\-\-to\fP options.) ++.IP ++This is, for example, useful if the remote is located somewhere ++without git-annex\-shell. (For example, if it's on GitHub). ++Or, it could be used if the network connection between two ++repositories is too slow to be used normally. ++.IP ++This does not prevent \fBgit-annex sync\fP, \fBgit-annex pull\fP, \fBgit-annex push\fP, ++\fBgit-annex assist\fP or the \fBgit-annex assistant\fP from operating on the ++git repository. It only affects annexed content. ++.IP ++.IP "\fBremote..annex\-ignore\-command\fP" ++If set, the command is run, and if it exits nonzero, that's the same ++as setting annex\-ignore to true. This allows controlling behavior based ++on e.g., the current network. ++.IP ++.IP "\fBremote..annex\-sync\fP" ++If set to \fBfalse\fP, prevents \fBgit-annex sync\fP (and \fBgit-annex pull\fP, ++\fBgit-annex push\fP, \fBgit-annex assist\fP, and the \fBgit-annex assistant\fP) ++from operating on this remote by default. ++.IP ++.IP "\fBremote..annex\-sync\-command\fP" ++If set, the command is run, and if it exits nonzero, that's the same ++as setting annex\-sync to false. This allows controlling behavior based ++on e.g., the current network. ++.IP ++.IP "\fBremote..annex\-pull\fP" ++If set to \fBfalse\fP, prevents \fBgit-annex pull\fP, \fBgit-annex sync\fP, ++\fBgit-annex assist\fP and the \fBgit-annex assistant\fP from ever pulling ++(or fetching) from the remote. ++.IP ++.IP "\fBremote..annex\-push\fP" ++If set to \fBfalse\fP, prevents \fBgit-annex push\fP, \fBgit-annex sync\fP, ++\fBgit-annex assist\fP and the \fBgit-annex assistant\fP from ever pushing ++to the remote. ++.IP ++.IP "\fBremote..annex\-readonly\fP" ++If set to \fBtrue\fP, prevents git-annex from making changes to a remote. ++This prevents \fBgit-annex sync\fP and \fBgit-annex assist\fP from pushing ++changes to a git repository. And it prevents storing or removing ++files from read\-only remote. ++.IP ++.IP "\fBremote..annex\-verify\fP, \fBannex.verify\fP" ++By default, git-annex will verify the checksums of objects downloaded ++from remotes. If you trust a remote and don't want the overhead ++of these checksums, you can set this to \fBfalse\fP. ++.IP ++Note that even when this is set to \fBfalse\fP, git-annex does verification ++in some edge cases, where it's likely the case than an ++object was downloaded incorrectly, or when needed for security. ++.IP ++.IP "\fBremote..annex\-tracking\-branch\fP" ++This is for use with special remotes that support exports and imports. ++.IP ++When set to eg, "master", this tells git-annex that you want the ++special remote to track that branch. ++.IP ++When set to eg, "master:subdir", the special remote tracks only ++the subdirectory of that branch. ++.IP ++Setting this enables some other commands to work with these special ++remotes: \fBgit-annex pull\fP will import changes from the remote and merge them into ++the annex\-tracking\-branch. And \fBgit-annex push\fP will export changes to ++the remote. Higher\-level commands \fBgit-annex sync \-\-content\fP ++and \fBgit-annex assist\fP both import and export. ++.IP ++.IP "\fBremote..annex\-export\-tracking\fP" ++Deprecated name for \fBremote..annex\-tracking\-branch\fP. Will still be used ++if it's configured and \fBremote..annex\-tracking\-branch\fP is not. ++.IP ++.IP "\fBremote..annexUrl\fP" ++Can be used to specify a different url than the regular \fBremote..url\fP ++for git-annex to use for accessing the remote. Similar to the \fBpushUrl\fP ++used by git\-push. ++.IP ++When this is set to an annex+http or annex+https url, that url is used ++for git-annex operations only, and the \fBremote..url\fP is used for ++git operations. This allows using git-annex\-p2phttp to serve a ++git-annex repository over http. ++.IP ++When this and the \fBremote..url\fP contain the same hostname, ++and this is an annex+http(s) url, and that is also a http(s) url, ++git-annex assumes that the same username and password can be used ++for both urls. When password caching is configured, this allows ++you to only be prompted once for a password when using both git and ++git-annex. See gitcredentials(7) for how to set up password caching. ++.IP ++.IP "\fBurl..annexInsteadOf\fP" ++This works similarly to git's \fBurl..pushInsteadOf\fP, rewriting ++a remote url that starts with the value of this config to instead ++start with \fB\fP. ++.IP ++The rewritten url is used by git-annex for accessing the remote, ++and works the same as \fBremote..annexUrl\fP, including supporting ++annex+http urls. ++.IP ++Note that git-annex also supports git's \fBurl..insteadOf\fP ++configuration. When both are set, the remote's url is first rewritten ++by insteadOf, and that rewritten url can then be further ++rewritten using annexInsteadOf. ++.IP ++.IP "\fBremote..annex\-uuid\fP" ++git-annex caches UUIDs of remote repositories here. ++.IP ++.IP "\fBremote..annex\-config\-uuid\fP" ++Used for some special remotes, points to a different special remote ++configuration to use. ++.IP ++.IP "\fBremote..annex\-retry\fP, \fBannex.retry\fP" ++Number of times a transfer that fails can be retried. (default 0) ++.IP ++.IP "\fBremote..annex\-forward\-retry\fP, \fBannex.forward\-retry\fP" ++If a transfer made some forward progress before failing, ++this allows it to be retried even when \fBannex.retry\fP does not. ++The value is the maximum number of times to do that. (default 5) ++.IP ++When both \fBannex.retry\fP and this are set, the maximum number of ++retries is the larger of the two. ++.IP ++.IP "\fBremote..annex\-retry\-delay\fP, \fBannex.retry\-delay\fP" ++Number of seconds to delay before the first retry of a transfer. ++When making multiple retries of the same transfer, the delay ++doubles after each retry. (default 1) ++.IP ++.IP "\fBremote..annex\-bwlimit\fP, \fBannex.bwlimit\fP" ++This can be used to limit how much bandwidth is used for a transfer ++from or to a remote. ++.IP ++For example, to limit transfers to 1 mebibyte per second: ++\fBgit config annex.bwlimit "1MiB"\fP ++.IP ++This will work with many remotes, including git remotes, but not ++for remotes where the transfer is run by a separate program than ++git-annex. ++.IP ++.IP "\fBremote..annex\-bwlimit\-download\fP, \fBannex.bwlimit\-download\fP" ++Limit bandwith for downloads from a remote. ++.IP ++Overrides \fBremote..annex\-bwlimit\fP and \fBannex.bwlimit\fP ++.IP ++.IP "\fBremote..annex\-bwlimit\-upload\fP, \fBannex.bwlimit\-upload\fP" ++Limit bandwith for uploads to a remote. ++.IP ++Overrides \fBremote..annex\-bwlimit\fP and \fBannex.bwlimit\fP ++.IP ++.IP "\fBremote..annex\-stalldetection\fP, \fBannex.stalldetection\fP" ++Configuring this lets stalled or too\-slow transfers be detected, and ++dealt with, so rather than getting stuck, git-annex will cancel the ++stalled operation. The transfer will be considered to have failed, so ++settings like annex.retry will control what it does next. ++.IP ++The default is to automatically detect when transfers that have probably ++stalled, and suggest configuring this, but not cancel the stalled ++operations. For this to work, a remote needs to update its progress ++consistently. Remotes that do not will not have automatic stall detection ++done. And it may take a while for git-annex to decide a remote is really ++stalled when using automatic stall detection, since it needs to be ++conservative about what looks like a stall. ++.IP ++Set to "false" to avoid all attempts at stall detection. ++.IP ++To detect and cancel stalled transfers, set this to a value in the form ++"$amount/$timeperiod" which specifies how much data git-annex should ++expect to see flowing, minimum, over a given period of time. ++.IP ++For example, to detect outright stalls where no data has been transferred ++after 30 seconds: \fBgit config annex.stalldetection "1KB/30s"\fP ++.IP ++Or, if you have a remote on a USB drive that is normally capable of ++several megabytes per second, but has bad sectors where it gets ++stuck for a long time, you could use: ++\fBgit config remote.usbdrive.annex\-stalldetection "1MB/1m"\fP ++.IP ++Some remotes don't report transfer progress, and stalls cannot be ++detected when using those. ++.IP ++Some remotes only report transfer progress occasionally, eg ++after each chunk. To avoid false timeouts in such a situation, if the ++first progress update takes longer to arrive than the configured time ++period, the stall detection will be automically adjusted to use a longer ++time period. For example, if the first progress update comes after 10 ++minutes, but annex.stalldetection is "1MB/1m", it will be treated as eg ++"30MB/30m". ++.IP ++Configuring stall detection can make git-annex use more resources. To be ++able to cancel stalls, git-annex has to run transfers in separate ++processes (one per concurrent job). So it may need to open more ++connections to a remote than usual, or the communication with those ++processes may make it a bit slower. ++.IP ++.IP "\fBremote..annex\-stalldetection\-download\fP, \fBannex.stalldetection\-download\fP" ++Stall detection for downloads from a remote. ++.IP ++For example, if a remote is often fast, but sometimes is very slow, ++and there is another remote that is consistently medium speed ++and that contains the same data, this could be set to treat the fast ++remote as stalled when it's slow. Then a command like \fBgit-annex get\fP ++will fall back to downloading from the medium speed remote. ++.IP ++Overrides \fBremote..annex\-stalldetection\fP, \fBannex.stalldetection\fP ++.IP ++.IP "\fBremote..annex\-stalldetection\-upload\fP, \fBannex.stalldetection\-upload\fP" ++Stall detection for uploads to a remote. ++.IP ++Overrides \fBremote..annex\-stalldetection\fP, \fBannex.stalldetection\fP ++.IP ++.IP "\fBremote..annex\-checkuuid\fP" ++This only affects remotes that have their url pointing to a directory on ++the same system. git-annex normally checks the uuid of such ++remotes each time it's run, which lets it transparently deal with ++different drives being mounted to the location at different times. ++.IP ++Setting annex\-checkuuid to false will prevent it from checking the uuid ++at startup (although the uuid is still verified before making any ++changes to the remote repository). This may be useful to set to prevent ++unnecessary spin\-up or automounting of a drive. ++.IP ++.IP "\fBremote..annex\-trustlevel\fP" ++Configures a local trust level for the remote. This overrides the value ++configured by the trust and untrust commands. The value can be any of ++"trusted", "semitrusted" or "untrusted". ++.IP ++.IP "\fBremote..annex\-speculate\-present\fP" ++Set to "true" to make git-annex speculate that this remote may contain the ++content of any file, even though its normal location tracking does not ++indicate that it does. This will cause git-annex to try to get all file ++contents from the remote. Can be useful in setting up a caching remote. ++ ++.IP "\fBremote..annex\-proxy\fP" ++.IP ++Set to "true" to make the local repository able to act as a proxy to this ++remote. The remote can be a git-annex repository or a special remote. ++.IP ++After configuring this, run [[git-annex\-updateproxy](1) to store ++the new configuration in the git-annex branch. ++.IP ++.IP "\fBremote..annex\-proxied\-by\fP" ++Usually this is used internally, when git-annex sets up proxied remotes, ++and will not need to be configured. The value is the UUID of the ++git-annex repository that proxies access to this remote. ++.IP ++.IP "\fBremote..annex\-cluster\-node\fP" ++Set to the name of a cluster to make this remote be part of ++the cluster. Names of multiple clusters can be separated by ++whitespace to make a remote be part of more than one cluster. ++.IP ++After configuring this, run [[git-annex\-updatecluster](1) to store ++the new configuration in the git-annex branch. ++.IP ++.IP "\fBremote..annex\-cluster\-gateway\fP" ++Set to the UUID of a cluster that this remote serves as a gateway for. ++Multiple UUIDs can be listed, separated by whitespace. When the local ++repository is also a gateway for that cluster, it will proxy for the ++nodes of the remote gateway. ++.IP ++Usually this is set up by running git-annex\-extendcluster. ++.IP ++.IP "\fBremote..annex\-private\fP" ++When this is set to true, no information about the remote will be ++recorded in the git-annex branch. This is mostly useful for special ++remotes, and is set when using git-annex\-initremote(1) with the ++\fB\-\-private\fP option. ++.IP ++.IP "\fBremote..annex\-max\-git\-bundles\fP, \fBannex.max\-git\-bundles\fP" ++When using git\-remote\-annex to store a git repository in a special ++remote, this configures how many separate git bundle objects to store ++in the special remote before re\-uploading a single git bundle that contains ++the entire git repository. ++.IP ++The default is 100, which aims to avoid often needing to often re\-upload, ++while preventing a clone or fetch needing to download too many objects. ++Set to 0 to disable re\-uploading. ++.IP ++.IP "\fBremote..annex\-allow\-encrypted\-gitrepo\fP" ++Setting this to true allows using git\-remote\-annex to push the git ++repository to an encrypted special remote. ++.IP ++That is not allowed by default, because it is impossible to git clone ++from an encrypted special remote, since it needs encryption keys stored ++in the remote. So take care that, if you set this, you don't rely ++on the encrypted special remote being the only copy of your git repository. ++.IP ++.IP "\fBremote..annex\-bare\fP" ++Can be used to tell git-annex if a remote is a bare repository ++or not. Normally, git-annex determines this automatically. ++.IP ++.IP "\fBremote..annex\-availability\fP" ++This configuration setting is no longer used. ++.IP ++.IP "\fBremote..annex\-ssh\-options\fP" ++Options to use when using ssh to talk to this remote. ++.IP ++.IP "\fBremote..annex\-rsync\-options\fP" ++Options to use when using rsync ++to or from this remote. For example, to force IPv6, and limit ++the bandwidth to 100Kbyte/s, set it to \fB\-6 \-\-bwlimit 100\fP ++.IP ++Note that git-annex\-shell has a whitelist of allowed rsync options, ++and others will not be be passed to the remote rsync. So using some ++options may break the communication between the local and remote rsyncs. ++.IP ++.IP "\fBremote..annex\-rsync\-upload\-options\fP" ++Options to use when using rsync to upload a file to a remote. ++.IP ++These options are passed after other applicable rsync options, ++so can be used to override them. For example, to limit upload bandwidth ++to 10Kbyte/s, set \fB\-\-bwlimit 10\fP. ++.IP ++.IP "\fBremote..annex\-rsync\-download\-options\fP" ++Options to use when using rsync to download a file from a remote. ++.IP ++These options are passed after other applicable rsync options, ++so can be used to override them. ++.IP ++.IP "\fBremote..annex\-rsync\-transport\fP" ++The remote shell to use to connect to the rsync remote. Possible ++values are \fBssh\fP (the default) and \fBrsh\fP, together with their ++arguments, for instance \fBssh \-p 2222 \-c blowfish\fP; Note that the ++remote hostname should not appear there, see rsync(1) for details. ++When the transport used is \fBssh\fP, connections are automatically cached ++unless \fBannex.sshcaching\fP is unset. ++.IP ++.IP "\fBremote..annex\-bup\-split\-options\fP" ++Options to pass to bup split when storing content in this remote. ++For example, to limit the bandwidth to 100Kbyte/s, set it to \fB\-\-bwlimit 100k\fP ++(There is no corresponding option for bup join.) ++.IP ++.IP "\fBremote..annex\-gnupg\-options\fP" ++Options to pass to GnuPG when it's encrypting data. For instance, to ++use the AES cipher with a 256 bits key and disable compression, set it ++to \fB\-\-cipher\-algo AES256 \-\-compress\-algo none\fP. (These options take ++precedence over the default GnuPG configuration, which is otherwise ++used.) ++.IP ++.IP "\fBremote..annex\-gnupg\-decrypt\-options\fP" ++Options to pass to GnuPG when it's decrypting data. (These options take ++precedence over the default GnuPG configuration, which is otherwise ++used.) ++.IP ++.IP "\fBremote..annex\-shared\-sop\-command\fP" ++Use this command, which is an implementation of the Stateless OpenPGP ++command line interface, rather than GnuPG for encrypting and decrypting ++data. This is only used when a special remote is configured with ++encryption=shared. ++.IP ++For example, to use Sequoia PGP's sqop command, set this to "sqop". ++.IP ++.IP "\fBremote..annex\-shared\-sop\-profile\fP" ++When encrypting with a Stateless OpenPGP command, this can be used ++to specify the profile to use, such as "rfc4880". ++.IP ++For a list of available profiles, run eg "sqop list\-profiles encrypt" ++.IP ++sqop list\-profiles encrypt ++.IP ++.IP "\fBannex.ssh\-options\fP, \fBannex.rsync\-options\fP," ++\fBannex.rsync\-upload\-options\fP, \fBannex.rsync\-download\-options\fP, ++\fBannex.bup\-split\-options\fP, \fBannex.gnupg\-options\fP, ++\fBannex.gnupg\-decrypt\-options\fP, ++\fBannex.shared\-sop\-command\fP, \fBannex.shared\-sop\-profile\fP ++.IP ++Default options to use if a remote does not have more specific options ++as described above. ++.IP ++.IP "\fBremote..annex\-rsyncurl\fP" ++Used by rsync special remotes, this configures ++the location of the rsync repository to use. Normally this is automatically ++set up by \fBgit annex initremote\fP, but you can change it if needed. ++.IP ++.IP "\fBremote..annex\-buprepo\fP" ++Used by bup special remotes, this configures ++the location of the bup repository to use. Normally this is automatically ++set up by \fBgit annex initremote\fP, but you can change it if needed. ++.IP ++.IP "\fBremote..annex\-borgrepo\fP" ++Used by borg special remotes, this configures ++the location of the borg repository to use. Normally this is automatically ++set up by \fBgit annex initremote\fP, but you can change it if needed. ++.IP ++.IP "\fBremote..annex\-compute\fP" ++Used to identify compute special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-ddarrepo\fP" ++Used by ddar special remotes, this configures ++the location of the ddar repository to use. Normally this is automatically ++set up by \fBgit annex initremote\fP, but you can change it if needed. ++.IP ++.IP "\fBremote..annex\-directory\fP" ++Used by directory special remotes, this configures ++the location of the directory where annexed files are stored for this ++remote. Normally this is automatically set up by \fBgit annex initremote\fP, ++but you can change it if needed. ++.IP ++.IP "\fBremote..annex\-adb\fP" ++Used to identify remotes on Android devices accessed via adb. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-androiddirectory\fP" ++Used by adb special remotes, this is the directory on the Android ++device where files are stored for this remote. Normally this is ++automatically set up by \fBgit annex initremote\fP, but you can change ++it if needed. ++.IP ++.IP "\fBremote..annex\-androidserial\fP" ++Used by adb special remotes, this is the serial number of the Android ++device used by the remote. Normally this is automatically set up by ++\fBgit annex initremote\fP, but you can change it if needed, eg when ++upgrading to a new Android device. ++.IP ++.IP "\fBremote..annex\-s3\fP" ++Used to identify Amazon S3 special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-glacier\fP" ++Used to identify Amazon Glacier special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-rclone\fP" ++Used to identify rclone special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-web\fP" ++Used to identify web special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-webdav\fP" ++Used to identify webdav special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-tahoe\fP" ++Used to identify tahoe special remotes. ++Points to the configuration directory for tahoe. ++.IP ++.IP "\fBremote..annex\-gcrypt\fP" ++Used to identify gcrypt special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++It is set to "true" if this is a gcrypt remote. ++If the gcrypt remote is accessible over ssh and has git-annex\-shell ++available to manage it, it's set to "shell". ++.IP ++.IP "\fBremote..annex\-git\-lfs\fP" ++Used to identify git\-lfs special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++It is set to "true" if this is a git\-lfs remote. ++.IP ++.IP "\fBremote..annex\-httpalso\fP" ++Used to identify httpalso special remotes. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-mask\fP" ++Used by mask special remotes, this is set to the name of the remote ++that is masked. If this is set to "true", then any remote with the ++right UUID will be used. ++Normally this is automatically set up by \fBgit annex initremote\fP. ++.IP ++.IP "\fBremote..annex\-externaltype\fP" ++Used by external special remotes to record the type of the remote. ++.IP ++Eg, if this is set to "foo", git-annex will run a "git-annex\-remote\-foo" ++program to communicate with the external special remote. ++.IP ++If this is set to "readonly", then git-annex will not run any external ++special remote program, but will try to access things stored in the ++remote using http. That only works for some external special remotes, ++so consult the documentation of the one you are using. ++.IP ++.IP "\fBremote..annex\-hooktype\fP" ++Used by hook special remotes to record the type of the remote. ++.IP ++.IP "\fBannex.web\-options\fP, \fBremote..annex\-web\-options\fP" ++Options to pass to curl when git-annex uses it to download urls ++(rather than the default built\-in url downloader). ++.IP ++For example, to force IPv4 only, set it to "\-4". ++.IP ++Setting this makes git-annex use curl, but only ++when annex.security.allowed\-ip\-addresses is configured in a ++specific way. See its documentation. ++.IP ++Setting this prevents git-annex from using git\-credential ++for prompting for http passwords. Instead, you can include "\-\-netrc" ++to make curl use your ~/.netrc file and record the passwords there. ++.IP ++.IP "\fBannex.youtube\-dl\-options\fP" ++Options to pass to yt\-dlp (or deprecated youtube\-dl) when using it to ++find the url to download for a video. ++.IP ++Some options may break git-annex's integration with yt\-dlp. For ++example, the \-\-output option could cause it to store files somewhere ++git-annex won't find them. Avoid setting here or in the yt\-dlp config ++file any options that cause it to download more than one file, ++or to store the file anywhere other than the current working directory. ++.IP ++.IP "\fBannex.youtube\-dl\-command\fP" ++Default is to use "yt\-dlp" or if that is not available in the PATH, ++to use "youtube\-dl". ++.IP ++.IP "\fBannex.aria\-torrent\-options\fP" ++Options to pass to aria2c when using it to download a torrent. ++.IP ++.IP "\fBannex.http\-headers\fP" ++HTTP headers to send when downloading from the web. Multiple lines of ++this option can be set, one per header. ++.IP ++.IP "\fBannex.http\-headers\-command\fP" ++If set, the command is run and each line of its output is used as a HTTP ++header. This overrides annex.http\-headers. ++.IP ++Alternatively, a hook script can be installed in ++\fB.git/hooks/http\-headers\-annex\fP ++.IP ++.IP "\fBannex.security.allowed\-url\-schemes\fP" ++List of URL schemes that git-annex is allowed to download content from. ++The default is "http https ftp". ++.IP ++Think very carefully before changing this; there are security ++implications. For example, if it's changed to allow "file" URLs, then ++anyone who can get a commit into your git-annex repository could ++\fBgit-annex addurl\fP a pointer to a private file located outside that ++repository, possibly causing it to be copied into your repository ++and transferred on to other remotes, exposing its content. ++.IP ++Any url schemes supported by curl can be listed here, but you will ++also need to configure annex.security.allowed\-ip\-addresses to allow ++using curl. ++.IP ++Some special remotes support their own domain\-specific URL ++schemes; those are not affected by this configuration setting. ++.IP ++.IP "\fBannex.security.allowed\-ip\-addresses\fP" ++By default, git-annex only makes connections to public IP addresses; ++it will refuse to use HTTP and other servers on localhost or on a ++private network. ++.IP ++This setting can override that behavior, allowing access to particular ++IP addresses that would normally be blocked. For example "127.0.0.1 ::1" ++allows access to localhost (both IPV4 and IPV6). ++To allow access to all IP addresses, use "all" ++.IP ++Think very carefully before changing this; there are security ++implications. Anyone who can get a commit into your git-annex repository ++could \fBgit annex addurl\fP an url on a private server, possibly ++causing it to be downloaded into your repository and transferred to ++other remotes, exposing its content. ++.IP ++Note that, since the interfaces of curl and yt\-dlp do not allow ++these IP address restrictions to be enforced, curl and yt\-dlp will ++never be used unless annex.security.allowed\-ip\-addresses=all. ++.IP ++To allow accessing local or private IP addresses on only specific ports, ++use the syntax "[addr]:port". For example, ++"[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows ++localhost on the http ports only. ++.IP ++.IP "\fBannex.security.allowed\-http\-addresses\fP" ++Old name for annex.security.allowed\-ip\-addresses. ++If set, this is treated the same as having ++annex.security.allowed\-ip\-addresses set. ++.IP ++.IP "\fBannex.security.allow\-unverified\-downloads\fP" ++For security reasons, git-annex refuses to download content from ++most special remotes when it cannot check a hash to verify ++that the correct content was downloaded. This particularly impacts ++downloading the content of URL or WORM keys, which lack hashes. ++.IP ++The best way to avoid problems due to this is to migrate files ++away from such keys, before their content reaches a special remote. ++See git-annex\-migrate(1). ++.IP ++When the content is only available from a special remote, you can ++use this configuration to force git-annex to download it. ++But you do so at your own risk, and it's very important you read and ++understand the information below first! ++.IP ++Downloading unverified content from encrypted special remotes is ++prevented, because the special remote could send some other encrypted ++content than what you expect, causing git-annex to decrypt data that you ++never checked into git-annex, and risking exposing the decrypted ++data to any non\-encrypted remotes you send content to. ++.IP ++Downloading unverified content from (non\-encrypted) ++external special remotes is prevented, because they could follow ++http redirects to web servers on localhost or on a private network, ++or in some cases to a file:/// url. ++.IP ++If you decide to bypass this security check, the best thing to do is ++to only set it temporarily while running the command that gets the file. ++The value to set the config to is "ACKTHPPT". ++For example: ++.IP ++ git \-c annex.security.allow\-unverified\-downloads=ACKTHPPT annex get myfile ++.IP ++It would be a good idea to check that it downloaded the file you expected, ++too. ++.IP ++.IP "\fBremote..annex\-security\-allow\-unverified\-downloads\fP" ++Per\-remote configuration of annex.security.allow\-unverified\-downloads. ++.IP ++.IP "\fBannex.security.allowed\-compute\-programs\fP" ++This is a space separated list of compute programs eg ++"git-annex\-compute\-foo git-annex\-compute\-bar". Listing a compute ++program here allows compute special remotes that use that program to be ++enabled by \fBgit-annex enableremote\fP or autoenabled. ++.IP ++.SH CONFIGURATION OF ASSISTANT ++.IP "\fBannex.delayadd\fP" ++.IP ++Makes the watch and assistant commands delay for the specified number of ++seconds before adding a newly created file to the annex. Normally this ++is not needed, because they already wait for all writers of the file ++to close it. ++.IP ++Note that this only delays adding files created while the daemon is ++running. Changes made when it is not running will be added immediately ++the next time it is started up. ++.IP ++.IP "\fBannex.expireunused\fP" ++Controls what the assistant does about unused file contents ++that are stored in the repository. ++.IP ++The default is \fBfalse\fP, which causes ++all old and unused file contents to be retained, unless the assistant ++is able to move them to some other repository (such as a backup repository). ++.IP ++Can be set to a time specification, like "7d" or "1m", and then ++file contents that have been known to be unused for a week or a ++month will be deleted. ++.IP ++.IP "\fBannex.fscknudge\fP" ++When set to false, prevents the webapp from reminding you when using ++repositories that lack consistency checks. ++.IP ++.IP "\fBannex.autoupgrade\fP" ++When set to ask (the default), the webapp will check for new versions ++and prompt if they should be upgraded to. When set to true, automatically ++upgrades without prompting (on some supported platforms). When set to ++false, disables any upgrade checking. ++.IP ++Note that upgrade checking is only done when git-annex is installed ++from one of the prebuilt images from its website. This does not ++bypass e.g., a Linux distribution's own upgrade handling code. ++.IP ++This setting also controls whether to restart the git-annex assistant ++when the git-annex binary is detected to have changed. That is useful ++no matter how you installed git-annex. ++.IP ++.IP "\fBannex.autocommit\fP" ++Set to false to prevent the \fBgit-annex assistant\fP, \fBgit-annex assist\fP, ++and \fBgit-annex sync\fP from automatically committing changes to files in ++the repository. ++.IP ++To configure the behavior in all clones of the repository, ++this can be set in git-annex\-config(1). ++.IP ++.IP "\fBannex.startupscan\fP" ++Set to false to prevent the git-annex assistant from scanning the ++repository for new and changed files on startup. This will prevent it ++from noticing changes that were made while it was not running, but can be ++a useful performance tweak for a large repository. ++.IP ++.IP "\fBannex.listen\fP" ++Configures which IP address the webapp listens on. ++The default is localhost. Can be either an IP address, ++or a hostname that resolves to the desired address. ++.IP ++.IP "\fBannex.port\fP" ++Configures which port address the webapp listens on. ++The default is to pick an unused port. ++.IP ++.SH CONFIGURATION VIA .gitattributes ++The key\-value backend used when adding a new file to the annex can be ++configured on a per\-file\-type basis via \fB.gitattributes\fP files. In the file, ++the \fBannex.backend\fP attribute can be set to the name of the backend to ++use. (See git-annex\-backends(1) for information about ++available backends.) ++For example, this here's how to use the WORM backend by default, ++but the SHA256E backend for ogg files: ++.PP ++ * annex.backend=WORM ++ *.ogg annex.backend=SHA256E ++.PP ++There is a annex.largefiles attribute, which is used to configure which ++files are large enough to be added to the annex. Since attributes cannot ++contain spaces, it is difficult to use for more complex annex.largefiles ++settings. Setting annex.largefiles in git-annex\-config(1) is an easier ++way to configure it across all clones of the repository. ++See git-annex\-matching\-expression(1) for details on the syntax. ++.PP ++The numcopies and mincopies settings can also be configured on a ++per\-file\-type basis via the \fBannex.numcopies\fP and \fBannex.mincopies\fP ++attributes in \fB.gitattributes\fP files. This overrides other settings. ++For example, this makes two copies be needed for wav files and 3 copies ++for flac files: ++.PP ++ *.wav annex.numcopies=2 ++ *.flac annex.numcopies=3 ++.PP ++These settings are honored by git-annex whenever it's operating on a ++matching file. However, when using \-\-all, \-\-unused, or \-\-key to specify ++keys to operate on, git-annex is operating on keys and not files, so will ++not honor the settings from .gitattributes. For this reason, the git annex ++numcopies\fB and \fPgit annex mincopies commands are useful to configure a ++global default. ++.PP ++Also note that when using views, only the toplevel .gitattributes file is ++preserved in the view, so other settings in other files won't have any ++effect. ++.PP ++.SH EXIT STATUS ++git-annex itself will exit 0 on success and 1 on failure, unless ++the \fB\-\-size\-limit\fP or \fB\-\-time\-limit\fP option is hit, in ++which case it exits 101. ++.PP ++A few git-annex subcommands have other exit statuses used to indicate ++specific problems, which are documented on their individual man pages. ++.PP ++.SH ENVIRONMENT ++These environment variables are used by git-annex when set: ++.PP ++.IP "\fBGIT_WORK_TREE\fP, \fBGIT_DIR\fP" ++Handled the same as they are by git, see git(1) ++.IP ++.IP "\fBGIT_SSH\fP, \fBGIT_SSH_COMMAND\fP" ++Handled similarly to the same as described in git(1). ++The one difference is that git-annex will sometimes pass an additional ++"\-n" parameter to these, as the first parameter, to prevent ssh from ++reading from stdin. Since that can break existing uses of these ++environment variables that don't expect the extra parameter, you will ++need to set \fBGIT_ANNEX_USE_GIT_SSH=1\fP to make git-annex support ++these. ++.IP ++Note that setting either of these environment variables prevents ++git-annex from automatically enabling ssh connection caching ++(see \fBannex.sshcaching\fP), so it will slow down some operations with ++remotes over ssh. It's up to you to enable ssh connection caching ++if you need it; see ssh's documentation. ++.IP ++Also, \fBannex.ssh\-options\fP and \fBremote..annex\-ssh\-options\fP ++won't have any effect when these envionment variables are set. ++.IP ++Usually it's better to configure any desired options through your ++~/.ssh/config file, or by setting \fBannex.ssh\-options\fP. ++.IP ++.IP "\fBGIT_ANNEX_VECTOR_CLOCK\fP" ++Normally git-annex timestamps lines in the log files committed to the ++git-annex branch. Setting this environment variable to a number ++will make git-annex use that (or a larger number) ++rather than the current number of seconds since the UNIX epoch. ++Note that decimal seconds are supported. ++.IP ++This is only provided for advanced users who either have a better way to ++tell which commit is current than the local clock, or who need to avoid ++embedding timestamps for policy reasons. ++.IP ++.IP "Some special remotes use additional environment variables" ++for authentication etc. For example, \fBAWS_ACCESS_KEY_ID\fP ++and \fBGIT_ANNEX_P2P_AUTHTOKEN\fP. See special remote documentation. ++.IP ++.SH FILES ++These files are used by git-annex: ++.PP ++\fB.git/annex/objects/\fP in your git repository contains the annexed file ++contents that are currently available. Annexed files in your git ++repository symlink to that content. ++.PP ++\fB.git/annex/\fP in your git repository contains other run\-time information ++used by git-annex. ++.PP ++\fB~/.config/git-annex/autostart\fP is a list of git repositories ++to start the git-annex assistant in. ++.PP ++.SH SEE ALSO ++More git-annex documentation is available on its web site, ++ ++.PP ++If git-annex is installed from a package, a copy of its documentation ++should be included, in, for example, \fB/usr/share/doc/git-annex/\fP. ++.PP ++.IP "git-annex\-shell(1)" ++.IP "git\-remote\-annex(1)" ++.IP "git\-remote\-tor\-annex(1)" ++.SH AUTHOR ++Joey Hess ++.PP ++ ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-remote-annex.1 +@@ -0,0 +1,105 @@ ++.TH git-remote-annex 1 ++.SH NAME ++git\-remote\-annex \- remote helper program to store a git repository in a git-annex special remote ++.PP ++.SH SYNOPSIS ++git fetch annex::uuid?param=value¶m=value... ++.PP ++.SH DESCRIPTION ++This is a git remote helper program that allows git to clone, ++pull and push from a git repository that is stored in a git-annex ++special remote with an URL that starts with "annex::" ++.PP ++The special remote needs to have a \fBremote..url\fP ++configured to use this. That is set up automatically when git ++cloning from a special remote. ++.PP ++To make git-annex\-initremote(1) and git-annex\-enableremote(1) ++configure the url, pass them the \fB\-\-with\-url\fP option. ++.PP ++Or, to configure an existing special remote with a shorthand URL, run: ++.PP ++git config remote.name.url annex:: ++.PP ++Once the URL is configured, you can use \fBgit pull\fP, \fBgit push\fP, etc ++with the special remote much like with any other git remote. ++But see CONFLICTING PUSHES below for some situations where it behaves ++slightly differently. ++.PP ++.SH URL FORMAT ++This uses an URL that starts with "annex::". There are three forms of such ++URLs: ++.PP ++.IP "Complete URL" ++This contains the UUID and all configuration parameters ++of the special remote that were passed when using ++\fBgit-annex initremote\fP. ++.IP ++For example, to clone from a directory special remote: ++.IP ++git clone annex::358ff77e\-0bc3\-11ef\-bc49\-872e6695c0e3?type=directory&encryption=none&directory=/mnt/foo/ ++.IP ++.IP "Shorthand URL" ++This makes it easy to configure an existing special remote with an URL ++without having to come up with the complete URL. ++.IP ++annex:: ++.IP ++When using this shorthand URL, the full URL will be displayed each time you ++git pull or push, when it's possible for git-annex to determine it. ++(Although in some cases, like the directory special remote, some ++parameters may be left off of the displayed URL.) ++.IP ++.IP "Web URL" ++This URL points at a file on the web, which contains the complete annex:: ++URL. ++.IP ++annex::https://example.com/foo\-repo ++.IP ++Not all special remotes can be accessed by such an URL, ++for security reasons. Currently, this is limited to httpalso special ++remotes. ++.IP ++.SH CONFLICTING PUSHES ++Like any git repository, a git repository stored on a special remote can ++have conflicting things pushed to it from different places. This mostly ++works the same as any other git repository, eg a push that overwrites other ++work will be prevented unless forced. ++.PP ++However, it is possible, when conflicting pushes are being done at the same ++time, for one of the pushes to be overwritten by the other one. In this ++situation, the overwritten push will appear to have succeeded, but pulling ++later will show the true situation. ++.PP ++.SH REPOSITORY FORMAT ++The git repository is stored in the special remote using special annex objects ++with names starting with "GITMANIFEST" and "GITBUNDLE". For details, see: ++ ++.PP ++Pushes to a special remote are usually done incrementally. However, ++sometimes the whole git repository is re\-uploaded. That is done when force ++pushing a ref, or deleting a ref from the remote. It's also done when too ++many git bundles accumulate in the special remote, as configured by the ++\fBremote..annex\-max\-git\-bundles\fP git config. ++.PP ++Note that a re\-upload of the repository does not delete old GITBUNDLE ++objects from it. This means that refs pushed to the special ++remote can still be accessed even after deleting or overwriting them. ++.PP ++A push that deletes every ref from the special remote will delete all ++the accumulated GITBUNDLE objects. But of course, making such a push ++means that someone who clones from the special remote at that point in time ++will see an empty remote. ++.PP ++.SH SEE ALSO ++gitremote\-helpers(1) ++.PP ++git-annex(1) ++.PP ++git-annex\-initremote(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ +--- /dev/null ++++ git-annex-10.20250416/man/git-remote-tor-annex.1 +@@ -0,0 +1,33 @@ ++.TH git-remote-tor-annex 1 ++.SH NAME ++git\-remote\-tor\-annex \- remote helper program to talk to git-annex over tor ++.PP ++.SH SYNOPSIS ++git fetch tor\-annex::address.onion:port ++.PP ++git remote add tor tor\-annex::address.onion:port ++.PP ++.SH DESCRIPTION ++This is a git remote helper program that allows git to pull and push ++over tor(1), communicating with a tor hidden service. ++.PP ++The tor hidden service probably requires an authtoken to use it. ++The authtoken can be provided in the environment variable ++\fBGIT_ANNEX_P2P_AUTHTOKEN\fP. Or, if there is a file in ++\fB.git/annex/creds/\fP matching the onion address of the hidden ++service, its first line is used as the authtoken. ++.PP ++.SH SEE ALSO ++gitremote\-helpers(1) ++.PP ++git-annex(1) ++.PP ++git-annex\-enable\-tor(1) ++.PP ++git-annex\-remotedaemon(1) ++.PP ++.SH AUTHOR ++Joey Hess ++.PP ++.PP ++ diff --git a/debian/rules b/debian/rules index b0a76a0602..8bc2294408 100755 --- a/debian/rules +++ b/debian/rules @@ -17,7 +17,7 @@ ifneq (,$(filter armel,$(DEB_HOST_ARCH))) export BUILDEROPTIONS:=$(BUILDEROPTIONS) --ghc-option=-O1 endif ifneq (,$(filter armhf,$(DEB_HOST_ARCH))) -export BUILDEROPTIONS:=$(BUILDEROPTIONS) --ghc-option=-O1 +export BUILDEROPTIONS:=$(BUILDEROPTIONS) --ghc-option=-O0 endif STANDALONE_BUILD=$(shell grep -qe '^Package: git-annex-standalone' debian/control \ @@ -71,3 +71,7 @@ override_dh_makeshlibs: dh_makeshlibs --noscripts endif + +override_dh_auto_test: + echo testsuite disabled + diff --git a/man/git-annex-add.1 b/man/git-annex-add.1 new file mode 100644 index 0000000000..cb88f2bf40 --- /dev/null +++ b/man/git-annex-add.1 @@ -0,0 +1,119 @@ +.TH git-annex-add 1 +.SH NAME +git-annex-add \- adds files to the git annex +.PP +.SH SYNOPSIS +git annex add \fB[path ...]\fP +.PP +.SH DESCRIPTION +Adds the specified files to the annex. If a directory is specified, +acts on all files inside the directory and its subdirectories. +If no path is specified, adds files from the current directory and below. +.PP +Files that are already checked into git and are unmodified, or that +git has been configured to ignore will be silently skipped. +.PP +If annex.largefiles is configured (in git config, gitattributes, or +git-annex config), and does not match a file, \fBgit annex add\fP will behave +the same as \fBgit add\fP and add the non\-large file directly to the git +repository, instead of to the annex. (By default dotfiles and the contents +of dotdirs) are assumed to not be large, and are added directly to git, but +annex.dotfiles can be configured to annex those too.) See the git-annex +manpage for documentation of these and other configuration settings. +.PP +By default, large files are added to the annex in locked form, which +prevents further modification of their content until +unlocked by git-annex\-unlock(1). (This is not the case however +when a repository is in a filesystem not supporting symlinks.) +The annex.addunlocked git config (and git-annex config) can be used to +change this behavior. +.PP +This command can also be used to add symbolic links, both symlinks to +annexed content, and other symlinks. +.PP +.SH EXAMPLES + # git annex add foo bar + add foo ok + add bar ok + # git commit \-m added +.PP +.SH OPTIONS +.IP "\fB\-\-no\-check\-gitignore\fP" +.IP +Add gitignored files. +.IP +.IP "\fB\-\-force\-large\fP" +Treat all files as large files, ignoring annex.largefiles and annex.dotfiles +configuration, and add to the annex. +.IP +.IP "\fB\-\-force\-small\fP" +Treat all files as small files, ignoring annex.largefiles and annex.dotfiles +and annex.addsmallfiles configuration, and add to git. +.IP +.IP "\fB\-\-backend\fP" +Specifies which key\-value backend to use. +.IP +.IP "file matching options" +Many of the git-annex\-matching\-options(1) +can be used to specify files to add. +.IP +For example: \fB\-\-largerthan=1GB\fP +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Adds multiple files in parallel. This may be faster. +For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-update\fP \fB\-u\fP" +Like \fBgit add \-\-update\fP, this does not add new files, but any updates +to tracked files will be added to the index. +.IP +.IP "\fB\-\-dry\-run\fP" +Output what would be done for each file, but avoid making any changes. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which a file to add is read in a line from stdin, +the file is added, and repeat. +.IP +Note that if a file is skipped (due to not existing, being gitignored, +already being in git, or doesn't meet the matching options), +an empty line will be output instead of the normal output produced +when adding a file. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-unlock(1) +.PP +git-annex\-lock(1) +.PP +git-annex\-undo(1) +.PP +git-annex\-import(1) +.PP +git-annex\-unannex(1) +.PP +git-annex\-reinject(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-addcomputed.1 b/man/git-annex-addcomputed.1 new file mode 100644 index 0000000000..e2ec72a0f5 --- /dev/null +++ b/man/git-annex-addcomputed.1 @@ -0,0 +1,100 @@ +.TH git-annex-addcomputed 1 +.SH NAME +git-annex-addcomputed \- adds computed files to the repository +.PP +.SH SYNOPSIS +git annex addcomputed \fB\-\-to=remote \-\- ...\fP +.PP +.SH DESCRIPTION +Adds files to the annex that are computed from input files in the +repository, using a compute special remote. +.PP +Once a file has been added to a compute remote, commands +like \fBgit-annex get\fP will use it to compute the content of the file. +.PP +The syntax of this command after the \fB\-\-\fP is up to the program that +the compute special remote is set up to run to perform the comuptation. +.PP +To see the program's usage, you can run: +.PP +git-annex addcomputed \-\-to=foo +.PP +Generally you will provide an input file (or files), and often also an +output filename, and additional parameters to control the computation. +.PP +There can be more than one input file that are combined to compute an +output file. And multiple output files can be computed at the same time. +.PP +Some examples of how this might look: +.PP +git-annex addcomputed \-\-to=x \-\- convert file.raw file.jpeg passes=10 +git-annex addcomputed \-\-to=y \-\- compress foo \-\-level=9 +git-annex addcomputed \-\-to=z \-\- clip foo 2:01\-3:00 combine with bar to baz +.PP +Note that parameters that were passed to \fBgit-annex initremote\fP +when setting up the compute special remote will be appended to the end of +the parameters provided to \fBgit-annex addcomputed\fP. +.PP +.SH OPTIONS +.IP "\fB\-\-to=remote\fP" +.IP +Specify which remote will compute the files. +.IP +This must be a compute remote. For example, one can be +initialized with: +.IP +git-annex initremote photoconv type=compute \\ +program=git-annex\-compute\-photoconv +.IP +For details about compute remotes, and a list of some +of the programs that are available, see + +.IP +.IP "\fB\-\-fast\fP" +Adds computed files to the repository, without doing any work yet to +compute their content. +.IP +This implies \fB\-\-unreproducible\fP, because even if the compute remote +produces reproducible output, it's not available. +.IP +.IP "\fB\-\-unreproducible\fP, \fB\-u\fP" +Indicate that the computation is not expected to be fully reproducible. +It can vary, in ways that produce files that equivilant enough to +be interchangeable, but are not necessarily identical. +.IP +This is the default unless the compute remote indicates that it produces +reproducible output. +.IP +.IP "\fB\-\-reproducible\fP, \fB\-r\fP" +Indicate that the computation is expected to be fully reproducible. +.IP +This is the default when the compute remote indicates that it produces +reproducible output (except when using \fB\-\-fast\fP). +.IP +If a computation turns out not to be fully reproducible, then getting +a computed file from the compute remote will later fail with a +checksum verification error. One thing that can be done then is to use +\fBgit-annex recompute \-\-original \-\-unreproducible\fP. +.IP +.IP "\fB\-\-backend\fP" +Specifies which key\-value backend to use. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-recompute(1) +.PP +git-annex\-findcomputed(1) +.PP +git-annex\-initremote(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-addunused.1 b/man/git-annex-addunused.1 new file mode 100644 index 0000000000..6541b87590 --- /dev/null +++ b/man/git-annex-addunused.1 @@ -0,0 +1,36 @@ +.TH git-annex-addunused 1 +.SH NAME +git-annex-addunused \- add back unused files +.PP +.SH SYNOPSIS +git annex addunused \fB[number|range ...]\fP +.PP +.SH DESCRIPTION +Adds back files for the content corresponding to the numbers or ranges, +as listed by the last \fBgit annex unused\fP. +.PP +The files will have names starting with "unused." +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "The git-annex\-common\-options(1) can also be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-add(1) +.PP +git-annex\-unused(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-addurl.1 b/man/git-annex-addurl.1 new file mode 100644 index 0000000000..d640a797f2 --- /dev/null +++ b/man/git-annex-addurl.1 @@ -0,0 +1,168 @@ +.TH git-annex-addurl 1 +.SH NAME +git-annex-addurl \- add urls to annex +.PP +.SH SYNOPSIS +git annex addurl \fB[url ...]\fP +.PP +.SH DESCRIPTION +Downloads each url to its own file, which is added to the annex. +.PP +When \fByt\-dlp\fP is installed, it can be used to check for a video +embedded in a web page at the url, and that is added to the annex instead. +(However, this is disabled by default as it can be a security risk. +See the documentation of annex.security.allowed\-ip\-addresses +in git-annex(1) for details.) +.PP +Special remotes can add other special handling of particular urls. For +example, the bittorrent special remotes makes urls to torrent files +(including magnet links) download the content of the torrent, +using \fBaria2c\fP. +.PP +Normally the filename is based on the full url, so will look like +"www.example.com_dir_subdir_bigfile". In some cases, addurl is able to +come up with a better filename based on other information. Options can also +be used to get better filenames. +.PP +.SH OPTIONS +.IP "\fB\-\-fast\fP" +.IP +Avoid immediately downloading the url. The url is still checked +(via HEAD) to verify that it exists, and to get its size if possible. +.IP +.IP "\fB\-\-relaxed\fP" +Don't immediately download the url, and avoid storing the size of the +url's content. This makes git-annex accept whatever content is there +at a future point. +.IP +This is the fastest option, but it still has to access the network +to check if the url contains embedded media. When adding large numbers +of urls, using \fB\-\-relaxed \-\-raw\fP is much faster. +.IP +.IP "\fB\-\-verifiable\fP \fB\-V\fP" +This can be used with the \fB\-\-fast\fP or \fB\-\-relaxed\fP option. It improves +the safety of the resulting annexed file, by letting its content be +verified with a checksum when it is transferred between git-annex +repositories, as well as by things like \fBgit-annex fsck\fP. +.IP +When used with \-\-relaxed, content from the web special remote will +always be accepted, even if it has changed, and the checksum recorded +for later verification. +.IP +When used with \-\-fast, the checksum is recorded the first time the +content is downloaded from the web special remote. Once a checksum has +been recorded, subsequent downloads from the web special remote +must have the same checksum. +.IP +When addurl was used without this option before, the file it added +can be converted to be verifiable by migrating it to the VURL backend. +For example: \fBgit-annex migrate foo \-\-backend=VURL\fP +.IP +.IP "\fB\-\-raw\fP" +Prevent special handling of urls by yt\-dlp, and by bittorrent +and other special remotes. This will for example, make addurl +download the .torrent file and not the contents it points to. +.IP +.IP "\fB\-\-no\-raw\fP" +Require content pointed to by the url to be downloaded using yt\-dlp +or a special remote, rather than the raw content of the url. if that +cannot be done, the add will fail. +.IP +.IP "\fB\-\-raw\-except=remote\fP" +Prevent special handling of urls by all special remotes except +for the specified one. To allow special handling only +by yt\-dlp, use \fB\-\-raw\-except=web\fP. +.IP +.IP "\fB\-\-file=name\fP" +Use with a filename that does not yet exist to add a new file +with the specified name and the content downloaded from the url. +.IP +If the file already exists, addurl will record that it can be downloaded +from the specified url(s). +.IP +.IP "\fB\-\-preserve\-filename\fP" +When the web server (or torrent, etc) provides a filename, use it as\-is, +avoiding sanitizing unusual characters, or truncating it to length, or any +other modifications. +.IP +git-annex will still check the filename for safety, and if the filename +has a security problem such as path traversal or a control character, +it will refuse to add it. +.IP +.IP "\fB\-\-pathdepth=N\fP" +Rather than basing the filename on the whole url, this causes a path to +be constructed, starting at the specified depth within the path of the +url. +.IP +For example, adding the url http://www.example.com/dir/subdir/bigfile +with \fB\-\-pathdepth=1\fP will use "dir/subdir/bigfile", +while \fB\-\-pathdepth=3\fP will use "bigfile". +.IP +It can also be negative; \fB\-\-pathdepth=\-2\fP will use the last +two parts of the url. +.IP +.IP "\fB\-\-prefix=foo\fP \fB\-\-suffix=bar\fP" +Use to adjust the filenames that are created by addurl. For example, +\fB\-\-suffix=.mp3\fP can be used to add an extension to the file. +.IP +.IP "\fB\-\-no\-check\-gitignore\fP" +By default, gitignores are honored and it will refuse to download an +url to a file that would be ignored. This makes such files be added +despite any ignores. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel downloads when multiple urls are being added. +For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which lines containing urls to add are read from +stdin. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-with\-files\fP" +When batch mode is enabled, makes it parse lines of the form: "$url $file" +.IP +That adds the specified url to the specified file, downloading its +content if the file does not yet exist; the same as +\fBgit annex addurl $url \-\-file $file\fP +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-backend\fP" +Specifies which key\-value backend to use. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH CAVEATS +If annex.largefiles is configured, and does not match a file, git annex +addurl will add the non\-large file directly to the git repository, +instead of to the annex. However, this is not done when \-\-fast or \-\-relaxed +is used. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-rmurl(1) +.PP +git-annex\-registerurl(1) +.PP +git-annex\-importfeed(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-adjust.1 b/man/git-annex-adjust.1 new file mode 100644 index 0000000000..f4a6016740 --- /dev/null +++ b/man/git-annex-adjust.1 @@ -0,0 +1,128 @@ +.TH git-annex-adjust 1 +.SH NAME +git-annex-adjust \- enter an adjusted branch +.PP +.SH SYNOPSIS +git annex adjust \fB\-\-unlock|\-\-lock|\-\-fix|\-\-hide\-missing [\-\-unlock|\-\-lock|\-\-fix]|\-\-unlock\-present\fP +.PP +.SH DESCRIPTION +Enters an adjusted form of the current branch. The annexed files will +be treated differently. For example with \-\-unlock all annexed files will +be unlocked. +.PP +The adjusted branch will have a name like "adjusted/master(unlocked)". +Since it's a regular git branch, you can use \fBgit checkout\fP to switch +back to the original branch at any time. +.PP +This allows changing how annexed files are handled, without making changes +to a public branch with commands like \fBgit-annex unlock\fP. +.PP +While in the adjusted branch, you can use git-annex and git commands as +usual. Any commits that you make will initially only be made to the +adjusted branch. +.PP +To propagate commits from the adjusted branch back to the original branch, +and to other repositories, as well as to merge in changes from other +repositories, run \fBgit annex sync\fP. This will propagate changes that you've +made such as adding/deleting files, but will not propagate the adjustments +made by this command. +.PP +When in an adjusted branch, using \fBgit merge otherbranch\fP is often not +ideal, because merging a non\-adjusted branch may lead to unnecessary +merge conflicts, or add files in non\-adjusted form. To avoid those +problems, use \fBgit annex merge otherbranch\fP. +.PP +Re\-running this command with the same options +while inside the adjusted branch will update the adjusted branch +as necessary (eg for \fB\-\-hide\-missing\fP and \fB\-\-unlock\-present\fP), +and will also propagate commits back to the original branch. +.PP +.SH OPTIONS +.IP "\fB\-\-unlock\fP" +.IP +Unlock all annexed files in the adjusted branch. This allows +annexed files to be modified. +.IP +Normally, unlocking a file requires a copy to be made of its content, +so that its original content is preserved, while the copy can be modified. +To use less space, annex.thin can be set to true before running this +command; this makes a hard link to the content be made instead of a copy. +(When supported by the file system.) While this can save considerable +disk space, any modification made to a file will cause the old version of the +file to be lost from the local repository. So, enable annex.thin with care. +.IP +When in an adjusted unlocked branch, \fBgit annex add\fP will add files +unlocked instead of the default behavior of adding them locked. +.IP +.IP "\fB\-\-lock\fP" +Lock all annexed files in the adjusted branch. This may be preferred +by those who like seeing broken symlinks when the content of an +annexed file is not present. +.IP +When in an adjusted locked branch, \fBgit annex add\fP will add files locked, +as usual. However, \fBgit add\fP (and \fBgit commit \-a\fP etc) still add files +unlocked. This is because it's not possible for those git commands to +add files locked. +.IP +.IP "\fB\-\-fix\fP" +Fix the symlinks to annexed files to point to the local git annex +object directory. This can be useful if a repository is checked out in an +unusual way that prevents the symlinks committed to git from pointing at +the annex objects. +.IP +.IP "\fB\-\-hide\-missing\fP" +Only include annexed files in the adjusted branch when their content +is present. +.IP +The adjusted branch is not immediately changed when content availability +changes, so if you \fBgit annex drop\fP files, they will become broken +links in the usual way. And when files that were missing are copied into the +repository from elsewhere, they won't immediatly become visible in the +branch. +.IP +To update the adjusted branch to reflect changes to content availability, +run \fBgit annex adjust \-\-hide\-missing\fP again. Or, to automate updates, +set the \fBannex.adjustedbranchrefresh\fP config. +.IP +Despite missing files being hidden, \fBgit annex sync \-\-content\fP will +still operate on them, and can be used to download missing +files from remotes. It also updates the adjusted branch after +transferring content. +.IP +This option can be combined with \-\-unlock, \-\-lock, or \-\-fix. +.IP +.IP "\fB\-\-unlock\-present\fP" +Unlock files whose content is present, and lock files whose content is +missing. This provides the benefits of working with unlocked files, +but makes it easier to see when the content of a file is not missing, +since it will be a broken symlink. +.IP +The adjusted branch is not immediately changed when content availability +changes, so when you \fBgit annex get\fP files, they will remain locked. +And when you \fBgit annex drop\fP files, they will remain locked and so will +not be broken symlinks. +.IP +To update the adjusted branch to reflect changes to content availability, +run \fBgit annex adjust \-\-unlock\-present\fP again. Or, to automate updates, +set the \fBannex.adjustedbranchrefresh\fP config. Or use git-annex sync +\-\-content, which updates the branch after transferring content. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-unlock(1) +.PP +git-annex\-lock(1) +.PP +git-annex\-upgrade(1) +.PP +git-annex\-sync(1) +.PP +git-annex\-view(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-assist.1 b/man/git-annex-assist.1 new file mode 100644 index 0000000000..6f269f4e8a --- /dev/null +++ b/man/git-annex-assist.1 @@ -0,0 +1,63 @@ +.TH git-annex-assist 1 +.SH NAME +git-annex-assist \- add files and sync changes with remotes +.PP +.SH SYNOPSIS +git annex assist \fB[remote ...]\fP +.PP +.SH DESCRIPTION +This command assists you in checking files into the repository +and syncing with remotes. It's the simplest possible way to use git-annex +at the command line, since only this one command needs to be run on a +regular basis. +.PP +This command first adds any new files to the repository, and commits those +as well as any modified files. Then it does the equivilant of running +[[git-annex\-pull](1) followed by git-annex\-push(1). +.PP +This command operates on all files in the whole working tree, +even when ran in a subdirectory. To limit it to operating on files in a +subdirectory, use the \fB\-\-content\-of\fP option. +.PP +To block some files from being added to the repository, use \fB.gitignore\fP +files. +.PP +By default, all files that are added are added to the annex, the same +as when you run \fBgit annex add\fP. If you configure annex.largefiles, +files that it does not match will instead be added with \fBgit add\fP. +.PP +.SH OPTIONS +.IP "\fB\-\-message=msg\fP \fB\-m msg\fP" +.IP +Use this option to specify a commit message. +.IP +If multiple \-m options are given, their values are concatenated +as separate paragraphs. +.IP +.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" +Only add, pull, and push files in the given path. +.IP +This option can be repeated multiple times with different paths. +.IP +.IP "Also all options supported by git-annex\-pull(1) and" +git-annex\-push(1) can be used. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-add(1) +.PP +git-annex\-pull(1) +.PP +git-annex\-push(1) +.PP +git-annex\-sync(1) +.PP +git-annex\-assistant(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-assistant.1 b/man/git-annex-assistant.1 new file mode 100644 index 0000000000..7c6ea7e30e --- /dev/null +++ b/man/git-annex-assistant.1 @@ -0,0 +1,63 @@ +.TH git-annex-assistant 1 +.SH NAME +git-annex-assistant \- daemon to add files and automatically sync changes +.PP +.SH SYNOPSIS +git annex assistant +.PP +.SH DESCRIPTION +Watches for changes to files in the current directory and its subdirectories, +and automatically syncs them to other remotes. This includes adding new +files. New files published to remotes by others are also automatically +downloaded. +.PP +By default, all new files in the directory will be added to the repository. +(Including dotfiles.) To block some files from being added, use +\fB.gitignore\fP files. +.PP +By default, all files that are added are added to the annex, the same +as when you run \fBgit annex add\fP. If you configure annex.largefiles, +files that it does not match will instead be added with \fBgit add\fP. +.PP +.SH OPTIONS +.IP "\fB\-\-autostart\fP" +.IP +Automatically starts the assistant running in each repository listed +in the file \fB~/.config/git-annex/autostart\fP +.IP +This is typically started at boot, or when you log in. +.IP +.IP "\fB\-\-startdelay=N\fP" +Wait N seconds before running the startup scan. This process can +be expensive and you may not want to run it immediately upon login. +.IP +When \-\-autostart is used, defaults to \-\-startdelay=5. +.IP +.IP "\fB\-\-foreground\fP" +Avoid forking to the background. +.IP +.IP "\fB\-\-stop\fP" +Stop a running daemon in the current repository. +.IP +.IP "\fB\-\-autostop\fP" +The complement to \-\-autostart; stops all running daemons in the +repositories listed in the autostart file. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-watch(1) +.PP +git-annex\-assist(1) +.PP +git-annex\-schedule(1) +.PP +For more details about the git-annex assistant, see + +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-backends.1 b/man/git-annex-backends.1 new file mode 100644 index 0000000000..51a629cb44 --- /dev/null +++ b/man/git-annex-backends.1 @@ -0,0 +1,22 @@ +.TH git-annex-backends 1 +.SH NAME +git-annex\-backends \- key/value backends for git-annex +.PP +.SH DESCRIPTION +The "backend" in git-annex controls how a key is generated from a file's +content and/or filesystem metadata. Most backends are different kinds of +hashes. A single repository can use different backends for different files. +.PP +For a list of available backends, see \fBgit-annex version\fP. For more +details, see +.PP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP + +.PP +.PP + diff --git a/man/git-annex-benchmark.1 b/man/git-annex-benchmark.1 new file mode 100644 index 0000000000..e52f43f408 --- /dev/null +++ b/man/git-annex-benchmark.1 @@ -0,0 +1,60 @@ +.TH git-annex-benchmark 1 +.SH NAME +git-annex-benchmark \- benchmark git-annex commands +.PP +.SH SYNOPSIS +git annex benchmark [criterionopts] ( \-\- commmand [; command] | \-\-databases=N ) +.PP +.SH DESCRIPTION +When git-annex is built with benchmarking support, this command can be used +to benchmark any other git-annex command. For example +"git annex benchmark \-\- get ." +will benchmark "git annex get". +.PP +The command being benchmarked is run in the current git-annex repository. +It does not run just once; the benchmarking process will run it several +times to get a statistically meaningful result. +.PP +When benchmarking an action like "git annex get", the first run will +often do much more than subseqent runs. To make the benchmark repeat an +action like getting a file each time, additional commands can be listed, +separated by ';'. (Note that ';' needs to be escaped from the shell.) +The combined script will be run repeatedly by the benchmark. An example +of using this: +.PP + git annex benchmark \-\- get . ';' drop . +.PP +Note that git-annex benchmark does not fork new git-annex processes when +benchmarking; it calls the command to benchmark internally, and so avoids +git-annex's startup overhead. (So don't try to use it to optimise git-annex +startup.) +.PP +.SH OPTIONS +Before the "\-\-" any of the criterion library's command\-line options can be +used. +.PP +Any options that git-annex usually accepts can be included after the +command to benchmark. +.PP +The \-\-databases=N option benchmark's git-annex's use of sqlite databases, +instead of a command. N is the number of items to benchmark. +.PP +.SH OUTPUT +The output of the commands being benchmarked goes to standard output and +standard error as usual. It's often a good idea to use \-\-quiet to avoid +unnecessary output, unless the generation of that output is part of what +you want to benchmark. +.PP +The benchmark report is output to standard output by default, although +criterion options can be used to redirect it to a file. For example: +.PP + git annex benchmark \-o bench \-\- find >/dev/null +.PP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-calckey.1 b/man/git-annex-calckey.1 new file mode 100644 index 0000000000..6882e603ab --- /dev/null +++ b/man/git-annex-calckey.1 @@ -0,0 +1,40 @@ +.TH git-annex-calckey 1 +.SH NAME +git-annex-calckey \- calculate key for a file +.PP +.SH SYNOPSIS +git annex calckey \fB[file ...]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command calculates the key that would be used +to refer to a file. The file is not added to the annex by this command. +The key is output to stdout. +.PP +The backend used is the one from the annex.backend configuration +setting, which can be overridden by the \-\-backend option. +For example, to force use of the SHA1 backend: +.PP + git annex calckey \-\-backend=SHA1 file +.PP +.SH OPTIONS +.IP "\fB\-\-backend=name\fP" +.IP +Specifies which key\-value backend to use. +.IP +.IP "\fB\-\-batch\fP" +Enable batch mode, in which a line containing the filename is read from +stdin, the key is output to stdout (with a trailing newline), and repeat. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-checkpresentkey.1 b/man/git-annex-checkpresentkey.1 new file mode 100644 index 0000000000..2dd75c1f21 --- /dev/null +++ b/man/git-annex-checkpresentkey.1 @@ -0,0 +1,35 @@ +.TH git-annex-checkpresentkey 1 +.SH NAME +git-annex-checkpresentkey \- check if key is present in remote +.PP +.SH SYNOPSIS +git annex checkpresentkey \fBkey\fP \fB[remote]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command verifies if the specified key's content +is present in the specified remote. +.PP +When no remote is specified, it verifies if the key's content is present +in any accessible remotes. +.PP +Exits 0 if the content is verified present in the remote, or 1 if it is +verified to not be present in the remote. If there is a problem, +the special exit code 100 is used, and an error message is output to stderr. +.PP +.SH OPTIONS +.IP "\fB\-\-batch\fP" +.IP +Enables batch mode. In this mode, the \fBkey\fP is not specified at the +command line, but the \fBremote\fP may still be. Lines containing keys are +read from stdin, and a line is output with "1" if the key is verified to +be present, and "0" otherwise. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-common-options.1 b/man/git-annex-common-options.1 new file mode 100644 index 0000000000..0554969e48 --- /dev/null +++ b/man/git-annex-common-options.1 @@ -0,0 +1,142 @@ +.TH git-annex-common-options 1 +.SH NAME +git-annex\-common\-options \- options supported by many git-annex commands +.PP +.SH DESCRIPTION +These common options are accepted by many git-annex commands, and +may not be explicitly listed on their individual man pages. +Most of these options are accepted by all git-annex commands. +(Many commands also accept the git-annex\-matching\-options(1).) +.PP +.SH OPTIONS +.IP "\fB\-\-force\fP" +.IP +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. +.IP +.IP "\fB\-\-fast\fP" +Avoid some expensive operations normally performed by a command. +What is avoided depends on the command, see individual command's man +pages for details. +.IP +.IP "\fB\-\-quiet\fP" +Avoid the default verbose display of what is done; only show errors. +.IP +.IP "\fB\-\-verbose\fP" +Enable verbose display. On by default but can be disabled by \-\-quiet. +.IP +.IP "\fB\-\-explain\fP" +Display explanations of what git-annex takes into account when deciding +what to do. The explanations will be inside square brackets. +For example, "[foo is not present here]" +.IP +This includes explanations of why preferred content expressions and +other similar expressions like annex.largefiles match or fail to match. +In these explanations, the expression is displayed, with each term +followed by "[TRUE]" or "[FALSE]" to indicate the value. +Irrelevant terms will be ommitted from the explanation, for example +\fB"exclude=* and copies=1"\fP will be displayed as \fB"exclude=*[FALSE]"\fP +.IP +.IP "\fB\-\-debug\fP" +Display debug messages to standard error. +.IP +.IP "\fB\-\-no\-debug\fP" +Disable display of debug messages. +.IP +.IP "\fB\-\-debugfilter=name[,name..]\fP" +When debug message display has been enabled by \fB\-\-debug\fP, this filters +the debug messages that are displayed to ones coming from modules with +the specified names. +.IP +To find the names of modules, see the full debug output, which includes +the module name, eg "(Utility.Process)" +.IP +The full module name does not need to be +specified when using this, a substring of the name will do. +.IP +For example, \fB\-\-debugfilter=Process,External\fP will display debugging +output when git-annex runs processes, and when it communicates with +external special remotes. +.IP +.IP "\fB\-\-numcopies=n\fP" +Overrides the numcopies setting. +.IP +.IP "\fB\-\-mincopies=n\fP" +Overrides the mincopies setting. +.IP +.IP "\fB\-\-rebalance\fP" +Changes the behavior of the "balanced" preferred content expression +to be the same as "fullbalanced" and the "sizebalanced" expression +to be the same as "fullsizebalanced". When those expressions are +used, this can cause a lot of work to be done to rebalance +repositories. +.IP +.IP "\fB\-\-time\-limit=time\fP" +Limits how long a git-annex command runs. The time can be something +like "5h", or "30m" or even "45s" or "10d". +.IP +Note that git-annex may continue running for some time past the specified +time limit, in order to finish processing files it started before the +time limit was reached. That and a cleaner shutdown are the differences +between using this option and a command like \fBtimeout(1)\fP. +.IP +When the time limit prevents git-annex from doing all it +was asked to, it will exit with a special code, 101. +.IP +.IP "\fB\-\-size\-limit=size\fP" +Limits the total size of annexed files that a git-annex command +can process. +.IP +The size can be specified with any commonly used units, for example, +"50gb". +.IP +In some cases, an annexed file's size is not known. This option will +prevent git-annex from processing such files. +.IP +When the size limit prevents git-annex from acting on any files, +it will exit with a special code, 101. +.IP +.IP "\fB\-\-semitrust=repository\fP" +.IP "\fB\-\-untrust=repository\fP" +Overrides trust settings for a repository. May be specified more than once. +.IP +The repository should be specified using the name of a configured remote, +or the UUID or description of a repository. +.IP +.IP "\fB\-\-trust=repository\fP" +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 \fB\-\-force\fP option. +.IP +.IP "\fB\-\-trust\-glacier\fP" +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 \fB\-\-force\fP option. +.IP +.IP "\fB\-\-user\-agent=value\fP" +Overrides the User\-Agent to use when downloading files from the web, +or otherwise accessing web services. +.IP +.IP "\fB\-\-notify\-finish\fP" +Caused a desktop notification to be displayed after each successful +file download and upload. +.IP +(Only supported on some platforms, e.g. Linux with dbus. A no\-op when +not supported.) +.IP +.IP "\fB\-\-notify\-start\fP" +Caused a desktop notification to be displayed when a file upload +or download has started, or when a file is dropped. +.IP +.IP "\fB\-c name=value\fP" +Overrides git configuration settings. May be specified multiple times. +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-config.1 b/man/git-annex-config.1 new file mode 100644 index 0000000000..e9334e076d --- /dev/null +++ b/man/git-annex-config.1 @@ -0,0 +1,219 @@ +.TH git-annex-config 1 +.SH NAME +git-annex-config \- configuration stored in git-annex branch +.PP +.SH SYNOPSIS +git annex config \-\-set name value +.PP +git annex config \-\-get name +.PP +git annex config \-\-unset name +.PP +git annex config \-\-show\-origin name +.PP +.SH DESCRIPTION +Set or get configuration settings stored in the git-annex branch. +.PP +Unlike \fBgit config\fP settings, these settings can be seen +in all clones of the repository, once they have gotten their +git-annex branches in sync. +.PP +These settings can be overridden on a per\-repository basis using +\fBgit config\fP. +.PP +git-annex does not check the git-annex branch for all the \fBgit config\fP +settings that affect it (which are listed on the git-annex man page +CONFIGURATION section). Only a few make sense to be able to set such +that all clones of a repository see the setting, and so git-annex only +looks for these. +.PP +.SH SUPPORTED SETTINGS +.IP "\fBannex.numcopies\fP" +.IP +Tells git-annex how many copies it should preserve of files, over all +repositories. The default is 1. +.IP +When git-annex is asked to drop a file, it first verifies that the +number of copies can be satisfied among all the other +repositories that have a copy of the file. +.IP +In unusual situations, involving special remotes that do not support +locking, and concurrent drops of the same content from multiple +repositories, git-annex may violate the numcopies setting. It still +guarantees at least 1 copy is preserved. This can be configured by +setting annex.mincopies. +.IP +This is the same setting that the git-annex\-numcopies(1) command +configures. It can be overridden on a per\-file basis +by the annex.numcopies setting in \fB.gitattributes\fP files. +.IP +.IP "\fBannex.mincopies\fP" +Tells git-annex how many copies it is required to preserve of files, +over all repositories. The default is 1. +.IP +This supplements the annex.numcopies setting. +In unusual situations, involving special remotes that do not support +locking, and concurrent drops of the same content from multiple +repositories, git-annex may violate the numcopies setting. +In these unusual situations, git-annex ensures that the number of copies +never goes below mincopies. +.IP +It is a good idea to not only rely on only setting mincopies. Set +numcopies as well, to a larger number, and keep mincopies at the +bare minimum you're comfortable with. Setting mincopies to a large +number, rather than setting numcopies will in some cases prevent +droping content in entirely safe situations. +.IP +This is the same setting that the git-annex\-mincopies(1) command +configures. It can be overridden on a per\-file basis +by the annex.mincopies setting in \fB.gitattributes\fP files. +.IP +.IP "\fBannex.largefiles\fP" +Used to configure which files are large enough to be added to the annex. +It is an expression that matches the large files, eg +"\fBinclude=*.mp3 or largerthan(500kb)\fP". +See git-annex\-matching\-expression(1) for details on the syntax. +.IP +This configures the behavior of both git-annex and git when adding +files to the repository. By default, \fBgit-annex add\fP adds all files +to the annex (except dotfiles and files in dotdirs), and +\fBgit add\fP adds files to git (unless they were added to the annex previously). +When annex.largefiles is configured, both +\fBgit annex add\fP and \fBgit add\fP will add matching large files to the +annex, and the other files to git. +.IP +Other git-annex commands also honor annex.largefiles, including +\fBgit annex import\fP, \fBgit annex addurl\fP, \fBgit annex importfeed\fP, +\fBgit-annex assist\fP, and the \fBgit-annex assistant\fP. +.IP +This sets a default, which can be overridden by annex.largefiles +attributes in \fB.gitattributes\fP files, or by \fBgit config\fP. +.IP +.IP "\fBannex.dotfiles\fP" +Normally, dotfiles and files inside dotdirs are assumed to be +configuration files like .gitignore, whose content should always +be part of the git repository, so they will not be added to the annex. +Setting annex.dotfiles to true makes these files be added to the +annex the same as any other file. +.IP +This sets a default, which can be overridden by annex.dotfiles +in \fBgit config\fP. +.IP +.IP "\fBannex.addunlocked\fP" +Commands like \fBgit-annex add\fP default to adding files to the repository +in locked form. This can make them add the files in unlocked form, +the same as if git-annex\-unlock(1) were run on the files. +.IP +This can be set to "true" to add everything unlocked, or it can be a more +complicated expression that matches files by name, size, or content. See +git-annex\-matching\-expression(1) for details. +.IP +This sets a default, which can be overridden by annex.addunlocked +in \fBgit config\fP. +.IP +.IP "\fBannex.autocommit\fP" +Set to false to prevent the \fBgit-annex assistant\fP, \fBgit-annex assist\fP +and \fBgit-annex sync\fP from automatically committing changes to files +in the repository. +.IP +This sets a default, which can be overridden by annex.autocommit +in \fBgit config\fP. +.IP +.IP "\fBannex.resolvemerge\fP" +Set to false to prevent merge conflicts in the checked out branch +being automatically resolved by the \fBgit-annex assitant\fP, +\fBgit-annex sync\fP, \fBgit-annex pull\fP, \fB\fPgit-annex merge, +and the \fBgit-annex post\-receive\fP hook. +.IP +This sets a default, which can be overridden by annex.resolvemerge +in \fBgit config\fP. +.IP +.IP "\fBannex.synccontent\fP" +Set to true to make \fBgit-annex sync\fP default to transferring +annexed content. +.IP +Set to false to prevent \fBgit-annex pull\fP and \fBgit-annex\fP push from +transferring annexed content. +.IP +This sets a default, which can be overridden by annex.synccontent +in \fBgit config\fP. +.IP +.IP "\fBannex.synconlyannex\fP" +Set to true to make \fBgit-annex sync\fP, \fBgit-annex pull\fP and git-annex +push default to only operate on the git-annex branch and annexed content. +.IP +This sets a default, which can be overridden by annex.synconlyannex +in \fBgit config\fP. +.IP +.IP "\fBannex.securehashesonly\fP" +Set to true to indicate that the repository should only use +cryptographically secure hashes (SHA2, SHA3) and not insecure +hashes (MD5, SHA1) for content. +.IP +When this is set, the contents of files using cryptographically +insecure hashes will not be allowed to be added to the repository. +.IP +Also, \fBgit-annex fsck\fP will complain about any files present in +the repository that use insecure hashes. +.IP +Note that this is only read from the git-annex branch by +\fBgit annex init\fP, and is copied to the corresponding git config setting. +So, changes to the value in the git-annex branch won't affect a +repository once it has been initialized. +.IP +.SH OPTIONS +.IP "\fB\-\-set name value\fP" +.IP +Set a value. +.IP +.IP "\fB\-\-get name\fP" +Get a value. +.IP +.IP "\fB\-\-unset\fP" +Unset a value. +.IP +.IP "\fB\-\-show\-origin name\fP" +Explain where the value is configured, whether in the git-annex branch, +or in a \fBgit config\fP file, or \fB.gitattributes\fP file. When a value is +configured in multiple places, displays the place and the value that +will be used. +.IP +Note that the parameter can be the name of one of the settings listed +above, but also any other configuration setting supported by git-annex. +For example, "annex.backend" cannot be set in the git-annex branch, but +it can be set in \fB.gitattributes\fP or \fBgit config\fP and this option can +explain which setting will be used for it. +.IP +.IP "\fB\-\-for\-file file\fP" +Can be used in combination with \fB\-\-show\-origin\fP to specify what +filename to check for in \fB.gitattributes\fP. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH EXAMPLE +Suppose you want to prevent git annex sync from committing changes +to files, so a manual git commit workflow is used in all clones of the +repository. Then run: +.PP + git annex config \-\-set annex.autocommit false +.PP +If you want to override that in a partiticular clone, just use git config +in the clone: +.PP + git config annex.autocommit true +.PP +And to get back to the default behavior: +.PP + git annex config \-\-unset annex.autocommit +.PP +.SH SEE ALSO +git-annex(1) +.PP +git\-config(1) +.PP +git-annex\-vicfg(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-configremote.1 b/man/git-annex-configremote.1 new file mode 100644 index 0000000000..4f093be370 --- /dev/null +++ b/man/git-annex-configremote.1 @@ -0,0 +1,37 @@ +.TH git-annex-configremote 1 +.SH NAME +git-annex-configremote \- changes special remote configuration +.PP +.SH SYNOPSIS +git annex configemote \fBname|uuid|desc [param=value ...]\fP +.PP +.SH DESCRIPTION +Changes the configuration of a special remote that was set up earlier +by \fBgit-annex initremote\fP. The special remote does not need to be enabled +for use in the current repository, and this command will not enable it. +.PP +This command can currently only be used to change the value of the +\fBautoenable\fP parameter, eg "autoenable=false". +.PP +To change other parameters, use \fBgit-annex enableremote\fP +.PP +.SH OPTIONS +Most options are not prefixed by a dash, and set parameters of the remote, +as shown above. +.PP +Also, the git-annex\-common\-options(1) can be used. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-initremote(1) +.PP +git-annex\-configremote(1) +.PP +git-annex\-renameremote(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-contentlocation.1 b/man/git-annex-contentlocation.1 new file mode 100644 index 0000000000..83fa1cab86 --- /dev/null +++ b/man/git-annex-contentlocation.1 @@ -0,0 +1,31 @@ +.TH git-annex-contentlocation 1 +.SH NAME +git-annex-contentlocation \- looks up content for a key +.PP +.SH SYNOPSIS +git annex contentlocation \fB[key ...]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command looks up filename used to store the content +of a key. The filename is output to stdout. If the key's content is not +present in the local repository, nothing is output, and it exits nonzero. +.PP +.SH OPTIONS +.IP "\fB\-\-batch\fP" +.IP +Enable batch mode, in which a line containing the key is read from +stdin, the filename to its content is output to stdout (with a trailing +newline), and repeat. +.IP +Note that if a key's content is not present, an empty line is output to +stdout instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-copy.1 b/man/git-annex-copy.1 new file mode 100644 index 0000000000..21487ebe79 --- /dev/null +++ b/man/git-annex-copy.1 @@ -0,0 +1,127 @@ +.TH git-annex-copy 1 +.SH NAME +git-annex-copy \- copy content of files to/from another repository +.PP +.SH SYNOPSIS +git annex copy \fB[path ...] [\-\-from=remote|\-\-to=remote]\fP +.PP +.SH DESCRIPTION +Copies the content of files from or to another remote. +.PP +With no parameters, operates on all annexed files in the current directory. +Paths of files or directories to operate on can be specified. +.PP +.SH OPTIONS +.IP "\fB\-\-from=remote\fP" +.IP +Copy the content of files from the specified +remote to the local repository. +.IP +Any files that are not available on the remote will be silently skipped. +.IP +.IP "\fB\-\-to=remote\fP" +Copy the content of files from the local repository +to the specified remote. +.IP +.IP "\fB\-\-to=here\fP" +Copy the content of files from all reachable remotes to the local +repository. +.IP +.IP "\fB\-\-from=remote1 \-\-to=remote2\fP" +Copy the content of files that are in remote1 to remote2. +.IP +This is implemented by first downloading the content from remote1 to the +local repository (if not already present), then sending it to remote2, and +then deleting the content from the local repository (if it was not present +to start with). +.IP +.IP "\fB\-\-from\-anywhere \-\-to=remote\fP" +Copy to the remote files from the local repository as well as from any reachable +remotes. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel transfers with up to the specified number of jobs +running at once. For example: \fB\-J10\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +Note that when using \-\-from with \-\-to, twice this many jobs will +run at once, evenly split between the two remotes. +.IP +.IP "\fB\-\-auto\fP" +Rather than copying all specified files, only copy those that don't yet have +the desired number of copies, or that are preferred content of the +destination repository. See git-annex\-preferred\-content(1) +.IP +.IP "\fB\-\-fast\fP" +When copying content to a remote, avoid a round trip to check if the remote +already has content. This can be faster, but might skip copying content +to the remote in some cases. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Rather than specifying a filename or path to copy, this option can be +used to copy all available versions of all files. +.IP +This is the default behavior when running git-annex in a bare repository. +.IP +.IP "\fB\-\-branch=ref\fP" +Operate on files in the specified branch or treeish. +.IP +.IP "\fB\-\-unused\fP" +Operate on files found by last run of git-annex unused. +.IP +.IP "\fB\-\-failed\fP" +Operate on files that have recently failed to be transferred. +.IP +.IP "\fB\-\-key=keyname\fP" +Use this option to copy a specified key. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to specify what to copy. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which lines containing names of files to copy +are read from stdin. +.IP +As each specified file is processed, the usual progress output is +displayed. If a file's content does not need to be copied, or it does not +match specified matching options, or it is not an annexed file, +a blank line is output in response instead. +.IP +Since the usual output while copying a file is verbose and not +machine\-parseable, you may want to use \-\-json in combination with +\-\-batch. +.IP +.IP "\fB\-\-batch\-keys\fP" +This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. +.IP +.IP "\fB\-z\fP" +Makes batch input be delimited by nulls instead of the usual newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-get(1) +.PP +git-annex\-move(1) +.PP +git-annex\-drop(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-dead.1 b/man/git-annex-dead.1 new file mode 100644 index 0000000000..075e687ba6 --- /dev/null +++ b/man/git-annex-dead.1 @@ -0,0 +1,58 @@ +.TH git-annex-dead 1 +.SH NAME +git-annex-dead \- hide a lost repository or key +.PP +.SH SYNOPSIS +git annex dead \fB[repository ...] [\-\-key somekey ...]\fP +.PP +.SH DESCRIPTION +This command exists to deal with situations where data has been lost, +and you know it has, and you want to stop being reminded of that fact. +.PP +When a repository is specified, indicates that the repository has +been irretrievably lost, so it will not be listed in eg, \fBgit annex whereis\fP. +Repositories can be specified using their remote name, their +description, or their UUID. (To undo, use \fBgit-annex semitrust\fP.) +.PP +When a key is specified, indicates that the content of that key has been +irretrievably lost. This makes the key be skipped when operating +on all keys with eg \fB\-\-all\fP. +(To undo, add the key's content back to the repository, +by using eg, \fBgit-annex reinject\fP.) +.PP +.SH OPTIONS +.IP "\fB\-\-key=somekey\fP" +.IP +Use to specify a key that is dead. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-trust(1) +.PP +git-annex\-semitrust(1) +.PP +git-annex\-untrust(1) +.PP +git-annex\-renameremote(1) +.PP +git-annex\-expire(1) +.PP +git-annex\-fsck(1) +.PP +git-annex\-reinject(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-describe.1 b/man/git-annex-describe.1 new file mode 100644 index 0000000000..49d2bea2ec --- /dev/null +++ b/man/git-annex-describe.1 @@ -0,0 +1,39 @@ +.TH git-annex-describe 1 +.SH NAME +git-annex-describe \- change description of a repository +.PP +.SH SYNOPSIS +git annex describe repository description +.PP +.SH DESCRIPTION +Changes the description of a repository. +.PP +The repository to describe can be specified by git remote name or +by uuid. To change the description of the current repository, use +"here". +.PP +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. +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-init(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-diffdriver.1 b/man/git-annex-diffdriver.1 new file mode 100644 index 0000000000..45c8ad3471 --- /dev/null +++ b/man/git-annex-diffdriver.1 @@ -0,0 +1,60 @@ +.TH git-annex-diffdriver 1 +.SH NAME +git-annex-diffdriver \- git diff driver +.PP +.SH SYNOPSIS +\fBgit annex diffdriver [\-\-get,\-\-text] [\-\- \-\-diffopts \-\-]\fP +.PP +\fBgit annex diffdriver \-\- cmd \-\-cmdopts \-\-\fP +.PP +.SH DESCRIPTION +Normally, \fBgit diff\fP when run on annexed files displays the changes that +are staged in git, eg annex symlinks and pointers. This command allows +\fBgit diff\fP to diff the content of annexed files instead. +.PP +This command can be used either as a simple text differ, +or as a shim that runs an external git diff driver. +.PP +If some of your annexed files are textual in form, and can be usefully +diffed with diff(1), you can configure git to use this command to diff +them, by configuring \fB.gitattributes\fP to contain eg \fB*.txt diff=annextextdiff\fP +and setting \fBgit config diff.annextextdiff.command "git annex diffdriver \-\-text"\fP. +.PP +If your annexed files are not textual in form, you will need an external +diff driver program that is able to diff the file format(s) you use. +See git's documentation of \fBGIT_EXTERNAL_DIFF\fP and +gitattributes(5)'s documentation of external diff drivers. +.PP +Normally, when using \fBgit diff\fP with an external diff driver, it will not +see the contents of annexed files, since git passes to it the git-annex +symlinks or pointer files. This command works around the problem, by +running the real external diff driver, and passing it the paths to the +annexed content. Configure git to use "git-annex diffdriver \-\- cmd params \-\-" +as the external diff driver, where cmd is the external diff +driver you want it to run, and params are any extra parameters to pass +to it. Note the trailing "\-\-", which is required. +.PP +For example, to use the j\-c\-diff program as the external diff driver, +set \fBGIT_EXTERNAL_DIFF="git-annex diffdriver \-\- j\-c\-diff \-\-"\fP +.PP +.SH OPTIONS +To get the contents of annexed files from remotes when they are not already +present, use the \fB\-\-get\fP option. The file contents will remain in the +repository for later use until dropped in the usual ways. +.PP +To diff text files with diff(1), use the \fB\-\-text\fP option. +To pass additional options to diff(1), use eg "\-\-text \-\- \-\-color \-\-" +.PP +To use an external diff driver command, the options must start with +"\-\-" followed by the diff driver command, its options, and another "\-\-" +.PP +Also the git-annex\-common\-options(1) can be used. +.PP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-direct.1 b/man/git-annex-direct.1 new file mode 100644 index 0000000000..35457937bb --- /dev/null +++ b/man/git-annex-direct.1 @@ -0,0 +1,24 @@ +.TH git-annex-direct 1 +.SH NAME +git-annex-direct \- switch repository to direct mode (deprecated) +.PP +.SH SYNOPSIS +git annex direct +.PP +.SH DESCRIPTION +This used to switch a repository to use direct mode. +But direct mode is no longer used; git-annex automatically converts +direct mode repositories to v7 adjusted unlocked branches. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-indirect(1) +.PP +git-annex\-adjust(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-drop.1 b/man/git-annex-drop.1 new file mode 100644 index 0000000000..9db3208cc3 --- /dev/null +++ b/man/git-annex-drop.1 @@ -0,0 +1,133 @@ +.TH git-annex-drop 1 +.SH NAME +git-annex-drop \- remove content of files from repository +.PP +.SH SYNOPSIS +git annex drop \fB[path ...]\fP +.PP +.SH DESCRIPTION +Drops the content of annexed files from this repository, when +possible. +.PP +git-annex will refuse to drop content if it cannot verify it is +safe to do so. Usually this involves verifying that the content is stored +in some other repository. +.PP +Content that is required to be stored in the repository will not be dropped +even if enough copies exist elsewhere. See git-annex\-required(1). +.PP +With no parameters, tries to drop all annexed files in the current directory. +Paths of files or directories to drop can be specified. +.PP +.SH EXAMPLES + # git annex drop *.jpeg + drop photo1.jpg (checking origin...) ok + drop photo2.jpg (unsafe) + Could only verify the existence of 0 out of 1 necessary copies +.PP + Rather than dropping this file, try using: git annex move +.PP + (Use \-\-force to override this check, or adjust numcopies.) + failed + drop photo3.jpg (checking origin...) ok +.PP +.SH OPTIONS +.IP "\fB\-\-from=remote\fP" +.IP +Rather than dropping the content of files in the local repository, +this option can specify a remote from which the files' +contents should be removed. +.IP +.IP "\fB\-\-auto\fP" +Rather than trying to drop all specified files, drop only those that +are not preferred content of the repository, and avoid trying to drop +files when there are not enough other copies for the drop to be possible. +See git-annex\-preferred\-content(1) +.IP +.IP "\fB\-\-force\fP" +Use this option with care! It bypasses safety checks, and forces +git-annex to delete the content of the specified files, even from +the last repository that is storing their content. Data loss can +result from using this option. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Rather than specifying a filename or path to drop, this option can be +used to drop all available versions of all files. +.IP +This is the default behavior when running git-annex drop in a bare +repository. +.IP +Note that this bypasses checking the .gitattributes annex.numcopies +setting and required content settings. +.IP +.IP "\fB\-\-branch=ref\fP" +Drop files in the specified branch or treeish. +.IP +Note that this bypasses checking the .gitattributes annex.numcopies +setting and required content settings. +.IP +.IP "\fB\-\-unused\fP" +Drop files found by last run of git-annex unused. +.IP +Note that this bypasses checking the .gitattributes annex.numcopies +setting and required content settings. +.IP +.IP "\fB\-\-key=keyname\fP" +Use this option to drop a specified key. +.IP +Note that this bypasses checking the .gitattributes annex.numcopies +setting and required content settings. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to specify what to drop. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Runs multiple drop jobs in parallel. This is particularly useful +when git-annex has to contact remotes to check if it can drop files. +For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which lines containing names of files to drop +are read from stdin. +.IP +As each specified file is processed, the usual output is +displayed. If a file's content is not present, or it does not +match specified matching options, or it is not an annexed file, +a blank line is output in response instead. +.IP +.IP "\fB\-\-batch\-keys\fP" +This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. +.IP +Note that this bypasses checking the .gitattributes annex.numcopies +setting and required content settings. +.IP +.IP "\fB\-z\fP" +Makes the batch input be delimited by nulls +instead of the usual newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-get(1) +.PP +git-annex\-move(1) +.PP +git-annex\-copy(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-dropkey.1 b/man/git-annex-dropkey.1 new file mode 100644 index 0000000000..46d11872f0 --- /dev/null +++ b/man/git-annex-dropkey.1 @@ -0,0 +1,42 @@ +.TH git-annex-dropkey 1 +.SH NAME +git-annex-dropkey \- drops annexed content for specified keys +.PP +.SH SYNOPSIS +git annex dropkey \fB[key ...]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command drops the annexed data for the specified +keys from this repository. +.PP +This can be used to drop content for arbitrary keys, which do not need +to have a file in the git repository pointing at them. +.PP +Warning: This command does not check that enough other copies of the content +exist; using it can easily result in data loss. +.PP +.SH OPTIONS +.IP "\fB\-\-batch\fP" +.IP +Enables batch mode, in which lines containing keys to drop are read from +stdin. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-setkey(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-dropunused.1 b/man/git-annex-dropunused.1 new file mode 100644 index 0000000000..dddb1c6349 --- /dev/null +++ b/man/git-annex-dropunused.1 @@ -0,0 +1,56 @@ +.TH git-annex-dropunused 1 +.SH NAME +git-annex-dropunused \- drop unused file content +.PP +.SH SYNOPSIS +git annex dropunused \fB[number|range ...]\fP +.PP +.SH DESCRIPTION +Drops the data corresponding to the numbers, as listed by the last +\fBgit annex unused\fP +.PP +You can also specify ranges of numbers, such as "1\-1000". +Or, specify "all" to drop all unused data. +.PP +.SH OPTIONS +.IP "\fB\-\-from=remote\fP" +.IP +Rather than dropping the unused files from the local repository, +drop them from the remote repository. +.IP +.IP "\fB\-\-force\fP" +Use this option with care! It bypasses safety checks, and forces +git-annex to delete the content of the specified files, even from +the last repository that is storing their content. Data loss can +result from using this option. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Runs multiple drop jobs in parallel. This is particularly useful +when git-annex has to contact remotes to check if it can drop content. +For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-unused(1) +.PP +git-annex\-drop(1) +.PP +git-annex\-copy(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-edit.1 b/man/git-annex-edit.1 new file mode 100644 index 0000000000..7f292c6f3f --- /dev/null +++ b/man/git-annex-edit.1 @@ -0,0 +1,16 @@ +.TH git-annex-edit 1 +.SH NAME +git-annex-unlock \- unlock files for modification +.PP +.SH SYNOPSIS +git annex edit \fB[path ...]\fP +.PP +.SH DESCRIPTION +This is an alias for the \fBunlock\fP command; see git-annex\-unlock(1) +for details. +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-enable-tor.1 b/man/git-annex-enable-tor.1 new file mode 100644 index 0000000000..d23b4ea428 --- /dev/null +++ b/man/git-annex-enable-tor.1 @@ -0,0 +1,36 @@ +.TH git-annex-enable-tor 1 +.SH NAME +git-annex-enable\-tor \- enable tor hidden service +.PP +.SH SYNOPSIS +git annex enable\-tor +.PP +sudo git annex enable\-tor $(id \-u) +.PP +.SH DESCRIPTION +This command enables a tor hidden service for git-annex. +.PP +It modifies \fB/etc/tor/torrc\fP to register the hidden service. If run as a +normal user, it will try to use sudo/su/etc to get root access to modify +that file. If you run it as root, pass it your non\-root user id number, +as output by \fBid \-u\fP +.PP +After this command is run, \fBgit annex remotedaemon\fP can be run to serve the +tor hidden service, and then \fBgit-annex p2p \-\-gen\-addresses\fP can be run to +give other users access to your repository via the tor hidden service. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-p2p\-auth(1) +.PP +git-annex\-remotedaemon(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-enableremote.1 b/man/git-annex-enableremote.1 new file mode 100644 index 0000000000..139ad45727 --- /dev/null +++ b/man/git-annex-enableremote.1 @@ -0,0 +1,86 @@ +.TH git-annex-enableremote 1 +.SH NAME +git-annex-enableremote \- enables git-annex to use a remote +.PP +.SH SYNOPSIS +git annex enableremote \fBname|uuid|desc [param=value ...]\fP +.PP +.SH DESCRIPTION +Enables use of an existing remote in the current repository, +that was set up earlier by \fBgit annex initremote\fP run in +another clone of the repository. +.PP +When enabling a remote, specify the same name used when originally +setting up that remote with \fBgit annex initremote\fP. Run +\fBgit annex enableremote\fP without any name to get a list of +remote names. Or you can specify the uuid or description of the +remote. +.PP +Some types of special remotes need parameters to be specified every time +they are enabled. For example, the directory special remote requires a +directory= parameter every time. The command will prompt for any required +parameters you leave out. +.PP +This command can also be used to modify the configuration of an existing +special remote, by specifying new values for parameters that are +usually set when using initremote. (However, some settings such as +the as the encryption scheme cannot be changed once a special remote +has been created.) +.PP +The GPG keys that an encrypted special remote is encrypted with can be +changed using the keyid+= and keyid\-= parameters. These respectively +add and remove keys from the list. However, note that removing a key +does NOT necessarily prevent the key's owner from accessing data +in the encrypted special remote +(which is by design impossible, short of deleting the remote). +.PP +One use\-case of keyid\-= is to replace a revoked key with +a new key: +.PP + git annex enableremote mys3 keyid\-=revokedkey keyid+=newkey +.PP +Also, note that for encrypted special remotes using plain public\-key +encryption (encryption=pubkey), adding or removing a key has NO effect +on files that have already been copied to the remote. Hence using +keyid+= and keyid\-= with such remotes should be used with care, and +make little sense except in cases like the revoked key example above. +.PP +If you get tired of manually enabling a special remote in each new clone, +you can pass "autoenable=true". Then when git-annex\-init(1) is run in +a new clone, it will will attempt to enable the special remote. Of course, +this works best when the special remote does not need anything special +to be done to get it enabled. +.PP +(This command also can be used to enable a git remote that git-annex +has found didn't work before and gave up on using, setting +\fBremote..annex\-ignore\fP.) +.PP +.SH OPTIONS +.IP "\fB\-\-with\-url\fP" +.IP +This configures the remote with an "annex::" url, which allows +git to push to and pull from it, using git\-remote\-annex. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also, the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-initremote(1) +.PP +git-annex\-configremote(1) +.PP +git-annex\-renameremote(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-examinekey.1 b/man/git-annex-examinekey.1 new file mode 100644 index 0000000000..87fb632d65 --- /dev/null +++ b/man/git-annex-examinekey.1 @@ -0,0 +1,81 @@ +.TH git-annex-examinekey 1 +.SH NAME +git-annex-examinekey \- prints information from a key +.PP +.SH SYNOPSIS +git annex examinekey \fB[key ...]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command is given a key, and prints information +that can be determined purely by looking at the key. +.PP +.SH OPTIONS +.IP "\fB\-\-format=value\fP" +.IP +Use custom output formatting. +.IP +The value is a format string, in which '${var}' is expanded to the +value of a variable. To right\-justify a variable with whitespace, +use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; +to escape unusual characters (including control characters) +in a variable, use '${escaped_var}' +.IP +To generate a path from the top of the repository to the git-annex +object for a key, use ${objectpath}. To generate the value of a +git-annex pointer file for a key, use ${objectpointer}. +.IP +These variables are also available for use in formats: ${key}, ${backend}, +${bytesize}, ${humansize}, ${keyname}, ${hashdirlower}, ${hashdirmixed}, +${mtime} (for the mtime field of a WORM key), ${file} (when a filename is +provided to examinekey). +.IP +Also, '\\n' is a newline, '\\000' is a NULL, etc. +.IP +The default output format is the same as \fB\-\-format='${escapedkey}\\n'\fP +except when outputting to a terminal, control characters will be escaped. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-migrate\-to\-backend=backend\fP" +Attempt to migrate the input key to the new backend specified. If +successful, outputs information about the migrated key. Otherwise, +outputs information about the input key. +.IP +This only does fast migrations; it will not re\-hash the content of a key +or similar expensive operation. +.IP +One way to use it is to add an extension to a key. +.IP + git-annex examinekey SHA256\-\-xxx \-\-migrate\-to\-backend=SHA256E \-\-filename=foo.tar.gz +.IP +Or to remove the extension from a key: +.IP + git-annex examinekey SHA256E\-\-xxx.tar.gz \-\-migrate\-to\-backend=SHA256 +.IP +.IP "\fB\-\-filename=name\fP" +The name of a file associated with the key, eg a work tree file. +It does not need to exist. This is needed when using \fB\-\-migrate\-to\-backend\fP +to add an extension to the key. +.IP +.IP "\fB\-\-batch\fP" +Enable batch mode, in which a line containing a key is read from stdin, +the information about it is output to stdout, and repeat. +.IP +In order to also provide the name of a file associated with the key, the +line can be in the format "$key $file" +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-expire.1 b/man/git-annex-expire.1 new file mode 100644 index 0000000000..bfcfe56802 --- /dev/null +++ b/man/git-annex-expire.1 @@ -0,0 +1,71 @@ +.TH git-annex-expire 1 +.SH NAME +git-annex-expire \- expire inactive repositories +.PP +.SH SYNOPSIS +git annex expire \fB[repository:]time ...\fP +.PP +.SH DESCRIPTION +This command expires repositories that have not performed some activity +within a specified time period. A repository is expired by marking it as +dead. De\-expiration is also done; if a dead repository performed some +activity recently, it is marked as semitrusted again. +.PP +This can be useful when it's not possible to keep track of the state +of repositories manually. For example, a distributed network of +repositories where nobody can directly access all the repositories to +check their status. +.PP +The repository can be specified using the name of a remote, +or the description or uuid of the repository. +.PP +The time is in the form "60d" or "1y". A time of "never" will disable +expiration. +.PP +If a time is specified without a repository, it is used as the default +value for all repositories. Note that the current repository is never +expired. +.PP +.SH OPTIONS +.IP "\fB\-\-no\-act\fP" +.IP +Print out what would be done, but not not actually expire or unexpire +any repositories. +.IP +.IP "\fB\-\-activity=Name\fP" +Specify the activity that a repository must have performed to avoid being +expired. The default is any activity. +.IP +Currently, the only activity that can be performed to avoid expiration +is \-\-activity=Fsck which corresponds to \fBgit annex fsck\fP. +Note that fscking a remote updates the expiration of the remote +repository, not the local repository. +.IP +The first version of git-annex that recorded fsck activity was +5.20150405. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-fsck(1) +.PP +git-annex\-schedule(1) +.PP +git-annex\-dead(1) +.PP +git-annex\-semitrust(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-export.1 b/man/git-annex-export.1 new file mode 100644 index 0000000000..3b37dcc6b5 --- /dev/null +++ b/man/git-annex-export.1 @@ -0,0 +1,173 @@ +.TH git-annex-export 1 +.SH NAME +git-annex-export \- export a tree of files to a special remote +.PP +.SH SYNOPSIS +git annex export \fBtreeish \-\-to remote\fP +.PP +.SH DESCRIPTION +Use this command to export a tree of files from a git-annex repository. +.PP +Normally files are stored on a git-annex special remote named by their +keys. That is great for reliable data storage, but your filenames are +obscured. Exporting replicates the tree to the special remote as\-is. +.PP +To use this, you have to configure a special remote with +\fBexporttree=yes\fP when initially setting it up with +git-annex\-initremote(1). +.PP +The treeish to export can be the name of a git branch, or a tag, or any +other treeish accepted by git, including eg master:subdir to only export a +subdirectory from a branch. +.PP +When the remote has a preferred content expression set by +git-annex\-wanted(1), the treeish is +filtered through it, excluding annexed files it does not want from +being exported to it. (Note that things in the expression like +"include=" match relative to the top of the treeish being exported.) +.PP +Any files in the treeish that are stored on git will also be exported to +the special remote. +.PP +Repeated exports are done efficiently, by diffing the old and new tree, +and transferring only the changed files, and renaming files as necessary. +.PP +Exports can be interrupted and resumed. However, partially uploaded files +will be re\-started from the beginning in most cases. +.PP +Once content has been exported to a remote, commands like \fBgit annex get\fP +can download content from there the same as from other remotes. However, +since an export is not a key/value store, git-annex has to do more +verification of content downloaded from an export. Some types of keys, +that are not based on checksums, cannot be downloaded from an export. +And, git-annex will never trust an export to retain the content of a key. +.PP +However, some special remotes, notably S3, support keeping track of old +versions of files stored in them. If a special remote is set up to do +that, it can be used as a key/value store and the limitations in the above +paragraph do not apply. Note that dropping content from such a remote is +not supported. See individual special remotes' documentation for +details of how to enable such versioning. +.PP +Commands like \fBgit-annex push\fP can also be used to export a branch to a +special remote, updating the special remote whenever the branch is changed. +To do this, you need to configure "remote..annex\-tracking\-branch" to +tell it what branch to track. For example: +.PP + git config remote.myremote.annex\-tracking\-branch master + git annex push myremote +.PP +You can combine using \fBgit annex export\fP to send changes to a special +remote with \fBgit annex import\fP to fetch changes from a special remote. +When a file on a special remote has been modified by software other than +git-annex, exporting to it will not overwrite the modified file, and the +export will not succeed. You can resolve this conflict by using +\fBgit annex import\fP. +.PP +(Some types of special remotes such as S3 with versioning may instead +let an export overwrite the modified file; then \fBgit annex import\fP +will create a sequence of commits that includes the modified file, +so the overwritten modification is not lost.) +.PP +.SH OPTIONS +.IP "\fB\-\-to=remote\fP" +.IP +Specify the special remote to export to. +.IP +.IP "\fB\-\-from=remote\fP" +When the content of a file is not available in the local repository, +this option lets it be downloaded from another remote, and sent on to the +destination remote. The file will be temporarily stored on local disk, +but will never enter the local repository. +.IP +This option can be repeated multiple times. +.IP +It is possible to use \-\-from with the same remote as \-\-to. If the tree +contains several files with the same content, and the remote being +exported to already contains one copy of the content, this allows making +a copy by downloading the content from it. +.IP +.IP "\fB\-\-tracking\fP" +This is a deprecated way to set "remote..annex\-tracking\-branch". +Instead of using this option, you should just set the git configuration +yourself. +.IP +.IP "\fB\-\-fast\fP" +This sets up an export of a tree, but avoids any expensive file uploads to +the remote. You can later run \fBgit annex push\fP to upload +the files to the export. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Exports multiple files in parallel. This may be faster. +For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH EXAMPLE + git annex initremote myremote type=directory directory=/mnt/myremote \\ + exporttree=yes encryption=none + git annex export master \-\-to myremote +.PP +After that, /mnt/myremote will contain the same tree of files as the master +branch does. +.PP + git mv myfile subdir/myfile + git commit \-m renamed + git annex export master \-\-to myremote +.PP +That updates /mnt/myremote to reflect the renamed file. +.PP + git annex export master:subdir \-\-to myremote +.PP +That updates /mnt/myremote, to contain only the files in the "subdir" +directory of the master branch. +.PP +.SH EXPORT CONFLICTS +If two different git-annex repositories are both exporting different trees +to the same special remote, it's possible for an export conflict to occur. +This leaves the special remote with some files from one tree, and some +files from the other. Files in the special remote may have entirely the +wrong content as well. +.PP +It's not possible for git-annex to detect when making an export will result +in an export conflict. The best way to avoid export conflicts is to either +only ever export to a special remote from a single repository, or to have a +rule about the tree that you export to the special remote. For example, if +you always export origin/master after pushing to origin, then an export +conflict can't happen. +.PP +An export conflict can only be detected after the two git repositories +that produced it get back in sync. Then the next time you run git annex +export, it will detect the export conflict, and resolve it. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-initremote(1) +.PP +git-annex\-import(1) +.PP +git-annex\-push(1) +.PP +git-annex\-preferred\-content(1) +.PP +.SH HISTORY +The \fBexport\fP command was introduced in git-annex version 6.20170925. +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-extendcluster.1 b/man/git-annex-extendcluster.1 new file mode 100644 index 0000000000..ddf8638723 --- /dev/null +++ b/man/git-annex-extendcluster.1 @@ -0,0 +1,39 @@ +.TH git-annex-extendcluster 1 +.SH NAME +git-annex-extendcluster \- add an additional gateway to a cluster +.PP +.SH SYNOPSIS +git-annex extendcluster gateway clustername +.PP +.SH DESCRIPTION +This command is used to configure a repository to serve as an additional +gateway to a cluster. It is run in that repository. +.PP +The repository this command is run in should have a remote that is a +gateway to the cluster. The \fBgateway\fP parameter is the name of that remote. +The \fBclustername\fP parameter is the name of the cluster. +.PP +The next step after running this command is to configure +any additional cluster nodes that this gateway serves to the cluster, +then run git-annex\-updatecluster. See the documentation of that +command for details about configuring nodes. +.PP +After running this command in the new gateway repository, it typically +also needs to be run in the other gateway repositories as well, +after adding the new gateway repository as a remote. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +.IP "git-annex(1)" +.IP "git-annex\-initcluster(1)" +.IP "git-annex\-updatecluster(1)" +.IP "git-annex\-updateproxy(1)" +.IP "" +.IP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-filter-branch.1 b/man/git-annex-filter-branch.1 new file mode 100644 index 0000000000..f6a18319bf --- /dev/null +++ b/man/git-annex-filter-branch.1 @@ -0,0 +1,135 @@ +.TH git-annex-filter-branch 1 +.SH NAME +git-annex-filter\-branch \- filter information from the git-annex branch +.PP +.SH SYNOPSIS +git annex filter\-branch [...] +.PP +.SH DESCRIPTION +This copies selected information from the git-annex branch into a git +commit object, and outputs its hash. The git commit can be transported +to another git repository, and given a branch name such as "foo/git-annex", +and git-annex there will automatically merge that into its git-annex +branch. This allows publishing some information from your git-annex branch, +without publishing the whole thing. +.PP +Other ways to avoid publishing information from a git-annex branch, +or remove information from it include git-annex\-forget(1), the +\fBannex.private\fP git config, and the \fB\-\-private\fP option to +git-annex\-initremote(1). Those are much easier to use, but this +provides full control for those who need it. +.PP +With no options, no information at all will be included from the git-annex +branch. Use options to specify what to include. All options can be specified +multiple times. +.PP +When the repository contains information about a private +repository (due to \fBannex.private\fP being set, or git-annex initremote +\-\-private being used), that private information will be included when +allowed by the options, even though it is not recorded on the git-annex +branch. +.PP +When a repository was created with \fBgit annex initremote \-\-sameas=foo\fP, +its information will be included when the information for foo is, +and excluded when foo is excluded. +.PP +When a special remote is configured with importtree=yes or exporttree=yes, +normally the git tree corresponding to the repository is included in +the git-annex branch, to make sure it does not get garbage collected +by \fBgit gc\fP. Those trees are *not* included when filtering the git-annex +branch. Usually this will not cause any problems, but if such a tree does +get garbage collected, it will prevent accessing files on the special +remote, until the next time a tree is imported or exported to it. +.PP +.SH OPTIONS +.IP "\fBpath\fP" +.IP +Include information about all keys of annexed files in the path. +.IP +.IP "file matching options" +The git-annex\-matching\-options(1) +can be used to specify which files in a path to include. +.IP +.IP "\fB\-\-branch=ref\fP" +Include information about keys referred of annexed files in the branch +or treeish. +.IP +.IP "\fB\-\-key=key\fP" +Include information about a specific key. +.IP +.IP "\fB\-\-all\fP" +Include information about all keys. +.IP +.IP "\fB\-\-include\-key\-information\-for=repo\fP" +When including information about a key, include information specific to +this repository. The repository can be specified with a uuid or the name +of a remote. This option can be used repeatedly to include several +repositories. +.IP +.IP "\fB\-\-include\-all\-key\-information\fP" +Include key information for all repositories, except any excluded with +the \fB\-\-exclude\-key\-information\-for\fP option. +.IP +.IP "\fB\-\-exclude\-key\-information\-for=repo\fP" +When including information about a key, exclude information specific to +this repository. The repository can be specified with a uuid or the name +of a remote. This option can be used repeatedly to exclude +several repositories. +.IP +.IP "\fB\-\-include\-repo\-config\-for=repo\fP" +Include configuration specific to this repository. +The repository can be specified with a uuid or the name of a remote. +.IP +This includes the configuration of special remotes, which may include +embedded credentials, or encryption parameters. It also includes trust +settings, preferred content, etc. It does not include information +about any git-annex keys. This option can be used repeatedly to include +several repositories. +.IP +.IP "\fB\-\-include\-all\-repo\-config\fP" +Include the configuration of all repositories, except for any excluded +with the \fB\-\-exclude\-repo\-config\-for\fP option. +.IP +.IP "\fB\-\-exclude\-repo\-config\-for=repo\fP" +Exclude configuration specific to this repository. +The repository can be specified with a uuid or the name of a remote. +This option can be used repeatedly to exclude several repositories. +.IP +.IP "\fB\-\-include\-global\-config\fP" +Include global configuration, that is not specific to any repository. +.IP +This includes configs stored by git-annex\-numcopies(1), +git-annex\-config(1), etc. +.IP +.SH EXAMPLES +You have a big git-annex repository and are splitting the directory "foo" +out, to make a smaller repository. You want the smaller repo's git-annex +branch to contain all the information about remotes and other configuration, +but only information about keys in that directory. +.PP + git-annex filter\-branch foo \-\-include\-all\-key\-information \\ + \-\-include\-all\-repo\-config \-\-include\-global\-config +.PP +That only includes information about the keys that are currently +in the directory "foo", not keys used by old versions of files. +To also include information about the version of the subdir in +tag "1.0", add the option \fB\-\-branch=1.0:foo\fP +.PP +Your repository has a special remote "bar", and you want to share information +about which annexed files are stored in it, but without sharing anything +about the configuration of the remote. +.PP + git-annex filter\-branch \-\-all \-\-include\-all\-key\-information \\ + \-\-include\-all\-repo\-config \-\-exclude\-repo\-config\-for=bar \\ + \-\-include\-global\-config +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-forget(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-filter-process.1 b/man/git-annex-filter-process.1 new file mode 100644 index 0000000000..bd26f3ebfe --- /dev/null +++ b/man/git-annex-filter-process.1 @@ -0,0 +1,48 @@ +.TH git-annex-filter-process 1 +.SH NAME +git-annex-filter\-process \- long running git filter process for git-annex +.PP +.SH SYNOPSIS +git annex filter\-process +.PP +.SH DESCRIPTION +When this is not enabled, each file that git wants to filter involves +starting up a new \fBgit-annex smudge\fP process. Starting many such processes +for many files can be slow, and can make commands like \fBgit checkout\fP and +\fBgit add\fP slow when they are operating on a lot of files. (A lot of locked +annexed files do not make \fBgit checkout\fP slow, but unlocked files and +non\-annexed files do slow it down.) +.PP +On the other hand when this is enabled, \fBgit add\fP of a large file does an +unnecessary extra read of the file, and pipes its contents into git-annex. +So when this is enabled, it will be faster to use \fBgit-annex add\fP to add +large files to the annex, rather than \fBgit add\fP. Other commands that +add files, like \fBgit commit \-a\fP, are also impacted by this. +.PP +This is used by default in git-annex repositories v9 and above, while +v8 repositories use \fBgit-annex smudge\fP for backwards compatability with +older versions of git-annex. +.PP +To enable this in a v8 repository, run: +.PP + git config filter.annex.process 'git-annex filter\-process' +.PP +To disable it, you can just unset the config: +.PP + git config \-\-unset filter.annex.process +.PP +There will be no visible difference in behavior between enabling this and +not, besides changes in speed and memory use when using git. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +git-annex\-smudge(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-find.1 b/man/git-annex-find.1 new file mode 100644 index 0000000000..8e6b262864 --- /dev/null +++ b/man/git-annex-find.1 @@ -0,0 +1,84 @@ +.TH git-annex-find 1 +.SH NAME +git-annex-find \- lists available files +.PP +.SH SYNOPSIS +git annex find \fB[path ...]\fP +.PP +.SH DESCRIPTION +Outputs a list of annexed files in the specified path. With no path, +finds files in the current directory and its subdirectories. +.PP +.SH OPTIONS +.IP "matching options" +.IP +The git-annex\-matching\-options(1) +can be used to specify files to list. +.IP +By default, the find command only lists annexed files whose content is +currently present. Specifying any of the matching options will override +this default behavior. +.IP +To list all annexed files, present or not, specify \fB\-\-anything\fP. +.IP +To list annexed files whose content is not present, specify \fB\-\-not \-\-in=here\fP +.IP +.IP "\fB\-\-branch=ref\fP" +List files in the specified branch or treeish. +.IP +.IP "\fB\-\-print0\fP" +Output filenames terminated with nulls, for use with \fBxargs \-0\fP +.IP +.IP "\fB\-\-format=value\fP" +Use custom output formatting. +.IP +The value is a format string, in which '${var}' is expanded to the +value of a variable. To right\-justify a variable with whitespace, +use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; +to escape unusual characters (including control characters) +in a variable, use '${escaped_var}' +.IP +These variables are available for use in formats: file, key, backend, +bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for +the mtime field of a WORM key). +.IP +Also, '\\n' is a newline, '\\000' is a NULL, etc. +.IP +The default output format is the same as \fB\-\-format='${file}\\n'\fP, +except when outputting to a terminal, control characters will be escaped. +.IP +.IP "\fB\-\-json\fP" +Output the list of files in JSON format. +.IP +This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which a file is read in a line from stdin, +its information displayed, and repeat. +.IP +Note that if the file is not an annexed file, or is not present, +or otherwise doesn't meet the matching options, an empty line +will be output instead. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-whereis(1) +.PP +git-annex\-findkeys(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-findcomputed.1 b/man/git-annex-findcomputed.1 new file mode 100644 index 0000000000..53a8173b31 --- /dev/null +++ b/man/git-annex-findcomputed.1 @@ -0,0 +1,92 @@ +.TH git-annex-findcomputed 1 +.SH NAME +git-annex-findcomputed \- lists computed files +.PP +.SH SYNOPSIS +git annex findcomputed \fB[path ...]\fP +.PP +.SH DESCRIPTION +Outputs a list of files in the specified path that can be computed by +enabled compute special remotes. With no path, lists files in the current +directory and its subdirectories. +.PP +Along with the name of each computed file, this displays the input that +was provided to git-annex\-addcomputed(1). +.PP +For example: +.PP +# git-annex findcomputed +foo.jpeg (imageconvert) \-\- convert file.raw file.jpeg passes=10 +bar.gz (compressor) \-\- compress bar \-\-level=9 +.PP +.SH OPTIONS +.IP "matching options" +.IP +The git-annex\-matching\-options(1) +can be used to specify files to list. +.IP +.IP "\fB\-\-branch=ref\fP" +List computed files in the specified branch or treeish. +.IP +.IP "\fB\-\-inputs\fP" +Display each computed file followed by the input that is used to +produce it. The current location of the input file in the work tree is +displayed, but if the input file is not in the work tree, the key +is displayed instead. +.IP +For example: +.IP +foo.jpeg file.raw +bar.gz bar +.IP +When multiple input files are needed to compute a file, outputs multiple +lines for that file: +.IP +foo bar +foo baz +.IP +.IP "\fB\-\-format=value\fP" +Use custom output formatting. +.IP +This option works the same as in git-annex\-find(1), with these +additional variables available for use in it: +"${remote}", "${computation}" +.IP +The default output format is the same as +\fB\-\-format='${file} (${remote}) \-\- ${computation}\\n'\fP, +except when outputting to a terminal, control characters will be escaped. +.IP +When \fB\-\-inputs\fP is used, there are additional variables "${inputfile}" +which is the input filename, "${inputkey}" which is the input key, +and "${input}" which is either the filename or the key. +The default output format for \fB\-\-inputs\fP +is the same as \fB\-\-format='${file} ${input}\\n'\fP +To separate the pair of files by nulls instead, use eg +\-\-format='${file}\\000${input}\\n' +.IP +.IP "\fB\-\-json\fP" +Output the list of files in JSON format. +.IP +This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-addcomputed(1) +.PP +git-annex\-recompute(1) +.PP +git-annex\-findcomputed(1) +.PP +git-annex\-find(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-findkeys.1 b/man/git-annex-findkeys.1 new file mode 100644 index 0000000000..5b94977466 --- /dev/null +++ b/man/git-annex-findkeys.1 @@ -0,0 +1,66 @@ +.TH git-annex-findkeys 1 +.SH NAME +git-annex-findkeys \- lists available keys +.PP +.SH SYNOPSIS +git annex findkeys +.PP +.SH DESCRIPTION +Outputs a list of keys known to git-annex. +.PP +.SH OPTIONS +.IP "matching options" +.IP +The git-annex\-matching\-options(1) +can be used to specify which keys to list. +.IP +By default, the findkeys command only lists keys whose content is +currently present. Specifying any of the matching options will override +this default behavior and match on all keys that git-annex knows about. +.IP +To list all keys, present or not, specify \fB\-\-anything\fP. +.IP +To list keys whose content is not present, specify \fB\-\-not \-\-in=here\fP +.IP +.IP "\fB\-\-print0\fP" +Output keys terminated with nulls, for use with \fBxargs \-0\fP +.IP +.IP "\fB\-\-format=value\fP" +Use custom output formatting. +.IP +The value is a format string, in which '${var}' is expanded to the +value of a variable. To right\-justify a variable with whitespace, +use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; +to escape unusual characters (including control characters) +in a variable, use '${escaped_var}' +.IP +These variables are available for use in formats: key, backend, +bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for +the mtime field of a WORM key). +.IP +Also, '\\n' is a newline, '\\000' is a NULL, etc. +.IP +The default output format is the same as \fB\-\-format='${escapedkey}\\n'\fP +except when outputting to a terminal, control characters will be escaped. +.IP +.IP "\fB\-\-json\fP" +Output the list of keys in JSON format. +.IP +This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-find(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-findref.1 b/man/git-annex-findref.1 new file mode 100644 index 0000000000..4920b6f68f --- /dev/null +++ b/man/git-annex-findref.1 @@ -0,0 +1,23 @@ +.TH git-annex-findref 1 +.SH NAME +git-annex-findref \- lists files in a git ref (deprecated) +.PP +.SH SYNOPSIS +git annex findref \fB[ref]\fP +.PP +.SH DESCRIPTION +This is the same as \fBgit annex find\fP with the \-\-branch option, and you're +encouraged to use that instead unless you need to support older versions of +git-annex. +.PP +.SH OPTIONS +Same as git-annex\-find(1) +.PP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-fix.1 b/man/git-annex-fix.1 new file mode 100644 index 0000000000..3d3313bc8b --- /dev/null +++ b/man/git-annex-fix.1 @@ -0,0 +1,42 @@ +.TH git-annex-fix 1 +.SH NAME +git-annex-fix \- fix up links to annexed content +.PP +.SH SYNOPSIS +git annex fix \fB[path ...]\fP +.PP +.SH DESCRIPTION +Fixes up symlinks that have become broken to again point to annexed +content. +.PP +This is useful to run manually when you have been moving the symlinks +around, but is done automatically when committing a change with git too. +.PP +Also, adjusts unlocked files to be copies or hard links as +configured by annex.thin. +.PP +.SH OPTIONS +.IP "file matching options" +.IP +The git-annex\-matching\-options(1) +can be used to specify files to fix. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-fsck(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-forget.1 b/man/git-annex-forget.1 new file mode 100644 index 0000000000..a963474327 --- /dev/null +++ b/man/git-annex-forget.1 @@ -0,0 +1,38 @@ +.TH git-annex-forget 1 +.SH NAME +git-annex-forget \- prune git-annex branch history +.PP +.SH SYNOPSIS +git annex forget +.PP +.SH DESCRIPTION +Causes the git-annex branch to be rewritten, throwing away historical +data about past locations of files. The resulting branch will use less +space, but \fBgit annex log\fP will not be able to show where +files used to be located. +.PP +When this rewritten branch is merged into other clones of +the repository, \fBgit-annex\fP will automatically perform the same rewriting +to their local \fBgit-annex\fP branches. So the forgetfulness will automatically +propagate out from its starting point until all repositories running +git-annex have forgotten their old history. (You may need to force +git to push the branch to any git repositories not running git-annex.) +.PP +.SH OPTIONS +.IP "\fB\-\-drop\-dead\fP" +.IP +Also prune references to repositories that have been marked as dead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-dead(1) +.PP +git-annex\-filter\-branch(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-fromkey.1 b/man/git-annex-fromkey.1 new file mode 100644 index 0000000000..b5c7d00cb3 --- /dev/null +++ b/man/git-annex-fromkey.1 @@ -0,0 +1,52 @@ +.TH git-annex-fromkey 1 +.SH NAME +git-annex-fromkey \- adds a file using a specific key +.PP +.SH SYNOPSIS +git annex fromkey \fB[key file ...]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command can be used to manually set up a file +in the git repository to link to a specified key. +.PP +Multiple pairs of file and key can be given in a single command line. +.PP +If no key and file pair are specified on the command line, batch input +is used, the same as if the \-\-batch option were specified. +.PP +Normally the key is a git-annex formatted key. However, to make it easier +to use this to add urls, if the key cannot be parsed as a key, and is a +valid url, an URL key is constructed from the url. Note that this does not +register the url as a location of the key; use git-annex\-registerurl(1) +to do that. +.PP +.SH OPTIONS +.IP "\fB\-\-force\fP" +.IP +Allow making a file link to a key whose content is not in the local +repository. The key may not be known to git-annex at all. +.IP +.IP "\fB\-\-batch\fP" +In batch input mode, lines are read from stdin, and each line +should contain a key and filename, separated by a single space. +.IP +.IP "\fB\-z\fP" +When in batch mode, the input is delimited by nulls instead of the usual +newlines. +.IP +(Note that for this to be used, you have to explicitly enable batch mode +with \fB\-\-batch\fP) +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-fsck.1 b/man/git-annex-fsck.1 new file mode 100644 index 0000000000..3aa734eaf4 --- /dev/null +++ b/man/git-annex-fsck.1 @@ -0,0 +1,122 @@ +.TH git-annex-fsck 1 +.SH NAME +git-annex-fsck \- find and fix problems +.PP +.SH SYNOPSIS +git annex fsck \fB[path ...]\fP +.PP +.SH DESCRIPTION +This command checks annexed files for consistency, and warns about or +fixes any problems found. This is a good complement to \fBgit fsck\fP. +.PP +The default is to check all annexed files in the current directory and +subdirectories. With parameters, only the specified files are checked. +.PP +The problems fsck finds include files that have gotten corrupted, +files whose content has somehow become lost, files that do not have the +configured number of copies yet made, and keys that can be upgraded to a +better format. +.PP +.SH OPTIONS +.IP "\fB\-\-from=remote\fP" +.IP +Check a remote, rather than the local repository. +.IP +Note that by default, files will be copied from the remote to check +their contents. To avoid this expensive transfer, and only +verify that the remote still has the files that are expected to be on it, +add the \fB\-\-fast\fP option. +.IP +.IP "\fB\-\-fast\fP" +Avoids expensive checksum calculations (and expensive transfers when +fscking a remote). +.IP +.IP "\fB\-\-incremental\fP" +Start a new incremental fsck pass, clearing records of all files that +were checked in the previous incremental fsck pass. +.IP +.IP "\fB\-\-more\fP" +Skip files that were checked since the last incremental fsck pass +was started. +.IP +Note that before \fB\-\-incremental\fP is used to start an incremental fsck +pass, files that are checked are still recorded, and using this option +will skip checking those files again. +.IP +Resuming may redundantly check some files that were checked +before. Any files that fsck found problems with before will be re\-checked +on resume. Also, checkpoints are made every 1000 files or every 5 minutes +during a fsck, and it resumes from the last checkpoint, so if an +incremental fsck is interrupted using eg ctrl\-c, it will recheck files +that didn't get into the last checkpoint. +.IP +.IP "\fB\-\-incremental\-schedule=time\fP" +This makes a new incremental fsck be started only a specified +time period after the last incremental fsck was started. +.IP +The time is in the form "10d" or "300h". +.IP +Maybe you'd like to run a fsck for 5 hours at night, picking up each +night where it left off. You'd like this to continue until all files +have been fscked. And once it's done, you'd like a new fsck pass to start, +but no more often than once a month. Then put this in a nightly cron job: +.IP + git annex fsck \-\-incremental\-schedule 30d \-\-time\-limit 5h +.IP +.IP "\fB\-\-numcopies=N\fP" +Override the normally configured number of copies. +.IP +To verify data integrity only while disregarding required number of copies, +use \fB\-\-numcopies=1\fP. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Normally only the files in the currently checked out branch +are fscked. This option causes all versions of all files to be fscked. +.IP +This is the default behavior when running git-annex in a bare repository. +.IP +.IP "\fB\-\-branch=ref\fP" +Operate on files in the specified branch or treeish. +.IP +.IP "\fB\-\-unused\fP" +Operate on files found by last run of git-annex unused. +.IP +.IP "\fB\-\-key=keyname\fP" +Use this option to fsck a specified key. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to control what to fsck. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Runs multiple fsck jobs in parallel. For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-quiet\fP" +Like all git-annex commands, this option makes only error and warning +messages be displayed. This is particularly useful with fsck, which +normally displays all the files it's checking even when there is no +problem with them. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-repair(1) +.PP +git-annex\-expire(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-fuzztest.1 b/man/git-annex-fuzztest.1 new file mode 100644 index 0000000000..d4e8ab9322 --- /dev/null +++ b/man/git-annex-fuzztest.1 @@ -0,0 +1,23 @@ +.TH git-annex-fuzztest 1 +.SH NAME +git-annex-fuzztest \- generates fuzz test files +.PP +.SH SYNOPSIS +git annex fuzztest +.PP +.SH DESCRIPTION +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. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-get.1 b/man/git-annex-get.1 new file mode 100644 index 0000000000..f7b4213d5a --- /dev/null +++ b/man/git-annex-get.1 @@ -0,0 +1,135 @@ +.TH git-annex-get 1 +.SH NAME +git-annex-get \- make content of annexed files available +.PP +.SH SYNOPSIS +git annex get \fB[path ...]\fP +.PP +.SH DESCRIPTION +Makes the content of annexed files available in this repository. This +will involve copying them from a remote repository, or downloading them, +or transferring them from some kind of key\-value store. +.PP +With no parameters, gets all annexed files in the current directory whose +content was not already present. Paths of files or directories to get can +be specified. +.PP +.SH EXAMPLES + # evince foo.pdf + error: Unable to open document foo.pdf: No such file or directory + # ls foo.pdf + foo.pdf@ + # git annex get foo.pdf + get foo.pdf (from origin..) ok + # evince foo.pdf +.PP +.SH OPTIONS +.IP "\fB\-\-auto\fP" +.IP +Rather than getting all the specified files, get only those that don't yet +have the desired number of copies, or that are preferred content of the +repository. See git-annex\-preferred\-content(1) +.IP +.IP "\fB\-\-from=remote\fP" +Normally git-annex will choose which remotes to get the content +from, preferring remotes with lower costs. Use this option to specify +which remote to use. +.IP +Any files that are not available on the remote will be silently skipped. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel download with up to the specified number of jobs +running at once. For example: \fB\-J10\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +When files can be downloaded from multiple remotes, enabling parallel +downloads will split the load between the remotes. For example, if +the files are available on remotes A and B, then one file will be +downloaded from A, and another file will be downloaded from B in +parallel. (Remotes with lower costs are still preferred over higher cost +remotes.) +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to control what to get. +.IP +.IP "\fB\-\-incomplete\fP" +Resume any incomplete downloads of files that were started and +interrupted at some point previously. Useful to pick up where you left +off ... when you don't quite remember where that was. +.IP +These incomplete files are the same ones that are +listed as unused temp files by git-annex\-unused(1). +.IP +Note that the git-annex key will be displayed when downloading, +as git-annex does not know the associated file, and the associated file +may not even be in the current git working directory. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Rather than specifying a filename or path to get, this option can be +used to get all available versions of all files. +.IP +This is the default behavior when running git-annex in a bare repository. +.IP +.IP "\fB\-\-branch=ref\fP" +Operate on files in the specified branch or treeish. +.IP +.IP "\fB\-\-unused\fP" +Operate on files found by last run of git-annex unused. +.IP +.IP "\fB\-\-failed\fP" +Operate on files that have recently failed to be transferred. +.IP +Not to be confused with \fB\-\-incomplete\fP which resumes only downloads +that managed to transfer part of the content of a file. +.IP +.IP "\fB\-\-key=keyname\fP" +Use this option to get a specified key. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which lines containing names of files to get +are read from stdin. +.IP +As each specified file is processed, the usual progress output is +displayed. If the specified file's content is already present, +or it does not match specified matching options, or +it is not an annexed file, a blank line is output in response instead. +.IP +Since the usual output while getting a file is verbose and not +machine\-parseable, you may want to use \-\-json in combination with +\-\-batch. +.IP +.IP "\fB\-\-batch\-keys\fP" +This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. +.IP +.IP "\fB\-z\fP" +Makes batch input be delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-drop(1) +.PP +git-annex\-copy(1) +.PP +git-annex\-move(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-group.1 b/man/git-annex-group.1 new file mode 100644 index 0000000000..77d9404f0b --- /dev/null +++ b/man/git-annex-group.1 @@ -0,0 +1,38 @@ +.TH git-annex-group 1 +.SH NAME +git-annex-group \- add a repository to a group +.PP +.SH SYNOPSIS +git annex group \fBrepository [groupname]\fP +.PP +.SH DESCRIPTION +Adds a repository to a group, such as "archive" or "transfer". +The groupname must be a single word. +.PP +Omit the groupname to show the current groups that a repository is in. +.PP +There are some standard groups that have different default preferred content +settings. See +.PP +A repository can be in multiple groups at the same time. +.PP +.SH OPTIONS +.IP "\fB\-\-list\fP" +.IP +Outputs a list of all groups that are used by at least one repository. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-ungroup(1) +.PP +git-annex\-preferred\-content(1) +.PP +git-annex\-wanted(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-groupwanted.1 b/man/git-annex-groupwanted.1 new file mode 100644 index 0000000000..9a97710b84 --- /dev/null +++ b/man/git-annex-groupwanted.1 @@ -0,0 +1,42 @@ +.TH git-annex-groupwanted 1 +.SH NAME +git-annex-groupwanted \- get or set groupwanted expression +.PP +.SH SYNOPSIS +git annex groupwanted \fBgroupname [expression]\fP +.PP +.SH DESCRIPTION +Sets or displays the groupwanted expression. This will be used by +repositories that are in the group, and that have their preferred +content expression set to "groupwanted". +.PP +For example, to configure a group named redundantarchive, and +make repositories in the group want to contain 3 copies of every file: +.PP + git annex groupwanted redundantarchive "not (copies=redundantarchive:3)" + for repo in foo bar baz; do + git annex group $repo redundantarchive + git annex wanted $repo groupwanted + done +.PP +Note that there must be exactly one groupwanted expression configured +amoung all the groups that a repository is in; if there's more than one, +none of them will be used. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-group(1) +.PP +git-annex\-wanted(1) +.PP +git-annex\-preferred\-content(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-import.1 b/man/git-annex-import.1 new file mode 100644 index 0000000000..d1882fdcef --- /dev/null +++ b/man/git-annex-import.1 @@ -0,0 +1,228 @@ +.TH git-annex-import 1 +.SH NAME +git-annex-import \- import files from a special remote +.PP +.SH SYNOPSIS +git annex import \-\-from remote branch[:subdir] | \fB[path ...]\fP +.PP +.SH DESCRIPTION +This command is a way to import a tree of files from elsewhere into your +git-annex repository. It can import files from a git-annex special remote, +or from a directory. +.PP +.SH IMPORTING FROM A SPECIAL REMOTE +Importing from a special remote first downloads or hashes all new content +from it, and then constructs a git commit that reflects files that have +changed on the special remote since the last time git-annex looked at it. +Merging that commit into your repository will update it to reflect changes +made on the special remote. +.PP +This way, something can be using the special remote for file storage, +adding files, modifying files, and deleting files, and you can track those +changes using git-annex. +.PP +You can combine using \fBgit annex import\fP to fetch changes from a special +remote with \fBgit annex export\fP to send your local changes to the special +remote. +.PP +You can only import from special remotes that were configured with +\fBimporttree=yes\fP when set up with git-annex\-initremote(1). Only some +kinds of special remotes will let you configure them this way. A perhaps +non\-exhaustive list is the directory, s3, and adb special remotes. +.PP +To import from a special remote, you must specify the name of a branch. +A corresponding remote tracking branch will be updated by \fBgit annex import\fP. +After that point, it's the same as if you had run a \fBgit fetch\fP +from a regular git remote; you can merge the changes into your +currently checked out branch. +.PP +For example: +.PP + git annex import master \-\-from myremote + git annex merge \-\-allow\-unrelated\-histories myremote/master +.PP +You could just as well use \fBgit merge \-\-allow\-unrelated\-histories myremote/master\fP +as the second step, but using \fBgit-annex merge\fP avoids a couple of gotchas. +When using adjusted branches, it adjusts the branch before merging from it. +.PP +The \-\-allow\-unrelated\-histories option is needed for at least the first +merge of an imported remote tracking branch, since the branch's history is +not connected. Think of this as the remote being a separate git repository +with its own files. If you first \fBgit annex export\fP files to a remote, and +then \fBgit annex import\fP from it, you won't need that option. +.PP +You can import into a subdirectory, using the "branch:subdir" syntax. For +example, if "camera" is a special remote that accesses a camera, and you +want to import those into the photos directory, rather than to the root of +your repository: +.PP + git annex import master:photos \-\-from camera + git merge camera/master +.PP +The \fBgit annex sync \-\-content\fP command (and the git-annex assistant) +can also be used to import from a special remote. +To do this, you need to configure "remote..annex\-tracking\-branch" +to tell it what branch to track. For example: +.PP + git config remote.myremote.annex\-tracking\-branch master + git annex sync \-\-content +.PP +Any files that are gitignored will not be included in the import, +but will be left on the remote. +.PP +When the special remote has a preferred content expression set by +git-annex\-wanted(1), that is used to pick which files to import from +it. Files that are not preferred content of the remote will not be +imported from it, but will be left on the remote. +.PP +So for example, a preferred content expression like +\fB"include=*.jpeg or largerthan=100mb"\fP will make only jpegs and +large files be imported. +.PP +Parts of a preferred content expression that relate to the key, +such as "copies=" are ignored when importing, because the key +is not known before importing. +.PP +Things in the expression like "include=" match relative to the top of +the tree of files on the remote, even when importing into a subdirectory. +.PP +.SH OPTIONS FOR IMPORTING FROM A SPECIAL REMOTE +.IP "\fB\-\-content\fP, \fB\-\-no\-content\fP" +.IP +Controls whether annexed content is downloaded from the special remote. +.IP +The default is to download content into the git-annex repository. +.IP +With \-\-no\-content, git-annex keys are generated from information +provided by the special remote, without downloading it. Commands like +\fBgit-annex get\fP can later be used to download files, as desired. +The \-\-no\-content option is not supported by all special remotes. +.IP +.IP "\fB\-\-message=msg\fP \fB\-m msg\fP" +Use this option to specify a commit message for the changes that have +been made to the special remote since the last import from it. +.IP +If multiple \-m options are given, their values are concatenated +as separate paragraphs. +.IP +.SH IMPORTING FROM A DIRECTORY +When run with a path, \fBgit annex import\fP **moves** files from somewhere outside +the git working copy, and adds them to the annex. In contrast to importing +from a special directory remote, imported files are **deleted from the given +path**. +.PP +This is a legacy interface. It is still supported, but please consider +switching to importing from a directory special remote instead, using the +interface documented above. +.PP +Individual files to import can be specified. If a directory is specified, +the entire directory is imported. Please note that the following instruction +will **delete all files from the source directory**. +.PP + git annex import /media/camera/DCIM/* +.PP +When importing files, there's a possibility of importing a duplicate +of a file that is already known to git-annex \-\- its content is either +present in the local repository already, or git-annex knows of another +repository that contains it, or it was present in the annex before but has +been removed now. +.PP +By default, importing a duplicate of a known file will result in +a new filename being added to the repository, so the duplicate file +is present in the repository twice. (With all checksumming backends, +including the default SHA256E, only one copy of the data will be stored.) +.PP +Several options can be used to adjust handling of duplicate files, see +\fB\-\-duplicate\fP, \fB\-\-deduplicate\fP, \fB\-\-skip\-duplicates\fP, \fB\-\-clean\-duplicates\fP, +and \fB\-\-reinject\-duplicates\fP documentation below. +.PP +symbolic links in the directory being imported are skipped to avoid +accidentially importing things outside the directory that import was ran +on. The directory that import is run on can, however inself be a symbolic +link, and that symbolic link will be followed. +.PP +.SH OPTIONS FOR IMPORTING FROM A DIRECTORY +.IP "\fB\-\-duplicate\fP" +.IP +Do not delete files from the import location. +.IP +Running with this option repeatedly can import the same files into +different git repositories, or branches, or different locations in a git +repository. +.IP +.IP "\fB\-\-deduplicate\fP" +Only import files that are not duplicates; +duplicate files will be deleted from the import location. +.IP +.IP "\fB\-\-skip\-duplicates\fP" +Only import files that are not duplicates. Avoids deleting any +files from the import location. +.IP +.IP "\fB\-\-clean\-duplicates\fP" +Does not import any files, but any files found in the import location +that are duplicates are deleted. +.IP +.IP "\fB\-\-reinject\-duplicates\fP" +Imports files that are not duplicates. Files that are duplicates have +their content reinjected into the annex (similar to +git-annex\-reinject(1)). +.IP +.IP "\fB\-\-force\fP" +Allow existing files to be overwritten by newly imported files. +.IP +Also, causes .gitignore to not take effect when adding files. +.IP +.IP "file matching options" +Many of the git-annex\-matching\-options(1) +can be used to specify files to import. +.IP + git annex import /dir \-\-include='*.png' +.IP +.SH COMMON OPTIONS +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +.IP +Imports multiple files in parallel. This may be faster. +For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-backend\fP" +Specifies which key\-value backend to use for the imported files. +.IP +.IP "\fB\-\-no\-check\-gitignore\fP" +Add gitignored files. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH CAVEATS +Note that using \fB\-\-deduplicate\fP or \fB\-\-clean\-duplicates\fP with the WORM +backend does not look at file content, but filename and mtime. +.PP +If annex.largefiles is configured, and does not match a file, git annex +import will add the non\-large file directly to the git repository, +instead of to the annex. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-add(1) +.PP +git-annex\-export(1) +.PP +git-annex\-preferred\-content(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-importfeed.1 b/man/git-annex-importfeed.1 new file mode 100644 index 0000000000..df727fe41b --- /dev/null +++ b/man/git-annex-importfeed.1 @@ -0,0 +1,129 @@ +.TH git-annex-importfeed 1 +.SH NAME +git-annex-importfeed \- import files from podcast feeds +.PP +.SH SYNOPSIS +git annex importfeed \fB[url ...]\fP +.PP +.SH DESCRIPTION +Imports the contents of podcasts and other rss and atom feeds. Only +downloads files whose content has not already been added to the repository +before, so you can delete, rename, etc the resulting files and repeated +runs won't duplicate them. +.PP +When \fByt\-dlp\fP is installed, it can be used to download links in the feed. +This allows importing e.g., YouTube playlists. +(However, this is disabled by default as it can be a security risk. +See the documentation of annex.security.allowed\-ip\-addresses +in git-annex(1) for details.) +.PP +To make the import process add metadata to the imported files from the feed, +\fBgit config annex.genmetadata true\fP +.PP +By default, the downloaded files are put in a directory with the title +of the feed, and files are named based on the title of the item in the +feed. This can be changed using the \-\-template option. +.PP +Existing files are not overwritten by this command. If "some feed/foo.mp3" +already exists, it will instead write to "some feed/2\_foo.mp3" +(or 3, 4, etc). Sometimes a feed will change an item's url, +resulting in the new url being downloaded to such a filename. +.PP +.SH OPTIONS +.IP "\fB\-\-force\fP" +.IP +Force downloading items it's seen before. +.IP +.IP "\fB\-\-fast\fP, \fB\-\-relaxed\fP, \fB\-\-verifiable\fP, \fB\-\-raw\fP, \fB\-\-raw\-except\fP" +These options behave the same as when using git-annex\-addurl(1). +.IP +.IP "\fB\-\-fast\fP" +Avoid immediately downloading urls. The url is still checked +(via HEAD) to verify that it exists, and to get its size if possible. +.IP +.IP "\fB\-\-relaxed\fP" +Don't immediately download urls, and avoid storing the size of the +url's content. This makes git-annex accept whatever content is there +at a future point. +.IP +.IP "\fB\-\-raw\fP" +Prevent special handling of urls by yt\-dlp, bittorrent, and other +special remotes. This will for example, make importfeed +download a .torrent file and not the contents it points to. +.IP +.IP "\fB\-\-no\-raw\fP" +Require content pointed to by the url to be downloaded using yt\-dlp +or a special remote, rather than the raw content of the url. if that +cannot be done, the import will fail, and the next import of the feed +will retry. +.IP +.IP "\fB\-\-scrape\fP" +Rather than downloading the url and parsing it as a rss/atom feed +to find files to import, uses yt\-dlp to screen scrape the equivilant +of a feed, and imports what it found. +.IP +.IP "\fB\-\-template\fP" +Controls where the files are stored. +.IP +The default template is '${feedtitle}/${itemtitle}${extension}' +.IP +The available variables in the template include these that +are information about the feed: feedtitle, feedauthor, feedurl +.IP +And these that are information about individual items in the feed: +itemtitle, itemauthor, itemsummary, itemdescription, itemrights, +itemid. +.IP +Also, title is itemtitle but falls back to feedtitle if the item has no +title, and author is itemauthor but falls back to feedauthor. +.IP +(All of the above are also added as metadata when annex.genmetadata is +set.) +.IP +The extension variable is the extension of the file in the feed, +or sometimes ".m" if no extension can be determined. +.IP +The template also has some variables for when an item was published. +.IP +itempubyear (YYYY), itempubmonth (MM), itempubday (DD), itempubhour (HH), +itempubminute (MM), itempubsecond (SS), +itempubdate (YYYY\-MM\-DD or if the feed's date cannot be parsed, the raw +value from the feed). +.IP +(These use the UTC time zone, not the local time zone.) +.IP +.IP "\fB\-\-no\-check\-gitignore\fP" +By default, gitignores are honored and it will refuse to download an +url to a file that would be ignored. This makes such files be added +despite any ignores. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Runs multiple downloads parallel. For example: \fB\-J4\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-backend\fP" +Specifies which key\-value backend to use. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-addurl(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-indirect.1 b/man/git-annex-indirect.1 new file mode 100644 index 0000000000..36cb2a858f --- /dev/null +++ b/man/git-annex-indirect.1 @@ -0,0 +1,24 @@ +.TH git-annex-indirect 1 +.SH NAME +git-annex-indirect \- switch repository to indirect mode (deprecated) +.PP +.SH SYNOPSIS +git annex indirect +.PP +.SH DESCRIPTION +This command was used to switch a repository back from direct mode +indirect mode. +.PP +Now git-annex automatically converts direct mode repositories to v7 +with adjusted unlocked branches, so this command does nothing. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-direct(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-info.1 b/man/git-annex-info.1 new file mode 100644 index 0000000000..f9bb124860 --- /dev/null +++ b/man/git-annex-info.1 @@ -0,0 +1,85 @@ +.TH git-annex-info 1 +.SH NAME +git-annex-info \- information about an item or the repository +.PP +.SH SYNOPSIS +git annex info \fB[directory|file|treeish|remote|description|uuid ...]\fP +.PP +.SH DESCRIPTION +Displays statistics and other information for the specified item. +.PP +When no item is specified, displays overall information. This includes a +list of all known repositories, how much annexed data is present in the +local repository, the total size of all annexed data in the working +tree, the combined size of annexed data in all repositories, and the annex +sizes of each repository. +.PP +When a directory is specified, displays information +about the annexed files in that directory (and subdirectories). +This includes how much annexed data is present in the local repository, +the total size of all annexed data in the directory, how many files +have the specified numcopies or more (+1, +2 etc) or less (\-1, \-2 etc), +and information about how much of the annexed data is stored in known +repositories. +.PP +When a treeish is specified, displays similar information +as when a directory is specified, but about the annexed files in that +treeish. +.PP +When a remote, or description of a repository, or uuid is specified, +displays information about the specified repository, including the total +amount of annexed data stored in it, and a variety of configuration +information. +.PP +.SH OPTIONS +.IP "\fB\-\-fast\fP" +.IP +Only show the information that can be gathered quickly. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-bytes\fP" +Show file sizes in bytes, disabling the default nicer units. +.IP +.IP "\fB\-\-batch\fP" +Enable batch mode, in which a line containing an item is read from stdin, +the information about it is output to stdout, and repeat. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-autoenable\fP" +Display a list of special remotes that have been configured to +autoenable. +.IP +.IP "\fB\-\-dead\-repositories\fP" +Display a list of repositories that have been marked as dead. +Such repositories are not displayed in other info displays. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) can be used to select what +to include in the statistics. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH EXAMPLES +Suppose you want to run "git annex get .", but +would first like to see how much disk space that will use. +Then run: +.PP + git annex info \-\-fast . \-\-not \-\-in here +.PP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-init.1 b/man/git-annex-init.1 new file mode 100644 index 0000000000..b8decaf564 --- /dev/null +++ b/man/git-annex-init.1 @@ -0,0 +1,80 @@ +.TH git-annex-init 1 +.SH NAME +git-annex-init \- initialize git-annex +.PP +.SH SYNOPSIS +git annex init \fB[description]\fP +.PP +.SH DESCRIPTION +Until a repository (or one of its remotes) has been initialized, +git-annex will refuse to operate on it, to avoid accidentally +using it in a repository that was not intended to have an annex. +.PP +It's useful, but not mandatory, to initialize each new clone +of a repository with its own description. If you don't provide one, +one will be generated using the username, hostname and the path. +.PP +If any special remotes were configured with autoenable=true, +this will also attempt to enable them. See git-annex\-initremote(1). +To prevent that, re\-enable a remote with "autoenable=false", or +mark it as dead (see git-annex\-dead(1)). +.PP +This command is entirely safe, although usually pointless, to run inside an +already initialized git-annex repository. +.PP +A top\-level \fB.noannex\fP file will prevent git-annex init from being used +in a repository. This is useful for repositories that have a policy +reason not to use git-annex. The content of the file will be displayed +to the user who tries to run git-annex init. +.PP +The annex.pre\-init\-command git configuration or pre\-init\-annex hook +is run before initialization and can exit nonzero as well to prevent +initialization, as well as doing other setup. +.PP +.SH EXAMPLES + # git annex add foo + git-annex: First run: git-annex init + # git annex init + init ok + # git annex add foo + add foo ok +.PP +.SH OPTIONS +.IP "\fB\-\-version=N\fP" +.IP +Force the repository to be initialized using a different annex.version +than the current default. +.IP +When the version given is not supported, but can be automatically +upgraded to a newer version, it will use the newer version instead. +.IP +.IP "\fB\-\-autoenable\fP" +Only enable any special remotes that were configured with +autoenable=true, do not otherwise initialize anything. +.IP +.IP "\fB\-\-no\-autoenable\fP" +Do not enable special remotes that were configured with autoenable=true. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-describe(1) +.PP +git-annex\-reinit(1) +.PP +git\-init(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-initcluster.1 b/man/git-annex-initcluster.1 new file mode 100644 index 0000000000..62db038d40 --- /dev/null +++ b/man/git-annex-initcluster.1 @@ -0,0 +1,34 @@ +.TH git-annex-initcluster 1 +.SH NAME +git-annex-initcluster \- initialize a new cluster +.PP +.SH SYNOPSIS +git-annex initcluster name [description] +.PP +.SH DESCRIPTION +This command initializes a new cluster with the specified name. If no +description is provided, one will be set automatically. +.PP +This command should be run in the repository that will serve as the gateway +to the cluster. +.PP +The next step after running this command is to configure +the cluster nodes, then run git-annex\-updatecluster. See the +documentation of that command for details about configuring nodes. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +.IP "git-annex(1)" +.IP "git-annex\-updatecluster(1)" +.IP "git-annex\-extendcluster(1)" +.IP "git-annex\-preferred\-content(1)" +.IP "git-annex\-updateproxy(1)" +.IP "" +.IP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-initremote.1 b/man/git-annex-initremote.1 new file mode 100644 index 0000000000..ea27c001ec --- /dev/null +++ b/man/git-annex-initremote.1 @@ -0,0 +1,138 @@ +.TH git-annex-initremote 1 +.SH NAME +git-annex-initremote \- creates a special (non\-git) remote +.PP +.SH SYNOPSIS +git annex initremote \fBname type=value [param=value ...]\fP +.PP +.SH DESCRIPTION +Creates a new special remote, and adds it to \fB.git/config\fP. +.PP +Example Amazon S3 remote: +.PP + git annex initremote mys3 type=S3 encryption=hybrid keyid=me@example.com datacenter=EU +.PP +Many different types of special remotes are supported by git-annex. +For a list and details, see +.PP +The remote's configuration is specified by the parameters passed +to this command. Different types of special remotes need different +configuration values, so consult the documentation of a special remote for +details. The command will prompt for any required parameters you leave out; +you can also pass \-\-whatelse to see additional parameters. +.PP +A few parameters that are supported by all special remotes are documented in +the next section below. +.PP +Once a special remote has been initialized once with this command, +other clones of the repository can also be set up to access it using +\fBgit annex enableremote\fP. +.PP +The name you provide for the remote can't be one that's been used for any +other special remote before, because \fBgit-annex enableremote\fP uses the name +to identify which special remote to enable. If some old special remote +that's no longer used has taken the name you want to reuse, you might +want to use \fBgit annex renameremote\fP. +.PP +.SH OPTIONS +.IP "\fB\-\-with\-url\fP" +.IP +This configures the remote with an "annex::" url, which allows +git to push to and pull from it, using git\-remote\-annex. +.IP +.IP "\fB\-\-whatelse\fP / \fB\-w\fP" +Describe additional configuration parameters that you could specify. +.IP +For example, if you know you want a S3 remote, but forget how to +configure it: +.IP + git annex initremote mys3 type=S3 \-\-whatelse +.IP +For a machine\-readable list of the parameters, use this with \fB\-\-json\fP. +.IP +.IP "\fB\-\-fast\fP" +When initializing a remote that uses encryption, a cryptographic key is +created. This requires sufficient entropy. If initremote seems to hang +or take a long time while generating the key, you may want to Ctrl\-c it +and re\-run with \fB\-\-fast\fP, which causes it to use a lower\-quality source of +randomness. (Ie, /dev/urandom instead of /dev/random) +.IP +.IP "\fB\-\-sameas=remote\fP" +Use this when the new special remote uses the same underlying storage +as some other remote. This will result in the new special remote having +the same uuid as the specified remote, and either can be used to access +the same content. +.IP +The \fBremote\fP can be the name of a git remote, or the description +or uuid of any git-annex repository. +.IP +When using this option, the new remote inherits the encryption settings +of the existing remote, so you should not specify any encryption +parameters. No other configuration is inherited from the existing remote. +.IP +This will only work if both remotes use the underlying storage in +compatible ways. See this page for information about known +compatabilities. + +.IP +.IP "\fB\-\-private\fP" +Avoid recording information about the special remote in the git-annex +branch. The special remote will only be usable from the repository where +it was created. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH COMMON CONFIGURATION PARAMETERS +.IP "\fBencryption\fP" +.IP +Almost all special remotes support encryption. You will need to specify +what encryption, if any, to use. +.IP +If you do not want any encryption, use \fBencryption=none\fP +.IP +To encrypt to a GPG key, use \fBencryption=hybrid keyid=$keyid ...\fP +and fill in the GPG key id (or an email address associated with a GPG key). +.IP +For details about this and other encrpytion settings, see + +or \-\-whatelse +.IP +.IP "\fBautoenable\fP" +To avoid \fBgit annex enableremote\fP needing to be run, +you can pass "autoenable=true". Then when git-annex is run in a new clone, +it will attempt to enable the special remote. Of course, this works best +when the special remote does not need anything special to be done to get +it enabled. +.IP +.IP "\fBcost\fP" +Specify this to override the default cost of the special remote. +This configuration can be overridden by the local git config, +eg remote.name.annex\-cost. +.IP +.IP "\fBuuid\fP" +Normally, git-annex initremote generates a new UUID for the new special +remote. If you want to, you can specify a UUID for it to use, by passing a +uuid=whatever parameter. This can be useful in some unusual situations. +But if in doubt, don't do this. +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-enableremote(1) +.PP +git-annex\-configremote(1) +.PP +git-annex\-renameremote(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-inprogress.1 b/man/git-annex-inprogress.1 new file mode 100644 index 0000000000..af42f92b45 --- /dev/null +++ b/man/git-annex-inprogress.1 @@ -0,0 +1,63 @@ +.TH git-annex-inprogress 1 +.SH NAME +git-annex-inprogress \- access files while they're being downloaded +.PP +.SH SYNOPSIS +git annex inprogress \fB[path ...]\fP +.PP +.SH DESCRIPTION +This command allows accessing the content of an annexed file while +it is still being downloaded. It outputs to standard output the +name of the temporary file that is being used to download the specified +annexed file. +.PP +Nothing will be output when the download is from an encrypted or chunked +special remote. +.PP +This can sometimes be used to stream a file before it's been fully +downloaded, for example: +.PP + git annex get video.mpeg & + vlc $(git annex inprogress video.mpeg) +.PP +Of course if the file is downloading too slowly, the media player will +reach the end too soon and not show the whole thing. And of course, only +some file formats can be usefully streamed in this way. +.PP +.SH OPTIONS +.IP "\fB[path ..]\fP" +.IP +The files or directories whose partially downloaded content you want to +access. +.IP +Note that, when no path is specified, it defaults to all files in the +current working directory, and subdirectories, which can take a while to +traverse. It's most efficient to specify a the file you are interested +in, or to use \fB\-\-all\fP +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Rather than specifying a filename or path, this option can be +used to access all files that are currently being downloaded. +.IP +.IP "\fB\-\-key=keyname\fP" +Access the file that is currently being downloaded for the specified key. +.IP +.IP "file matching options" +The git-annex\-matching\-options(1) +can be used to specify files to access. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH EXIT STATUS +If any of the requested items are not currently being downloaded, +the exit status will be 1. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-get(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-list.1 b/man/git-annex-list.1 new file mode 100644 index 0000000000..ce8fd6801c --- /dev/null +++ b/man/git-annex-list.1 @@ -0,0 +1,34 @@ +.TH git-annex-list 1 +.SH NAME +git-annex-list \- show which remotes contain files +.PP +.SH SYNOPSIS +git annex list \fB[path ...]\fP +.PP +.SH DESCRIPTION +Displays a table of remotes that contain the contents of the specified +files. This is similar to \fBgit annex whereis\fP but a more compact display. +.PP +.SH OPTIONS +.IP "\fB\-\-allrepos\fP" +.IP +Only configured remotes are shown by default; this option +adds all known repositories to the list. +.IP +.IP "file matching options" +The git-annex\-matching\-options(1) +can be used to specify files to list. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-find(1) +.PP +git-annex\-whereis(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-lock.1 b/man/git-annex-lock.1 new file mode 100644 index 0000000000..4b36943aea --- /dev/null +++ b/man/git-annex-lock.1 @@ -0,0 +1,43 @@ +.TH git-annex-lock 1 +.SH NAME +git-annex-lock \- lock files to prevent modification +.PP +.SH SYNOPSIS +git annex lock \fB[path ...]\fP +.PP +.SH DESCRIPTION +Lock the specified annexed files, to prevent them from being modified. +When no files are specified, all annexed files in the current directory are +locked. +.PP +Locking a file changes how it is stored in the git repository (from a +pointer file to a symlink), so this command will make a change that you +can commit. +.PP +.SH OPTIONS +.IP "file matching options" +.IP +The git-annex\-matching\-options(1) +can be used to specify files to lock. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-add(1) +.PP +git-annex\-unlock(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-log.1 b/man/git-annex-log.1 new file mode 100644 index 0000000000..9a19e876f1 --- /dev/null +++ b/man/git-annex-log.1 @@ -0,0 +1,137 @@ +.TH git-annex-log 1 +.SH NAME +git-annex-log \- shows location log information +.PP +.SH SYNOPSIS +git annex log \fB[path ...]\fP +.PP +.SH DESCRIPTION +This command displays information from the history of the git-annex branch. +.PP +Several things can prevent that information being available to display. +When git-annex\-forget is used, old historical +data gets cleared from the branch. When annex.private or +remote.name.annex\-private is configured, git-annex does not write +information to the branch at all. And when annex.alwayscommit is set to +false, information may not have been committed to the branch yet. +.PP +.SH OPTIONS +.IP "\fB[path ...]\fP" +.IP +Displays the location log for the specified file or files, showing each +repository they were added to ("+") and removed from ("\-"). Note that +it displays information about the file content currently at these paths, +not for any different content that was there in earlier commits. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to control what to act on when displaying the location log +for specified files. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Shows location log changes to all content, with the most recent changes first. +In this mode, the names of files are not available and keys are displayed +instead. +.IP +.IP "\fB\-\-key=keyname\fP" +Displays the location log for the specified key. +.IP +.IP "\fB\-\-branch=ref\fP" +Displays the location log for the files in the specified branch or treeish. +.IP +.IP "\fB\-\-unused\fP" +Displays the location log for files found by last run of git-annex unused. +.IP +.IP "\fB\-\-sizesof=repository\fP" +Displays a history of the total size of the annexed files in a repository +over time from the creation of the repository to the present. +.IP +The repository can be "here" for the current repository, or the name of a +remote, or a repository description or uuid. +.IP +Note that keys that do not have a known size are not included in the +total. +.IP +.IP "\fB\-\-sizes\fP" +This is like \-\-sizesof, but rather than display the size of a single +repository, it displays the sizes of all known repositories. +.IP +The output is a CSV formatted table. +.IP +.IP "\fB\-\-totalsizes\fP" +This is like \fB\-\-sizesof\fP, but it displays the total size of all +known repositories. +.IP +.IP "\fB\-\-interval=time\fP" +When using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, and \fB\-\-totalsizes\fP, this +controls the minimum interval between displays of the size. +The default is to display each new recorded size. +.IP +The time is of the form "30d" or "1y". +.IP +.IP "\fB\-\-received\fP" +Combine this option with \fB\-\-sizesof\fP or \fB\-\-sizes\fP to display +the amount of data received into repositories since the last +line was output. +.IP +.IP "\fB\-\-gnuplot\fP" +Combine this option with \fB\-\-sizesof\fP or \fB\-\-sizes\fP or \fB\-\-totalsizes\fP +to use gnuplot(1) to graph the data. The gnuplot file will be left on +disk for you to reuse. +.IP +For example, to graph the sizes of all repositories: +.IP +git-annex log \-\-sizes \-\-interval=1d \-\-gnuplot +.IP +To graph the amount of new data received into each repository every 30 +days: +.IP +git-annex log \-\-sizes \-\-interval=30d \-\-gnuplot \-\-recieved +.IP +.IP "\fB\-\-bytes\fP" +Show sizes in bytes, disabling the default nicer units. +.IP +.IP "\fB\-\-raw\-date\fP" +Rather than the normal display of a date in the local time zone, +displays seconds since the unix epoch. +.IP +.IP "\fB\-\-since=date\fP, \fB\-\-after=date\fP, \fB\-\-until=date\fP, \fB\-\-before=date\fP, \fB\-\-max\-count=N\fP" +These options are passed through to \fBgit log\fP, and can be used to limit +how far back to search for location log changes. +.IP +For example: \fB\-\-since "1 month ago"\fP +.IP +These options do not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, +and \fB\-\-totalsizes\fP. +.IP +.IP "\fB\-\-gource\fP" +Generates output suitable for the \fBgource\fP visualization program. +.IP +This option does not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, +and \fB\-\-totalsizes\fP. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +This option does not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, +and \fB\-\-totalsizes\fP. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +This option does not have an affect when using \fB\-\-sizesof\fP, \fB\-\-sizes\fP, +and \fB\-\-totalsizes\fP. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-forget(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-lookupkey.1 b/man/git-annex-lookupkey.1 new file mode 100644 index 0000000000..282473ef71 --- /dev/null +++ b/man/git-annex-lookupkey.1 @@ -0,0 +1,41 @@ +.TH git-annex-lookupkey 1 +.SH NAME +git-annex-lookupkey \- looks up key used for file +.PP +.SH SYNOPSIS +git annex lookupkey \fB[file ...]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command looks up the key used for a file in the +index. The key is output to stdout. If there is no key (because +the file is not present in the index, or is not a git-annex managed file), +nothing is output, and it exits nonzero. +.PP +.SH OPTIONS +.IP "\fB\-\-ref\fP" +.IP +Rather than looking for the specified files in the index, interpet them +as git refs. For example to find the key used for somefile in tag v1.0: +.IP +git-annex lookupkey v1.0:somefile +.IP +.IP "\fB\-\-batch\fP" +Enable batch mode, in which a line containing the filename is read from +stdin, the key is output to stdout (with a trailing newline), and repeat. +.IP +Note that if there is no key corresponding to the file, an empty line is +output to stdout instead. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-map.1 b/man/git-annex-map.1 new file mode 100644 index 0000000000..1a4cf23e25 --- /dev/null +++ b/man/git-annex-map.1 @@ -0,0 +1,46 @@ +.TH git-annex-map 1 +.SH NAME +git-annex-map \- generate map of repositories +.PP +.SH SYNOPSIS +git annex map +.PP +.SH DESCRIPTION +Helps you keep track of your repositories, and the connections between them, +by going out and looking at all the ones it can get to, and generating a +Graphviz file displaying it all. If the \fBxdot\fP or \fBdot\fP command is available, +it is used to display the file to your screen. +.PP +This command only connects to hosts that the host it's run on can +directly connect to. It does not try to tunnel through intermediate hosts. +So it might not show all connections between the repositories in the network +.PP +Also, if connecting to a host requires a password, you might have to enter +it several times as the map is being built. +.PP +Note that this subcommand can be used to graph any git repository; it +is not limited to git-annex repositories. +.PP +.SH LEGEND +Ovals are repositories. White is regular, green is trusted, red is +untrusted, and grey is dead. +.PP +Arrows between repositories are connections via git remotes. +.PP +Light blue boxes are hosts that were mapped, and contain the repositories +on that host. +.PP +.SH OPTIONS +.IP "\fB\-\-fast\fP" +.IP +Don't display the generated Graphviz file, but save it for later use. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-matchexpression.1 b/man/git-annex-matchexpression.1 new file mode 100644 index 0000000000..925d248bb9 --- /dev/null +++ b/man/git-annex-matchexpression.1 @@ -0,0 +1,66 @@ +.TH git-annex-matchexpression 1 +.SH NAME +git-annex-matchexpression \- checks if an expression matches +.PP +.SH SYNOPSIS +git annex matchexpression \fBexpression [data]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command is given a preferred content expression, +and some data, and checks if the expression matches the data. It exits 0 if +it matches, and 1 if not. If not enough data was provided, it displays an +error and exits with special code 42. +.PP +For example, this will exit 0: +.PP + git annex matchexpression "include=*.png and largerthan=1mb" \-\-file=foo.png \-\-size=10mb +.PP +.SH OPTIONS +.IP "\fB\-\-file=\fP" +.IP +Provide the filename to match against. Note that the file does not have +to actually exist on disk. +.IP +.IP "\fB\-\-size=\fP" +Tell what the size of the file is. The size can be specified with any +commonly used units, for example, "0.5 gb" or "100 KiloBytes". +.IP +.IP "\fB\-\-key=\fP" +Tell what key is being matched against. This is needed for +matching expressions like "copies=N" and "metadata=tag=foo" and +"present", which all need to look up the information on file for a key. +.IP +Many keys have a known size, and so \-\-size is not needed when specifying +such a key. +.IP +.IP "\fB\-\-largefiles\fP" +Parse the expression as an annex.largefiles expression, rather than a +preferred content expression. +.IP +.IP "\fB\-\-mimetype=\fP" +Tell what the mime type of the file is. Only needed when using +\-\-largefiles with a mimetype= expression. +.IP +.IP "\fB\-\-mimeencoding=\fP" +Tell what the mime encoding of the file is. Only needed when using +\-\-largefiles with a mimeencoding= expression. +.IP +.IP "\fB\-\-explain\fP" +Display explanation of what parts of the preferred content expression +match, and which parts don't match. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-preferred\-content(1) +.PP +git-annex\-matching\-expression(1) +.PP +git-annex\-sim(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-matching-expression.1 b/man/git-annex-matching-expression.1 new file mode 100644 index 0000000000..2126104330 --- /dev/null +++ b/man/git-annex-matching-expression.1 @@ -0,0 +1,89 @@ +.TH git-annex-matching-expression 1 +.SH NAME +git-annex\-matching\-expression \- specifying a set of files +.PP +.SH DESCRIPTION +The annex.largefiles and annex.addunlocked configurations both use +expressions that match some files in the working tree. +.PP +.SH SYNTAX +The format of these expressions is similar to +git-annex\-preferred\-content(1) expressions. +.PP +For example: +.PP + largerthan=100kb and not (include=*.c or include=*.h) +.PP +This matches large files, but excludes C source files. +.PP +The following terms can be used: +.PP +.IP "\fBinclude=glob\fP / \fBexclude=glob\fP" +Specify files to include or exclude. +.IP +The glob can contain \fB*\fP and \fB?\fP to match arbitrary characters. +.IP +Note that this matches on the whole filename, relative to the top +of the git directory. So, \fBinclude=foo\fP will include a file \fBfoo\fP +in the top, but not \fBsubdir/foo\fP. To include both, use +\fBinclude=foo or include=*/foo\fP +.IP +.IP "\fBsmallerthan=size\fP / \fBlargerthan=size\fP" +Matches only files smaller than, or larger than the specified size. +.IP +The size can be specified with any commonly used units, for example, +"0.5 gb" or "100 KiloBytes" +.IP +.IP "\fBmimetype=glob\fP" +Looks up the MIME type of a file, and checks if the glob matches it. +.IP +For example, \fB"mimetype=text/*"\fP will match many varieties of text files, +including "text/plain", but also "text/x\-shellscript", "text/x\-makefile", +etc. +.IP +The MIME types are the same that are displayed by running \fBfile \-\-mime\-type\fP +.IP +This only matches when the content of the file is present in the local +repository. Usually that is the case, but eg, when importing from a +special remote with \-\-no\-content, the content is usually not present. +.IP +This is only available to use when git-annex was built with the +MagicMime build flag. +.IP +.IP "\fBmimeencoding=glob\fP" +Looks up the MIME encoding of a file, and checks if the glob matches it. +.IP +For example, \fB"mimeencoding=binary"\fP will match many kinds of binary +files. +.IP +The MIME encodings are the same that are displayed by running \fBfile \-\-mime\-encoding\fP +.IP +This only matches when the content of the file is present in the local +repository. Usually that is the case, but eg, when importing from a +special remote with \-\-no\-content, the content is usually not present. +.IP +This is only available to use when git-annex was built with the +MagicMime build flag. +.IP +.IP "\fBanything\fP" +Matches any file. +.IP +.IP "\fBnothing\fP" +Matches no files. (Same as "not anything") +.IP +.IP "\fBnot expression\fP" +Inverts what the expression matches. +.IP +.IP "\fBand\fP / \fBor\fP / \fB( expression )\fP" +These can be used to build up more complicated expressions. +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP + +.PP +.PP + diff --git a/man/git-annex-matching-options.1 b/man/git-annex-matching-options.1 new file mode 100644 index 0000000000..fa8a98cbfe --- /dev/null +++ b/man/git-annex-matching-options.1 @@ -0,0 +1,273 @@ +.TH git-annex-matching-options 1 +.SH NAME +git-annex\-matching\-options \- specifying what to act on +.PP +.SH DESCRIPTION +Many git-annex commands support using these options to specify which +files they act on. Some of these options can also be used by commands to +specify which keys they act on. +.PP +Arbitrarily complicated expressions can be built using these options. +For example: +.PP + \-\-include='*.mp3' \-\-and \-( \-\-in=usbdrive \-\-or \-\-in=archive \-) +.PP +The above example makes git-annex work on only mp3 files that are present +in either of two repositories. +.PP +.SH OPTIONS +.IP "\fB\-\-exclude=glob\fP" +.IP +Skips files matching the glob pattern. The glob is matched relative to +the current directory. For example: +.IP + git annex get \-\-exclude='*.mp3' \-\-exclude='subdir/*' +.IP +Note that this will not match anything when using \-\-all or \-\-unused. +.IP +.IP "\fB\-\-include=glob\fP" +Skips files not matching the glob pattern. (Same as \fB\-\-not \-\-exclude\fP.) +For example, to include only mp3 and ogg files: +.IP + git annex get \-\-include='*.mp3' \-\-or \-\-include='*.ogg' +.IP +Note that this will not skip anything when using \-\-all or \-\-unused. +.IP +.IP "\fB\-\-excludesamecontent=glob\fP" +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. +.IP +For example, to drop files in the archive directory, but not when the same +content is used by a file in the work directory: +.IP + git annex drop archive/ \-\-excludesamecontent='work/*' +.IP +.IP "\fB\-\-includesamecontent=glob\fP" +Skips files when there is no other file with the same content +whose name matches the glob. (Same as \fB\-\-not \-\-excludesamecontent\fP) +.IP +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: +.IP + git annex find inbox \-\-includesamecontent='outbox/*' +.IP +.IP "\fB\-\-in=repository\fP" +Matches only when git-annex believes that the content is present in a +repository. +.IP +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 \fB\-\-in=here\fP +.IP +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. +.IP +.IP "\fB\-\-in=repository@{date}\fP" +Matches only when the content was present in a repository on the given +date. +.IP +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. +.IP +For example, you might need to run \fBgit annex drop .\fP to temporarily +free up disk space. The next day, you can get back the files you dropped +using \fBgit annex get . \-\-in=here@{yesterday}\fP +.IP +.IP "\fB\-\-expected\-present\fP" +Matches only when git-annex believes that the content is present +in the local repository. +.IP +This is like \fB\-\-in=here\fP, 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. +.IP +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: +\fBgit-annex get \-\-expected\-present\fP +.IP +.IP "\fB\-\-copies=number\fP" +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. +.IP +.IP "\fB\-\-copies=trustlevel:number\fP" +Matches only when git-annex believes there are the specified number of +copies, on remotes with the specified trust level. For example, +\fB\-\-copies=trusted:2\fP +.IP +To match any trust level at or higher than a given level, +use 'trustlevel+'. For example, \fB\-\-copies=semitrusted+:2\fP +.IP +.IP "\fB\-\-copies=groupname:number\fP" +Matches only when git-annex believes there are the specified number of +copies, on remotes in the specified group. For example, +\fB\-\-copies=archive:2\fP +.IP +.IP "\fB\-\-lackingcopies=number\fP" +Matches only when git-annex believes that the specified number or +more additional copies need to be made in order to satisfy numcopies +settings. +.IP +.IP "\fB\-\-approxlackingcopies=number\fP" +Like lackingcopies, but does not look at .gitattributes annex.numcopies +settings. This makes it significantly faster. +.IP +.IP "\fB\-\-inbackend=name\fP" +Matches only when content is stored using the specified key\-value +backend. +.IP +.IP "\fB\-\-securehash\fP" +Matches only when content is hashed using a cryptographically +secure function. +.IP +.IP "\fB\-\-inallgroup=groupname\fP" +Matches only when git-annex believes content is present in +all repositories in the specified group. +.IP +.IP "\fB\-\-onlyingroup=groupname\fP" +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. +.IP +.IP "\fB\-\-smallerthan=size\fP" +.IP "\fB\-\-largerthan=size\fP" +Matches only when the content is is smaller than, or larger than the +specified size. +.IP +The size can be specified with any commonly used units, for example, +"0.5 gb" or "100 KiloBytes" +.IP +.IP "\fB\-\-metadata field=glob\fP" +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. +.IP +.IP "\fB\-\-metadata fieldvalue\fP" +.IP "\fB\-\-metadata field<=value\fP / \fB\-\-metadata field>=value\fP" +Matches only when there is a metadata field attached with a value +that is less then or greater than the specified value, respectively. +.IP +When both values are numbers, the comparison is done numerically. +When one value is not a number, the values are instead compared +lexicographically. +.IP +(Note that you will need to quote the second parameter to avoid +the shell doing redirection.) +.IP +.IP "\fB\-\-want\-get\fP" +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., \fB\-\-not \-\-in=here\fP +.IP +.IP "\fB\-\-want\-drop\fP" +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., \fB\-\-not \-\-in=here\fP +.IP +Things that this matches will not necessarily be dropped by +\fBgit-annex drop \-\-auto\fP. 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. +.IP +.IP "\fB\-\-want\-get\-by=repository\fP" +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., +\fB\-\-not \-\-in=repository\fP +.IP +The repository should be specified using the name of a configured remote, +or the UUID or description of a repository. \fB\-\-want\-get\-by=here\fP +is the same as \fB\-\-want\-get\fP. +.IP +.IP "\fB\-\-want\-drop\-by=repository\fP" +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., +\fB\-\-not \-\-in=repository\fP +.IP +The repository should be specified using the name of a configured remote, +or the UUID or description of a repository. \fB\-\-want\-drop\-by=here\fP +is the same as \fB\-\-want\-drop\fP. +.IP +.IP "\fB\-\-accessedwithin=interval\fP" +Matches when the content was accessed recently, within the specified time +interval. +.IP +The interval can be in the form "5m" or "1h" or "2d" or "1y", or a +combination such as "1h5m". +.IP +So for example, \fB\-\-accessedwithin=1d\fP matches when the content was +accessed within the past day. +.IP +If the OS or filesystem does not support access times, this will not +match anything. +.IP +.IP "\fB\-\-unlocked\fP" +Matches annexed files that are unlocked. +.IP +.IP "\fB\-\-locked\fP" +Matches annexed files that are locked. +.IP +.IP "\fB\-\-mimetype=glob\fP" +Looks up the MIME type of a file, and checks if the glob matches it. +.IP +For example, \fB\-\-mimetype="text/*"\fP will match many varieties of text files, +including "text/plain", but also "text/x\-shellscript", "text/x\-makefile", +etc. +.IP +The MIME types are the same that are displayed by running \fBfile \-\-mime\-type\fP +.IP +If the file's annexed content is not present, the file will not match. +.IP +This is only available to use when git-annex was built with the +MagicMime build flag. +.IP +.IP "\fB\-\-mimeencoding=glob\fP" +Looks up the MIME encoding of a file, and checks if the glob matches it. +.IP +For example, \fB\-\-mimeencoding=binary\fP will match many kinds of binary +files. +.IP +The MIME encodings are the same that are displayed by running \fBfile \-\-mime\-encoding\fP +.IP +If the file's annexed content is not present, the file will not match. +.IP +This is only available to use when git-annex was built with the +MagicMime build flag. +.IP +.IP "\fB\-\-anything\fP" +Always matches. One way this can be useful is \fBgit-annex find \-\-anything\fP +will list all annexed files, whether their content is present or not. +.IP +.IP "\fB\-\-nothing\fP" +Never matches. (Same as \fB\-\-not \-\-anything\fP) +.IP +.IP "\fB\-\-not\fP" +Inverts the next matching option. For example, to match +when there are less than 3 copies, use \fB\-\-not \-\-copies=3\fP +.IP +.IP "\fB\-\-and\fP" +Requires that both the previous and the next matching option matches. +The default. +.IP +.IP "\fB\-\-or\fP" +Requires that either the previous, or the next matching option matches. +.IP +.IP "\fB\-(\fP" +Opens a group of matching options. +.IP +.IP "\fB\-)\fP" +Closes a group of matching options. +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-maxsize.1 b/man/git-annex-maxsize.1 new file mode 100644 index 0000000000..2d3a2427b0 --- /dev/null +++ b/man/git-annex-maxsize.1 @@ -0,0 +1,61 @@ +.TH git-annex-maxsize 1 +.SH NAME +git-annex-maxsize \- configure maximum size of a repository +.PP +.SH SYNOPSIS +git annex maxsize repository size +.PP +git annex maxsize repository +.PP +git annex maxsize +.PP +.SH DESCRIPTION +This configures the maximum combined size of annexed files that can be +stored in a repository. When run with a repository but without a size, +it displays the currently configured maxsize. When run without any +parameters, it displays an overview of the size and maxsize of all +repositories. +.PP +The repository can be specified by git remote name or +by uuid. For the current repository, use "here". +.PP +The size can be specified using any units. For example "100 gigabytes" or +"0.8TB" +.PP +This is advisory only, it does not prevent git-annex from trying to store +more data in a repository. When a repository has a preferred content +expression configured using "balanced" or "sizebalanced", it will take the +maxsize into account when checking preferred content. It is still possible +for the maxsize to be exceeded, eg when there are multiple writers to the +same repository. +.PP +A hard repository size limit has to be enforced in some other way, +eg by putting the repository on a partition of the desired size. +This command can then be used to tell git-annex about that size limit. +.PP +For example, if a git repository is on a 1 terabyte drive, and is the only +thing stored on that drive, and \fBannex.diskreserve\fP is configured to 1 +gigabyte, then it would make sense to run +\fBgit-annex maxsize here "999 gigabytes"\fP +.PP +To stop checking maximum size of a repository, set the maxsize to 0. +.PP +.SH OPTIONS +.IP "\fB\-\-bytes\fP " +.IP +Displays the maximum size in bytes, disabling the default nicer units. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. +.IP +.IP "The git-annex\-common\-options(1) can also be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-preferred\-content(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-merge.1 b/man/git-annex-merge.1 new file mode 100644 index 0000000000..60beca1a01 --- /dev/null +++ b/man/git-annex-merge.1 @@ -0,0 +1,49 @@ +.TH git-annex-merge 1 +.SH NAME +git-annex-merge \- merge changes from remotes +.PP +.SH SYNOPSIS +git annex merge [branch] +.PP +.SH DESCRIPTION +When run without any parameters, this performs the same merging (and merge +conflict resolution) that is done by the \fBgit-annex pull\fP and \fBgit-annex sync\fP +commands, but without uploading or downloading any data. +.PP +When a branch to merge is specified, this merges it into the current branch, +using the same merge conflict resolution as the \fBgit-annex pull\fP command. +This is especially useful on an adjusted branch, because it applies the same +adjustment to the branch before merging it. +.PP +When annex.resolvemerge is set to false, merge conflict resolution +will not be done. +.PP +.SH OPTIONS +.IP "\fB\-\-allow\-unrelated\-histories\fP, \fB\-\-no\-allow\-unrelated\-histories\fP" +.IP +Passed on to \fBgit merge\fP, to control whether or not to merge +histories that do not share a common ancestor. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also, the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-pull(1) +.PP +git-annex\-sync(1) +.PP +git-annex\-adjust(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-metadata.1 b/man/git-annex-metadata.1 new file mode 100644 index 0000000000..c6dedec422 --- /dev/null +++ b/man/git-annex-metadata.1 @@ -0,0 +1,159 @@ +.TH git-annex-metadata 1 +.SH NAME +git-annex-metadata \- sets or gets metadata of a file +.PP +.SH SYNOPSIS +git annex metadata \fB[path ...]\fP +.PP +.SH DESCRIPTION +The content of an annexed file can have any number of metadata fields +attached to it to describe it. Each metadata field can in turn +have any number of values. +.PP +This command can be used to set metadata, or show the currently set +metadata. +.PP +When run without any \-s or \-t parameters, displays the current metadata. +.PP +Each metadata field has its own "field\-lastchanged" metadata, which +contains the date the field was last changed. Unlike other metadata, +this cannot be directly modified by this command. It is updated +automatically. +.PP +Note that the metadata is attached to git-annex key corresponding to the +content of a file, not to a particular filename on a particular git branch. +All files with the same key share the same metadata, which is +stored in the git-annex branch. If a file is modified, the metadata +of the previous version will be copied to the new key when git-annex adds +the modified file. +.PP +.SH OPTIONS +.IP "\fB\-g field\fP / \fB\-\-get field\fP" +.IP +Get the value(s) of a single field. +.IP +The values will be output one per line, with no other output, so +this is suitable for use in a script. +.IP +.IP "\fB\-s field=value\fP / \fB\-\-set field=value\fP" +Set a field's value, removing any old values. +.IP +.IP "\fB\-s field+=value\fP / \fB\-\-set field+=value\fP" +Add an additional value, preserving any old values. +.IP +.IP "\fB\-s field?=value\fP / \fB\-\-set field?=value\fP" +Set a value, but only if the field does not already have a value set. +.IP +.IP "\fB\-s field\-=value\fP / \fB\-\-set field\-=value\fP" +Remove a value from a field, leaving any other values that the field has +set. +.IP +.IP "\fB\-r field\fP / \fB\-\-remove field\fP" +Remove all current values of the field. +.IP +.IP "\fB\-t tag\fP / \fB\-\-tag tag\fP" +Set a tag. Note that a tag is just a value of the "tag" field. +.IP +.IP "\fB\-u tag\fP / \fB\-\-unset tag\fP" +Unset a tag. +.IP +.IP "\fB\-\-remove\-all\fP" +Remove all metadata from the specified files. +.IP +When a file is modified and the new version added, git-annex will copy +over the metadata from the old version of the file. In situations where +you don't want that copied metadata, you can use this option to remove +it. +.IP +.IP "\fB\-\-force\fP" +By default, \fBgit annex metadata\fP refuses to recursively set metadata +throughout the files in a directory. This option enables such recursive +setting. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to control what to act on. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Specify instead of a file to get/set metadata on all known keys. +.IP +.IP "\fB\-\-branch=ref\fP" +Specify instead of a file to get/set metadata on all files in the +specified branch or treeish. +.IP +.IP "\fB\-\-unused\fP" +Specify instead of a file to get/set metadata on +files found by last run of git-annex unused. +.IP +.IP "\fB\-\-key=keyname\fP" +Specify instead of a file to get/set metadata of the specified key. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output (and input). Each line is a JSON object. +.IP +The format of the JSON objects changed in git-annex version 6.20160726. +.IP +Example of the new format: +.IP + {"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true} +.IP +Example of the old format, which lacks the inner fields object: +.IP + {"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true} +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, which can be used to both get, store, and unset +metadata for multiple files or keys. +.IP +Batch currently only supports JSON input. So, you must +enable \fB\-\-json\fP along with \fB\-\-batch\fP. +.IP +In batch mode, git-annex reads lines from stdin, which contain +JSON objects. It replies to each input annexed file +with an output JSON object. (But if the file is not an annexed file, +an empty line will be output.) +.IP +The format of the JSON sent to git-annex can be the same as the JSON that +it outputs. Or, a simplified version. Only the "file" (or "key") field +is actually necessary. +.IP +For example, to get the current metadata of file foo: +.IP + {"file":"foo"} +.IP +To get the current metadata of the key k: + + {"key":"k"} +.IP +Any metadata fields included in the JSON object will be stored, +replacing whatever values the fields had before. +To unset a field, include it with an empty list of values. +.IP +To change the author of file foo to bar: +.IP + {"file":"foo","fields":{"author":["bar"]}} +.IP +To remove the author of file foo: +.IP + {"file":"foo","fields":{"author":[]}} +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH EXAMPLES +To set some tags on a file and also its author: +.PP + git annex metadata annexscreencast.ogv \-t video \-t screencast \-s author+=Alice +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-view(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-migrate.1 b/man/git-annex-migrate.1 new file mode 100644 index 0000000000..87a6aaac45 --- /dev/null +++ b/man/git-annex-migrate.1 @@ -0,0 +1,100 @@ +.TH git-annex-migrate 1 +.SH NAME +git-annex-migrate \- switch data to different backend +.PP +.SH SYNOPSIS +git annex migrate \fB[path ...]\fP +.PP +git annex migrate \-\-update +.PP +.SH DESCRIPTION +Changes the specified annexed files to use the default key\-value backend +(or the one specified with \fB\-\-backend\fP). Only files whose content +is currently present are migrated. +.PP +Note that the content is also still stored using the old keys after +migration. When possible, hard links are used to avoid that taking up +extra disk space. Use \fBgit annex unused\fP to find and remove the old keys. +.PP +Normally, nothing will be done to specified files that are already using +the new backend. However, if a backend changes the information it uses to +construct a key, this can also be used to migrate files to use the new key +format. +.PP +.SH OPTIONS +.IP "\fB\-\-update\fP" +.IP +This updates the local repository for migrations that were performed +elsewhere. Only new migrations since the last time this was run will +be performed. +.IP +This does not modify the working tree, but only hard links +(or in some cases copies) annex objects to their new keys. +.IP +\fBgit-annex pull\fP and \fBgit-annex sync \-\-content\fP automatically do this, +unless the \fBannex.syncmigrations\fP config is set to false. +.IP +Note that older versions of git-annex did not record migrations in a +way that this can use. Migrations performed with those older versions +had to be manually run in each clone of the repository. +.IP +.IP "\fB\-\-apply\fP" +This applies all recorded migrations to the local repository. It is the +non\-incremental form of \fB\-\-update\fP. +.IP +One situation where this can be useful is when git-annex migrate +\-\-update has been run, but since then un\-migrated +objects have entered the repository. Using this option ensures that +any such objects get migrated. +.IP +Note that older versions of git-annex did not record migrations in a +way that this can use. Migrations performed with those older versions +had to be manually run in each clone of the repository. +.IP +.IP "\fB\-\-backend\fP" +Specify the new key\-value backend to use for migrated data. +.IP +.IP "\fB\-\-force\fP" +Force migration of keys that are already using the new backend. +.IP +.IP "file matching options" +The git-annex\-matching\-options(1) +can be used to specify files to migrate. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.IP "\fB\-\-remove\-size\fP" +Keys often include the size of their content, which is generally a useful +thing. In fact, this command defaults to adding missing size information +to keys in most migrations. With this option, the size information is +removed instead. +.IP +One use of this option is to convert URL keys that were added +by \fBgit-annex addurl \-\-fast\fP to ones that would have been added if +that command was run with the \fB\-\-relaxed\fP option. Eg: +.IP + git-annex migrate \-\-remove\-size \-\-backend=URL somefile +.IP +To add back the size to an URL key, use this: +.IP +git-annex migrate \-\-backend=URL somefile +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-upgrade(1) +.PP +git-annex\-backend(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-mincopies.1 b/man/git-annex-mincopies.1 new file mode 100644 index 0000000000..5e83a6d87d --- /dev/null +++ b/man/git-annex-mincopies.1 @@ -0,0 +1,44 @@ +.TH git-annex-mincopies 1 +.SH NAME +git-annex-mincopies \- configure minimum number of copies +.PP +.SH SYNOPSIS +git annex mincopies \fBN\fP +.PP +.SH DESCRIPTION +Tells git-annex how many copies it is required to preserve of files, over all +repositories. The default is 1. +.PP +Run without a number to get the current value. +.PP +This configuration is stored in the git-annex branch, so it will be seen +by all clones of the repository. It can be overridden on a per\-file basis +by the annex.mincopies setting in .gitattributes files, or can be +overridden temporarily with the \-\-mincopies option. +.PP +This supplements the git-annex\-numcopies(1) setting. +In unusual situations, involving special remotes that do not support +locking, and concurrent drops of the same content from multiple +repositories, git-annex may violate the numcopies setting. +In these unusual situations, git-annex ensures that the number of copies +never goes below mincopies. +.PP +It is a good idea to not only rely on only setting mincopies. Set +numcopies as well, to a larger number, and keep mincopies at the +bare minimum you're comfortable with. Setting mincopies to a large +number, rather than setting numcopies will in some cases prevent +droping content in entirely safe situations. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +git-annex\-numcopies(1) +git-annex\-config(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-mirror.1 b/man/git-annex-mirror.1 new file mode 100644 index 0000000000..d1884b3dc3 --- /dev/null +++ b/man/git-annex-mirror.1 @@ -0,0 +1,85 @@ +.TH git-annex-mirror 1 +.SH NAME +git-annex-mirror \- mirror content of files to/from another repository +.PP +.SH SYNOPSIS +git annex mirror \fB[path ...] [\-\-to=remote|\-\-from=remote]\fP +.PP +.SH DESCRIPTION +This causes a destination repository to mirror a source repository. +.PP +Each specified file in the source repository is mirrored to the destination +repository. If a file's content is present in the source repository, it is +copied to the destination repository. If a file's content is not present in +the source repository, it will be dropped from the destination repository +when the numcopies setting allows. +.PP +Note that mirror does not sync the git repository, but only the file +contents. Use git-annex\-sync(1) for that. +.PP +.SH OPTIONS +.IP "\fB\-\-to=remote\fP" +.IP +Use the local repository as the source repository, and mirror its contents +to the remote. +.IP +.IP "\fB\-\-from=remote\fP" +Use the remote as the source repository, and mirror its contents to the local +repository. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel transfers with up to the specified number of jobs +running at once. For example: \fB\-J10\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Mirror all objects stored in the git annex, not only objects used by +currently existing files. +.IP +However, this bypasses checking the .gitattributes annex.numcopies +setting when dropping files. +.IP +This is the default behavior when running git-annex in a bare repository. +.IP +.IP "\fB\-\-branch=ref\fP" +Operate on files in the specified branch or treeish. +.IP +Like \-\-all, this bypasses checking the .gitattributes annex.numcopies +setting when dropping files. +.IP +.IP "\fB\-\-unused\fP" +Operate on files found by last run of git-annex unused. +.IP +.IP "\fB\-\-failed\fP" +Operate on files that have recently failed to be transferred. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to control what to mirror. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +Note that unlike all other commands that support \fB\-\-json\fP, this command +outputs different types of json objects in different circumstances. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-sync(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-move.1 b/man/git-annex-move.1 new file mode 100644 index 0000000000..2ae3637033 --- /dev/null +++ b/man/git-annex-move.1 @@ -0,0 +1,123 @@ +.TH git-annex-move 1 +.SH NAME +git-annex-move \- move content of files to/from another repository +.PP +.SH SYNOPSIS +git annex move \fB[path ...] [\-\-from=remote|\-\-to=remote|\-\-to=here]\fP +.PP +.SH DESCRIPTION +Moves the content of files from or to another remote. +.PP +With no parameters, operates on all annexed files in the current directory. +Paths of files or directories to operate on can be specified. +.PP +.SH OPTIONS +.IP "\fB\-\-from=remote\fP" +.IP +Move the content of files from the specified remote to the local repository. +.IP +.IP "\fB\-\-to=remote\fP" +Move the content of files from the local repository to the specified remote. +.IP +.IP "\fB\-\-to=here\fP" +Move the content of files from all reachable remotes to the local +repository. +.IP +.IP "\fB\-\-from=remote1 \-\-to=remote2\fP" +Move the content of files that are in remote1 to remote2. Does not change +what is stored in the local repository. +.IP +This is implemented by first downloading the content from remote1 to the +local repository (if not already present), then sending it to remote2, and +then deleting the content from the local repository (if it was not present +to start with). +.IP +.IP "\fB\-\-from\-anywhere \-\-to=remote\fP" +Move to the remote files from the local repository and from all +reachable remotes. +.IP +.IP "\fB\-\-force\fP" +Override numcopies and required content checking, and always remove +files from the source repository once the destination repository has a +copy. +.IP +Note that, even without this option, you can move the content of a file +from one repository to another when numcopies is not satisfied, as long +as the move does not result in there being fewer copies. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel transfers with up to the specified number of jobs +running at once. For example: \fB\-J10\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +Note that when using \-\-from with \-\-to, twice this many jobs will +run at once, evenly split between the two remotes. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Rather than specifying a filename or path to move, this option can be +used to move all available versions of all files. +.IP +This is the default behavior when running git-annex in a bare repository. +.IP +.IP "\fB\-\-branch=ref\fP" +Operate on files in the specified branch or treeish. +.IP +.IP "\fB\-\-unused\fP" +Operate on files found by last run of git-annex unused. +.IP +.IP "\fB\-\-failed\fP" +Operate on files that have recently failed to be transferred. +.IP +.IP "\fB\-\-key=keyname\fP" +Use this option to move a specified key. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) +can be used to control what to move. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which lines containing names of files to move +are read from stdin. +.IP +As each specified file is processed, the usual progress output is +displayed. If a file's content does not need to be moved, +or it does not match specified matching options, or it +is not an annexed file, a blank line is output in response instead. +.IP +Since the usual output while moving a file is verbose and not +machine\-parseable, you may want to use \-\-json in combination with +\-\-batch. +.IP +.IP "\fB\-\-batch\-keys\fP" +This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. +.IP +.IP "\fB\-z\fP" +Makes batch input be delimited by nulls instead of the usual newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-progress\fP" +Include progress objects in JSON output. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-get(1) +.PP +git-annex\-copy(1) +.PP +git-annex\-drop(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-multicast.1 b/man/git-annex-multicast.1 new file mode 100644 index 0000000000..eca4e909ea --- /dev/null +++ b/man/git-annex-multicast.1 @@ -0,0 +1,88 @@ +.TH git-annex-multicast 1 +.SH NAME +git-annex-multicast \- multicast file distribution +.PP +.SH SYNOPSIS +git annex multicast [options] +.PP +.SH DESCRIPTION +Multicast allows files to be broadcast to multiple receivers, +typically on a single local network. +.PP +The uftp program is used for multicast. + +.PP +.SH OPTIONS +.IP "\fB\-\-gen\-address\fP" +.IP +Generates a multicast encryption key and stores a corresponding multicast +address to the git-annex branch. +.IP +.IP "\fB\-\-send [file]\fP" +Sends the specified files to any receivers whose multicast addresses +are stored in the git-annex branch. +.IP +When no files are specified, all annexed files in the current directory +and subdirectories are sent. +.IP +The git-annex\-matching\-options(1) can be used to control which files to +send. For example: +.IP + git annex multicast send . \-\-not \-\-copies 2 +.IP +.IP "\fB\-\-receive\fP" +Receives files from senders whose multicast addresses +are stored in the git-annex brach. +.IP +As each file is received, its filename is displayed. This is the filename +that the sender used; the local working tree may use a different name +for the file, or not contain a link to the file. +.IP +This command continues running, until it is interrupted by you pressing +ctrl\-c. +.IP +Note that the configured annex.diskreserve is not honored by this +command, because \fBuftpd\fP receives the actual files, and can receive +any size file. +.IP +.IP "\fB\-\-uftp\-opt=option\fP \fB\-Uoption\fP" +Pass an option on to the uftp/uftpd command. May be specified multiple +times. +.IP +For example, to broadcast at 50 Mbps: +.IP + git annex multicast send \-U\-R \-U50000 +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH EXAMPLE +Suppose a teacher wants to multicast files to students in a classroom. +.PP +This assumes that the teacher and students have cloned a git-annex +repository, and both can push changes to its git-annex branch, +or otherwise push changes to each\-other. +.PP +First, the teacher runs \fBgit annex multicast \-\-gen\-address; git annex sync\fP +.PP +Next, students each run \fBgit annex multicast \-\-gen\-address; git annex sync\fP +.PP +Once all the students have generated addresses, the teacher runs +\fBgit annex sync\fP once more. (Now the students all have received the +teacher's address, and the teacher has received all the student's addresses.) +.PP +Next students each run \fBgit annex multicast \-\-receive\fP +.PP +Finally, once the students are all listening (ahem), teacher runs +\fBgit annex multicast \-\-send\fP +.PP +.SH SEE ALSO +git-annex(1) +.PP +uftp(1) +.PP +uftpd(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-numcopies.1 b/man/git-annex-numcopies.1 new file mode 100644 index 0000000000..e02300e4ff --- /dev/null +++ b/man/git-annex-numcopies.1 @@ -0,0 +1,41 @@ +.TH git-annex-numcopies 1 +.SH NAME +git-annex-numcopies \- configure desired number of copies +.PP +.SH SYNOPSIS +git annex numcopies \fBN\fP +.PP +.SH DESCRIPTION +Tells git-annex how many copies it should preserve of files, over all +repositories. The default is 1. +.PP +Run without a number to get the current value. +.PP +This configuration is stored in the git-annex branch, so it will be seen +by all clones of the repository. It can be overridden on a per\-file basis +by the annex.numcopies setting in .gitattributes files, or can be +overridden temporarily with the \-\-numcopies option. +.PP +When git-annex is asked to drop a file, it first verifies that the +number of copies can be satisfied among all the other +repositories that have a copy of the file. +.PP +In unusual situations, involving special remotes that do not support +locking, and concurrent drops of the same content from multiple +repositories, git-annex may violate the numcopies setting. It still +guarantees at least 1 copy is preserved. This can be configured by +using git-annex\-mincopies(1) +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +git-annex\-mincopies(1) +git-annex\-config(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-oldkeys.1 b/man/git-annex-oldkeys.1 new file mode 100644 index 0000000000..ba0a25e469 --- /dev/null +++ b/man/git-annex-oldkeys.1 @@ -0,0 +1,48 @@ +.TH git-annex-oldkeys 1 +.SH NAME +git-annex-oldkeys \- list keys used for old versions of files +.PP +.SH SYNOPSIS +git annex oldkeys \fB[path ...]\fP +.PP +.SH DESCRIPTION +Lists keys used for old versions of the specified files or directories. +.PP +The output from this command can be piped into a command like +\fBgit-annex drop \-\-batch\-keys\fP +.PP +The keys are listed in order from newest to oldest. +.PP +When listing old keys for a directory, it will include keys used by deleted +files that were in that directory in past commits. +.PP +.SH OPTIONS +.IP "\-\-unchecked" +.IP +By default this command does not list a key that is also used by any +file in the currently checked out branch. This option makes it also +list such keys. +.IP +The default behavior avoids surprises when dropping listed keys. +This option can be useful when eg copying all old versions of a file to a +remote. +.IP +.IP "\-\-revision\-range=value" +Only list old keys used in the specified range of revisions. +This works the same as the revision range option of \fBgit log\fP. +See gitrevisions(7) for documentation about the format of this option. +.IP +For example, to list only keys used since the tag v1.0, use +\fB\-\-revision\-range=v1.0..HEAD\fP +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-unused(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-p2p.1 b/man/git-annex-p2p.1 new file mode 100644 index 0000000000..4a6980c09c --- /dev/null +++ b/man/git-annex-p2p.1 @@ -0,0 +1,74 @@ +.TH git-annex-p2p 1 +.SH NAME +git-annex-p2p \- configure peer\-2\-peer links between repositories +.PP +.SH SYNOPSIS +git annex p2p [options] +.PP +.SH DESCRIPTION +This command can be used to link git-annex repositories over peer\-2\-peer +networks. +.PP +Currently, the only P2P network supported by git-annex is Tor hidden +services. +.PP +.SH OPTIONS +.IP "\fB\-\-pair\fP" +.IP +Run this in two repositories to pair them together over the P2P network. +.IP +This will print out a code phrase, like "3\-mango\-elephant", and +will prompt for you to enter the code phrase from the other repository. +.IP +Once code phrases have been exchanged, the two repositories will +be paired. A git remote will be created for the other repository, +with a name like "peer1". +.IP +This uses [Magic Wormhole](https://github.com/warner/magic\-wormhole) +to verify the code phrases and securely communicate the P2P addresses of +the repositories, so you will need it installed on both computers that are +being paired. +.IP +This feature was present in a broken form in git-annex versions +before version 6.20180705. Make sure that a new enough git-annex +is installed on both computers that are being paired. +.IP +.IP "\fB\-\-gen\-addresses\fP" +Generates addresses that can be used to access this git-annex repository +over the available P2P networks. The address or addresses is output to +stdout. +.IP +Note that anyone who knows these addresses can access your +repository over the P2P networks. +.IP +This can be run repeatedly, in order to give different addresses +out to different people. +.IP +.IP "\fB\-\-link\fP" +Sets up a git remote that is accessed over a P2P network. +.IP +This will prompt for an address to be entered; you should paste in the +address that was generated by \-\-gen\-addresses in the remote repository. +.IP +Defaults to making the git remote be named "peer1", "peer2", +etc. This can be overridden with the \fB\-\-name\fP option. +.IP +.IP "\fB\-\-name\fP" +Specify a name to use when setting up a git remote with \fB\-\-link\fP +or \fB\-\-pair\fP. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-enable\-tor(1) +.PP +git-annex\-remotedaemon(1) +.PP +wormhole(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-p2phttp.1 b/man/git-annex-p2phttp.1 new file mode 100644 index 0000000000..94ab832554 --- /dev/null +++ b/man/git-annex-p2phttp.1 @@ -0,0 +1,179 @@ +.TH git-annex-p2phttp 1 +.SH NAME +git-annex\-p2phttp \- HTTP server for the git-annex API +.PP +.SH SYNOPSIS +git-annex p2phttp +.PP +.SH DESCRIPTION +This is a HTTP server for the git-annex API. +It is the git-annex equivilant of git\-http\-backend(1), for serving +a repository over HTTP with write access for authenticated users. +.PP +This does not serve a git repository over HTTP, only the git-annex +API. +.PP +By default, this serves the git-annex API for the git-annex repository +in the current working directory. It can also serve more than one +repository, see the \fB\-\-directory\fP parameter. +.PP +Typically a remote will have \fBremote.name.url\fP set to a http url +as usual, and \fBremote.name.annexUrl\fP set to an annex+http url such as +"annex+http://example.com/git-annex/". The annex+http url is +served by this server, and uses port 9417 by default. +.PP +Note that, when \fBremote.name.url\fP and \fBremote.name.annexUrl\fP +contain the same hostname, they are assumed by git-annex to +support the same users and passwords. So, git-annex will use +the password for the \fBremote.name.url\fP to log into the +\fBremote.name.annexUrl\fP. +.PP +As well as serving the git-annex HTTP API, this server provides a +convenient way to download the content of any key, by using the path +"/git-annex/$uuid/$key". For example: +.PP + $ curl http://example.com:9417/git-annex/f11773f0\-11e1\-45b2\-9805\-06db16768efe/key/SHA256E\-s6\-\-5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 + hello +.PP +.SH OPTIONS +.IP "\fB\-\-directory=path\fP" +.IP +Serve each git-annex repository found in immediate +subdirectories of a directory. +.IP +This option can be provided more than once to serve several directories +full of git-annex repositories. +.IP +New git-annex repositories can be added to the directory, and will be +noticed and served immediately. There is no need to restart the server. +.IP +When a git-annex repository is removed from the directory, the server +will stop serving it as well. This may not be immediate, as some files +in the deleted repository may still be open. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +This or annex.jobs must be set to configure the number of worker +threads, per repository served, that serve connections to the webserver. +.IP +Since the webserver itself also uses one of these threads, +this needs to be set to 2 or more. +.IP +A good choice is often one worker per CPU core: \fB\-\-jobs=cpus\fP +.IP +.IP "\fB\-\-proxyconnections=N\fP" +When serving a repository that is configured to act as a proxy for some +of its remotes, this is the maximum number of idle connections to keep +open to proxied remotes. +.IP +The default is 1. +.IP +.IP "\fB\-\-clusterjobs=N\fP" +When serving a repository that is a gateway for a cluster, +this is the number of concurrent jobs to use to access nodes of the +cluster, per connection to the webserver. +.IP +The default is 1. +.IP +A good choice for this will be a balance between the number of nodes +in the cluster and the value of \fB\-\-jobs\fP. +.IP +For example, if the cluster has 4 nodes, and \fB\-\-jobs=4\fP, using +\fB\-\-clusterjobs=4\fP will make all nodes in the cluster be accessed +concurrently, which is often optimal. But around 20 cores can be needed +when the webserver is busy. +.IP +.IP "\fB\-\-port=N\fP" +Port to listen on. The default is port 9417, which is the default +port used for an annex+http or annex+https url. +.IP +It is not recommended to run this command as root in order to +use a low port like port 80. It will not drop permissions when run as +root. +.IP +.IP "\fB\-\-bind=address\fP" +What address to bind to. The default is to bind to all addresses. +.IP +.IP "\fB\-\-certfile=filename\fP " +TLS certificate file to use. Combining this with \fB\-\-privatekeyfile\fP +makes the server use HTTPS. +.IP +.IP "\fB\-\-privatekeyfile=filename\fP" +TLS private key file to use. Combining this with \fB\-\-certfile\fP +makes the server use HTTPS. +.IP +.IP "\fB\-\-chainfile=filename\fP" +TLS chain file to use. This option can be repeated any number of times. +.IP +.IP "\fB\-\-authenv\fP" +Allows users to be authenticated with a username and password. +For security, this only allows authentication when the user connects over +HTTPS. +.IP +To configure the passwords, set environment variables +like \fBGIT_ANNEX_P2PHTTP_PASSWORD_alice=foo123\fP +.IP +The permissions of users can also be configured by setting +environment variables like +\fBGIT_ANNEX_P2PHTTP_PERMISSIONS_alice=readonly\fP. The value +can be either "readonly" or "appendonly". When this is not set, +the default is to give the user full read+write+remove access. +.IP +.IP "\fB\-\-authenv\-http\fP" +Like \fB\-\-authenv\fP, but allows authentication when the user connects +over HTTP. This is not secure, since HTTP basic authentication is not +encrypted. +.IP +.IP "\fB\-\-unauth\-readonly\fP" +Allows unauthenticated users to read the repository, but not make +modifications to it. +.IP +This can be combined with \fB\-\-authenv\fP or \fB\-\-authenv\-http\fP to allow +anonymous readonly access, and authenticated write access. +.IP +.IP "\fB\-\-unauth\-appendonly\fP" +Allows unauthenticated users to read the repository, and store data in +it, but not remove data from it. +.IP +This can be combined with \fB\-\-authenv\fP or \fB\-\-authenv\-http\fP to allow +anonymous appendonly access, and authenticated remove access. +.IP +.IP "\fB\-\-unauth\-nolocking\fP" +By default, when \fB\-\-unauth\-readonly\fP or \fB\-\-unauth\-appendonly\fP is used, +unauthenticated users are allowed to lock content in the repository. +This option prevents that. +.IP +Locking content prevents it from being dropped from the repository +so it may be that an unauthenticated user abuses that, and this option +can be used in such a situation. +.IP +Note that enabling this option will prevent unauthenticated users from +dropping content from their other remotes in some cases. +.IP +.IP "\fB\-\-wideopen\fP" +Gives unauthenticated users full read+write+remove access to the +repository. +.IP +Please think carefully before enabling this option. +.IP +.SH SEE ALSO +git-annex(1) +.PP +git\-http\-backend(1) +.PP +git-annex\-shell(1) +.PP +git-annex\-updateproxy(1) +.PP +git-annex\-initcluster(1) +.PP +git-annex\-updatecluster(1) +.PP + +.PP +.SH AUTHOR +Joey Hess +.PP + +.PP +.PP + diff --git a/man/git-annex-post-receive.1 b/man/git-annex-post-receive.1 new file mode 100644 index 0000000000..ade0c21138 --- /dev/null +++ b/man/git-annex-post-receive.1 @@ -0,0 +1,39 @@ +.TH git-annex-post-receive 1 +.SH NAME +git-annex-post\-receive \- run by git post\-receive hook +.PP +.SH SYNOPSIS +git annex post\-receive +.PP +.SH DESCRIPTION +This is meant to be called from git's post\-receive hook. \fBgit annex init\fP +automatically creates a post\-receive hook using this. +.PP +When a repository is configured with receive.denyCurrentBranch=updateInstead, +pushes to the repository update its work tree. However, that does not work +for repositories that have an adjusted branch checked +out. The hook updates the work tree when run in such a repository, +the same as running \fBgit-annex merge\fP would. +.PP +When a repository is configured to proxy to a special remote with +exporttree=yes, and the configured remote.name.annex\-tracking\-branch +is received, the hook handles updating the tree exported to the +special remote. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-adjust(1) +.PP +git-annex\-merge(1) +.PP +git-annex\-export(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-pre-commit.1 b/man/git-annex-pre-commit.1 new file mode 100644 index 0000000000..aef78a909f --- /dev/null +++ b/man/git-annex-pre-commit.1 @@ -0,0 +1,28 @@ +.TH git-annex-pre-commit 1 +.SH NAME +git-annex-pre\-commit \- run by git pre\-commit hook +.PP +.SH SYNOPSIS +git annex pre\-commit \fB[path ...]\fP +.PP +.SH DESCRIPTION +This is meant to be called from git's pre\-commit hook. \fBgit annex init\fP +automatically creates a pre\-commit hook using this. +.PP +Fixes up symlinks that are staged as part of a commit, to ensure they +point to annexed content. +.PP +When in a view, updates metadata to reflect changes +made to files in the view. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-preferred-content.1 b/man/git-annex-preferred-content.1 new file mode 100644 index 0000000000..3e1fa77dfb --- /dev/null +++ b/man/git-annex-preferred-content.1 @@ -0,0 +1,411 @@ +.TH git-annex-preferred-content 1 +.SH NAME +git-annex\-preferred\-content \- which files are wanted in a repository +.PP +.SH DESCRIPTION +Each repository has a preferred content setting, which specifies content +that the repository wants to have present. These settings can be configured +using \fBgit annex vicfg\fP or \fBgit annex wanted\fP. +They are used by the \fB\-\-auto\fP option, by \fBgit annex sync \-\-content\fP, +by clusters, and by the git-annex assistant. +.PP +While preferred content expresses a preference, it can be overridden +by simply using \fBgit annex drop\fP. On the other hand, required content +settings are enforced; \fBgit annex drop\fP will refuse to drop a file if +doing so would violate its required content settings. A repository's +required content can be configured using \fBgit annex vicfg\fP or +\fBgit annex required\fP. +.PP +.SH SYNTAX +Preferred content expressions use a similar syntax to +the git-annex\-matching\-options(1), without the dashes. +For example: +.PP + exclude=archive/* and (include=*.mp3 or smallerthan=1mb) +.PP +The idea is that you write an expression that files are matched against. If +a file matches, the repository wants to store its content. If it doesn't, +the repository wants to drop its content (if there are enough copies +elsewhere to allow removing it). +.PP +An empty preferred content expression is treated the same as preferred +content not being configured. +.PP +.SH EXPRESSIONS +.IP "\fBinclude=glob\fP / \fBexclude=glob\fP" +.IP +Match files to include, or exclude. +.IP +While the command\-line options \-\-include=glob and \-\-exclude=glob match +files relative to the current directory, preferred content expressions +match files relative to the top of the git repository. +.IP +A glob is something like \fBfoo.*\fP or \fBb?r\fP. +Globs can also contain character classes, +like \fBfoo[Bb]ar\fP, as well as additional POSIX character classes like +\fB[[:space:]]\fP. Which is useful, since a glob in a preferred content +expression cannot contain spaces. See the \fBglob(7)\fP man page for more +about globs. +.IP +For example, suppose you put files into \fBarchive\fP directories +when you're done with them. Then you could configure your laptop to prefer +to not retain those files, like this: \fBexclude=*/archive/*\fP +.IP +When a subdirectory is being exported or imported to a special remote (see +git-annex\-export(1)) and git-annex\-import(1), these match relative +to the top of the subdirectory. +.IP +Note that, when a command is run with the \fB\-\-all\fP option, or in a bare +repository, there is no filename associated with an annexed object, +and so "include=" and "exclude=" will not match. +.IP +.IP "\fBcopies=number\fP" +Matches only files that git-annex believes to have the specified number +of copies, or more. Note that it does not check remotes to verify that +the copies still exist. +.IP +To decide if content should be dropped, git-annex evaluates the preferred +content expression under the assumption that the content has *already* been +dropped. If the content would not be wanted then, the drop can be done. +So, for example, \fBcopies=2\fP in a preferred content expression lets +content be dropped only when there are currently 3 copies of it, including +the repo it's being dropped from. This is different than running git annex +drop \-\-copies=2, which will drop files that currently have 2 copies. +.IP +.IP "\fBcopies=trustlevel:number\fP" +Matches only files that git-annex believes have the specified number +copies, on remotes with the specified trust level. For example, +\fBcopies=trusted:2\fP +.IP +To match any trust level at or higher than a given level, +use \fBtrustlevel+\fP. For example, \fBcopies=semitrusted+:2\fP +.IP +.IP "\fBcopies=groupname:number\fP" +Matches only files that git-annex believes have the specified number of +copies, on remotes in the specified group. For example, +\fBcopies=archive:2\fP +.IP +Preferred content expressions have no equivalent to the \fB\-\-in\fP +option, but groups can accomplish similar things. You can add +repositories to groups, and match against the groups in a +preferred content expression. So rather than \fB\-\-in=usbdrive\fP, +put all the USB drives into a "transfer" group, and use +\fBcopies=transfer:1\fP +.IP +.IP "\fBlackingcopies=number\fP" +Matches only files that git-annex believes need the specified number or +more additional copies to be made in order to satisfy their numcopies +settings. +.IP +.IP "\fBapproxlackingcopies=number\fP" +Like lackingcopies, but does not look at .gitattributes annex.numcopies +settings. This makes it significantly faster. +.IP +.IP "\fBinbackend=backendname\fP" +Matches only files whose content is stored using the specified key\-value +backend. +.IP +See git-annex\-backends(1) for information about available backends. +.IP +.IP "\fBsecurehash\fP" +Matches only files whose content is hashed using a cryptographically +secure function. +.IP +.IP "\fBinallgroup=groupname\fP" +Matches only files that git-annex believes are present in all repositories +in the specified group. +.IP +.IP "\fBonlyingroup=groupname\fP" +Matches files that git-annex believes are present in at least one +repository that is in the specified group, and are not present in any +repositories that are not in the specified group. +.IP +.IP "\fBsmallerthan=size\fP / \fBlargerthan=size\fP" +Matches only files whose content is smaller than, or larger than the +specified size. +.IP +The size can be specified with any commonly used units, for example, +"0.5 gb" or "100 KiloBytes" +.IP +.IP "\fBmetadata=field=glob\fP" +Matches only files that have a metadata field attached with a value that +matches the glob. The values of metadata fields are matched case +insensitively. +.IP +A glob is something like \fBfoo.*\fP or \fBb?r\fP. +Globs can also contain character classes, +like \fBfoo[Bb]ar\fP, as well as additional POSIX character classes like +\fB[[:space:]]\fP. Which is useful, since a glob in a preferred content +expression cannot contain spaces. See the \fBglob(7)\fP man page for more +about globs. +.IP +To match a tag "done", use \fBmetadata=tag=done\fP +.IP +To match author metadata, use \fBmetadata=author=*Smith\fP +.IP +.IP "\fBmetadata=fieldnumber\fP " +.IP "\fBmetadata=field<=number\fP / \fBmetadata=field>=number\fP" +Matches only files that have a metadata field attached with a value that +is a number and is less than or greater than the specified number. +.IP +To match PDFs with between 100 and 200 pages (assuming something has set +that metadata), use \fBmetadata=pagecount>=100 and metadata=pagecount<=200\fP +.IP +.IP "\fBpresent\fP" +Makes content be wanted if it's present, but not otherwise. +.IP +This leaves it up to you to use git-annex manually +to move content around. You can use this to avoid preferred content +settings from affecting a subdirectory. For example: +\fBauto/* or (include=ad\-hoc/* and present)\fP +.IP +Note that \fBnot present\fP is not a reasonable thing to put in a preferred +content expression. It says to get content that's not present, but then +drop it! If that somehow gets into a preferred content expression, +git-annex will recognize that the preferred content expression is not stable, +and make it never match. +.IP +.IP "\fBinpreferreddir\fP" +Makes content be preferred if it's in a directory (located anywhere +in the tree) with a particular name. +.IP +The name of the directory can be configured using +\fBgit annex enableremote $remote preferreddir=$dirname\fP +.IP +(If no directory name is configured, it uses "public" by default.) +.IP +Note that, when a command is run with the \fB\-\-all\fP option, or in a bare +repository, there is no filename associated with an annexed object, +and so "inpreferreddir" will not match. +.IP +.IP "\fBstandard\fP" +git-annex comes with some built\-in preferred content expressions, that +can be used with repositories that are in some standard groups +such as "client" and "transfer". +.IP +When a repository is in exactly one such group, you can use the "standard" +keyword in its preferred content expression, to match whatever content +the group's expression matches. +.IP +Most often, the whole preferred content expression is simply "standard". +But, you can do more complicated things, for example: +\fBstandard or include=otherdir/*\fP +.IP +.IP "\fBgroupwanted\fP" +The "groupwanted" keyword can be used to refer to a preferred content +expression that is associated with a group, as long as there is exactly +one such expression amoung the groups a repository is in. This is like +the "standard" keyword, but you can configure the preferred content +expressions using \fBgit annex groupwanted\fP. +.IP +When writing a groupwanted preferred content expression, +you can use all the keywords documented here, including "standard". +(But not "groupwanted".) +.IP +For example, to make a variant of the standard client preferred content +expression that does not want files in the "out" directory, you +could run: \fBgit annex groupwanted client "standard and exclude=out/*"\fP +.IP +Then repositories that are in the client group and have their preferred +content expression set to "groupwanted" will use that, while +other client repositories that have their preferred content expression +set to "standard" will use the standard expression. +.IP +Or, you could make a new group, with your own custom preferred content +expression tuned for your needs, and every repository you put in this +group and make its preferred content be "groupwanted" will use it. +.IP +For example, the archive group only wants to archive 1 copy of each file, +spread among every repository in the group. +Here's how to configure a group named redundantarchive, that instead +wants to contain 3 copies of each file: +.IP + git annex groupwanted redundantarchive "not (copies=redundantarchive:3)" + for repo in foo bar baz; do + git annex group $repo redundantarchive + git annex wanted $repo groupwanted + done +.IP +.IP "\fBunused\fP" +Matches only keys that \fBgit annex unused\fP has determined to be unused. +.IP +This is related the the \-\-unused option. +However, putting \fBunused\fP in a preferred content expression +doesn't make git-annex consider those unused keys. So when git-annex is +only checking preferred content expressions against files in the +repository (which are obviously used), \fBunused\fP in a preferred +content expression won't match anything. +.IP +So when is \fBunused\fP useful in a preferred content expression? +.IP +Using \fBgit annex sync \-\-content \-\-all\fP will operate on all files, +including unused ones, and take \fBunused\fP in preferred content expressions +into account. +.IP +The git-annex assistant periodically scans for unused files, and +moves them to some repository whose preferred content expression +says it wants them. (Or, if annex.expireunused is set, it may just delete +them.) +.IP +.IP "\fBbalanced=groupname[:number]\fP" +Makes content be evenly balanced amoung repositories in the group. +.IP +The number is the number of repositories in the group that will +want each file. When not specified, the default is 1. +.IP +For example, "balanced=backup:2", when there are 3 members of the backup +group, will make each backup repository want 2/3rds of the files. +.IP +For this to work, each repository in the group should have its preferred +content set to the same expression. Using \fBgroupwanted\fP is a good +way to do that. +.IP +The sizes of files are not taken into account, so it's possible for +one repository to get larger than usual files and so fill up before +the other repositories. But files are only wanted by repositories that +have enough free space to hold them. So once a repository is full, +the remaining repositories will have any additional files balanced +amoung them. For git-annex to know when a repository is full, +you must use git-annex\-maxsize(1) to specify the size of each +repository in the group. +.IP +This usually avoids moving files between repositories, even +if that means that things are not optimally balanced. Some of the ways +that it can get out of balance include adding a new repository to the +group, or a file getting copied into more repositories in the +group than the specified number, or some of the repositories filling up. +.IP +Running git-annex commands with the \fB\-\-rebalance\fP option will make this +expression instead behave like the \fBfullybalanced\fP expression, which will +make repositories want to move files around as necessary in order to get +fully balanced. +.IP +Using this in a preferred content expression makes git-annex need to do +some additional work to keep track of how full repositories are. Usually +that won't affect performance much. However, the first time git-annex +processes this expression in a given git repository, it will need to +calculate the sizes of all repositories, which can be slow when there are +a lot of files. When this causes git-annex to do a lot of work, it will +display "(calculating repository sizes)". +.IP +Note that \fBnot balanced\fP not a reasonable thing to use in a preferred +content expression for the same reasons as \fBnot present\fP. +.IP +.IP "\fBfullybalanced=groupname[:number]\fP" +This is like \fBbalanced\fP, but allows moving content between repositories +in the group at any time to keep it fully balanced. +.IP +Normally "balanced=groupname:number" is the same as +"(fullybalanced=groupname:number and not copies=groupname:number) or present" +.IP +When the \fB\-\-rebalance\fP option is used, \fBbalanced\fP is the same as +\fBfullybalanced\fP. +.IP +When the specified number is greater than 1, and too many repositories +in the group are more than 90% full (as configured by +annex.fullybalancedthreshhold), this behaves like \fBfullysizebalanced\fP. +.IP +For example, \fBfullybalanced=foo:3\fP, when group foo has 5 repositories, +two 50% full and three 99% full, will make some content move from the +full repositories to the others. Moving content like that is expensive, +but it allows new files to continue to be stored on the specified number +of repositories. +.IP +.IP "\fBsizebalanced=groupname:number\fP" +Distributes content amoung repositories in the group, keeping +repositories proportionally full. +.IP +The number is the number of repositories in the group that will +want each file. When not specified, the default is 1. +.IP +For this to work, you must use git-annex\-maxsize(1) to specify +the size of each repository in the group. When a repository's +maxsize has not been specified, it will not want any files. +.IP +For example, if one repository in the group has a maximum size of +100 gb with 60 gb used, and another has a maximum size of 50 gb with +25 gb used, the smaller one will want files (that fit in it), +and the larger one won't want any files +(that would fit in the smaller one) +until the smaller one gets equally full. +.IP +Note that, once a repository contains a file, it will continue to want +it, even if it's more full than other repositories. This is to avoid +churn in moving files around. +.IP +This is more likely to get out of balance than the \fBbalanced=\fP expression +is, because git-annex does not always have a consistent knowledge of +how full repositories are. Consider for example if a laptop and a desktop +are each sending a new file to the group. They will both pick whichever +repository was least full, but that means both files go to the same +repository, when a better solution might have been to send the smaller +file to a different repository. When using \fBbalanced=\fP in the same +situation, it's less likely that a repository will want both files. +.IP +Running git-annex commands with the \fB\-\-rebalance\fP option will make this +expression instead behave like the \fBfullysizebalanced\fP expression, which +will make repositories want to move files around as necessary in order to +get fully balanced. +.IP +Note that \fBnot sizebalanced\fP not a reasonable thing to use in a preferred +content expression for the same reasons as \fBnot present\fP. +.IP +.IP "\fBfullysizebalanced=groupname:number\fP" +This is like \fBsizebalanced\fP, but allows moving content between repositories +in the group at any time to keep it fully balanced. +.IP +Normally "sizebalanced=groupname:number" is the same as +"(fullysizebalanced=groupname:number and not copies=groupname:number) or present" +.IP +When the \fB\-\-rebalance\fP option is used, \fBsizebalanced\fP is the same as +\fBfullysizebalanced\fP. +.IP +.IP "\fBanything\fP" +Always matches. +.IP +.IP "\fBnothing\fP" +Never matches. (Same as "not anything") +.IP +.IP "\fBnot expression\fP" +Inverts what the expression matches. For example, \fBnot include=archive/*\fP +is the same as \fBexclude=archive/*\fP +.IP +.IP "\fBand\fP / \fBor\fP / \fB( expression )\fP" +These can be used to build up more complicated expressions. +.IP +.SH TESTING +To check at the command line which files are matched by a repository's +preferred content settings, you can use the \-\-want\-get and \-\-want\-drop +options. +.PP +For example, git annex find \-\-want\-get \-\-not \-\-in . will find all the files +that git annex get \-\-auto will want to get, and git annex find \-\-want\-drop \-\-in +\&. will find all the files that git annex drop \-\-auto will want to drop. +.PP +The \-\-explain option can be used to understand why a complex preferred +content expression matches or fails to match. The expression will +be displayed, with each term followed by "[TRUE]" or "[FALSE]" to indicate +the value. Irrelevant terms will be ommitted from the explanation, +for example \fB"exclude=* and copies=1"\fP will be displayed as +\fB"exclude=*[FALSE]"\fP +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-vicfg(1) +.PP +git-annex\-wanted(1) +.PP +git-annex\-maxsize(1) +.PP + +.PP + +.PP +.SH AUTHOR +Joey Hess +.PP + +.PP +.PP + diff --git a/man/git-annex-proxy.1 b/man/git-annex-proxy.1 new file mode 100644 index 0000000000..086230d65e --- /dev/null +++ b/man/git-annex-proxy.1 @@ -0,0 +1,22 @@ +.TH git-annex-proxy 1 +.SH NAME +git-annex-proxy \- safely bypass direct mode guard (deprecated) +.PP +.SH SYNOPSIS +git annex proxy \fB\-\- git cmd [options]\fP +.PP +.SH DESCRIPTION +This command was for use in a direct mode repository, and such +repositories are automatically updated to use an adjusted unlocked branch. +So, there's no reason to use this command any longer. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-direct(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-pull.1 b/man/git-annex-pull.1 new file mode 100644 index 0000000000..e281ddb958 --- /dev/null +++ b/man/git-annex-pull.1 @@ -0,0 +1,139 @@ +.TH git-annex-pull 1 +.SH NAME +git-annex-pull \- pull content from remotes +.PP +.SH SYNOPSIS +git annex pull \fB[remote ...]\fP +.PP +.SH DESCRIPTION +This command pulls content from remotes. It downloads +both git repository content, and the content of annexed files. +Like \fBgit pull\fP, it merges changes into the current branch. +.PP +You can use \fBgit pull\fP and \fBgit-annex get\fP by hand to do the same thing as +this command, but this command handles several details, including making +sure that the git-annex branch is fetched from the remote. +.PP +Some special remotes contain a tree of files that can be imported, +and this command can be used to pull from those remotes as +well as regular git remotes. See git-annex\-import(1) for details +about how those special remotes work. In order for this command to import +from a special remote, \fBremote..annex\-tracking\-branch\fP also must +be configured, and have the same value as the currently checked out branch. +.PP +When git-annex\-adjust(1) has been used to check out an adjusted branch, +this command will also pull changes from the parent branch. +.PP +When git-annex\-view(1) has been used to check out a view branch, +this command will update the view branch to reflect any changes +to the parent branch or metadata. +.PP +When git-annex\-migrate(1) has been used in other repositories, +this updates the content in the local repository for those migrations as well. +.PP +Normally this tries to download the content of each annexed file, +from any remote that it's pulling from that has a copy. +To control which files it downloads, configure the preferred +content of the local repository. It will also drop files from a +remote that are not preferred content of the remote. +See git-annex\-preferred\-content(1). +.PP +.SH OPTIONS +.IP "\fB[remote]\fP" +.IP +By default this command pulls from all available remotes, except for remotes +that have \fBremote..annex\-pull\fP (or \fBremote..annex\-sync\fP) +set to false. +.IP +By specifying the names of remotes (or remote groups), you can control +which ones to pull from. +.IP +.IP "\fB\-\-fast\fP" +Only pull with the remotes with the lowest annex\-cost value configured. +.IP +When a list of remotes (or remote groups) is provided, it picks from +among those, otherwise it picks from among all remotes. +.IP +.IP "\fB\-\-only\-annex\fP \fB\-a\fP, \fB\-\-not\-only\-annex\fP" +Only pull the git-annex branch and annexed content from remotes, +not other git branches. +.IP +The \fBannex.synconlyannex\fP configuration can be set to true to make +this be the default behavior. To override such a setting, use +\fB\-\-not\-only\-annex\fP. +.IP +When this is combined with \-\-no\-content, only the git-annex branch +will be pulled. +.IP +.IP "\fB\-\-no\-content\fP, \fB\-g\fP, \fB\-\-content\fP" +Use \fB\-\-no\-content\fP or \fB\-g\fP to avoid downloading (and dropping) +the content of annexed files, and also prevent doing any migrations of +content. +.IP +If you often use \fB\-\-no\-content\fP, you can set the \fBannex.synccontent\fP +configuration to false to prevent downloading content by default. +The \fB\-\-content\fP option overrides that configuration. +.IP +To only prevent only migrations of content, you can set the +\fBannex.syncmigrations\fP configuration to false. +The \fB\-\-content\fP option overrides that configuration as well. +.IP +.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" +Only download (and drop) annexed files in the given path. +.IP +This option can be repeated multiple times with different paths. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Usually this command operates on annexed files in the current branch. +This option makes it operate on all available versions of all annexed files +(when preferred content settings allow). +.IP +Note that preferred content settings that use \fBinclude=\fP or \fBexclude=\fP +will only match the version of files currently in the work tree, but not +past versions of files. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel pulling with up to the specified number of jobs +running at once. For example: \fB\-J10\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +(Note that git pulls are not done in parallel because that tends to be +less efficient.) +.IP +.IP "\fB\-\-allow\-unrelated\-histories\fP, \fB\-\-no\-allow\-unrelated\-histories\fP" +Passed on to \fBgit merge\fP, to control whether or not to merge +histories that do not share a common ancestor. +.IP +.IP "\fB\-\-resolvemerge\fP, \fB\-\-no\-resolvemerge\fP" +By default, merge conflicts are automatically handled by this command. +When two conflicting versions of a file have been committed, both will +be added to the tree, under different filenames. For example, file "foo" +would be replaced with "foo.variant\-A" and "foo.variant\-B". (See +git-annex\-resolvemerge(1) for details.) +.IP +Use \fB\-\-no\-resolvemerge\fP to disable this automatic merge conflict +resolution. It can also be disabled by setting \fBannex.resolvemerge\fP +to false. +.IP +.IP "\fB\-\-backend\fP" +Specifies which key\-value backend to use when importing from a +special remote. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-push(1) +.PP +git-annex\-sync(1) +.PP +git-annex\-preferred\-content(1) +.PP +git-annex\-satisfy(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-push.1 b/man/git-annex-push.1 new file mode 100644 index 0000000000..3f4a912cf2 --- /dev/null +++ b/man/git-annex-push.1 @@ -0,0 +1,135 @@ +.TH git-annex-push 1 +.SH NAME +git-annex-push \- push content to remotes +.PP +.SH SYNOPSIS +git annex push \fB[remote ...]\fP +.PP +.SH DESCRIPTION +This command pushes content to remotes. It uploads +both git repository content, and the content of annexed files. +.PP +You can use \fBgit push\fP and \fBgit-annex copy\fP by hand to do the same thing as +this command, but this command handles several details, including making +sure that the git-annex branch is pushed to the remote. +.PP +When using git-annex, often remotes are not bare repositories, because +it's helpful to add remotes for nearby machines that you want +to access the same annexed content. Pushing to a non\-bare remote will +not normally update the remote's current branch with changes from the local +repository. (Unless the remote is configured with +receive.denyCurrentBranch=updateInstead.) +.PP +To make working with such non\-bare remotes easier, this command pushes not +only local \fBmaster\fP to remote \fBmaster\fP, but also to remote \fBsynced/master\fP +(and similar with other branches). When \fBgit-annex pull\fP (or git-annex +sync\fB) is later run on the remote, it will merge the \fPsynced/ branches +that were pushed to it. +.PP +Some special remotes allow exporting a tree of files to them +(\fBexporttree=yes\fP), +and this command can be used to push to those remotes as well +as regular git remotes. See git-annex\-export(1) for details +about how those special remotes work. In order for this command to export +to a special remote, \fBremote..annex\-tracking\-branch\fP also must +be configured, and have the same value as the currently checked out branch. +.PP +When git-annex\-adjust(1) has been used to check out an adjusted branch, +this command will propagate changes that have been made back to the +parent branch, without propagating the adjustments. +.PP +Normally this tries to upload the content of each annexed file that is +in the working tree, to any remote that it's pushing to that does not have +a copy. To control which files are uploaded to a remote, configure the preferred +content of the remote. When a file is not the preferred content of a remote, +or of the local repository, this command will try to drop the file's content. +See git-annex\-preferred\-content(1). +.PP +.SH OPTIONS +.IP "\fB[remote]\fP" +.IP +By default, this command pushes to all available remotes, except for remotes +that have \fBremote..annex\-push\fP (or \fBremote..annex\-sync\fP) +set to false or \fBremote..annex\-readonly\fP set to true. +.IP +By specifying the names of remotes (or remote groups), you can control which +ones to push to. +.IP +.IP "\fB\-\-fast\fP" +Only push to the remotes with the lowest annex\-cost value configured. +.IP +When a list of remotes (or remote groups) is provided, it picks from +amoung those, otherwise it picks from amoung all remotes. +.IP +.IP "\fB\-\-only\-annex\fP \fB\-a\fP, \fB\-\-not\-only\-annex\fP" +Only push the git-annex branch and annexed content to remotes, +not other git branches. +.IP +The \fBannex.synconlyannex\fP configuration can be set to true to make +this be the default behavior. To override such a setting, use +\fB\-\-not\-only\-annex\fP. +.IP +When this is combined with \-\-no\-content, only the git-annex branch +will be pushed. +.IP +.IP "\fB\-\-no\-content\fP, \fB\-g\fP, \fB\-\-content\fP" +Use \fB\-\-no\-content\fP or \fB\-g\fP to avoid uploading (and dropping) the content +of annexed files. +.IP +If you often use \fB\-\-no\-content\fP, you can set the \fBannex.synccontent\fP +configuration to false to prevent uploading content by default. +The \fB\-\-content\fP option overrides that configuration. +.IP +.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" +Only upload (or drop) annexed files in the given path. +.IP +This option can be repeated multiple times with different paths. +.IP +Note that this option does not prevent exporting other files to an +"exporttree=yes" remote. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Usually this command operates on annexed files in the current branch. +This option makes it operate on all available versions of all annexed files +(when preferred content settings allow). +.IP +Note that preferred content settings that use \fBinclude=\fP or \fBexclude=\fP +will only match the version of files currently in the work tree, but not +past versions of files. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel pushing with up to the specified number of jobs +running at once. For example: \fB\-J10\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-cleanup\fP" +Removes the local and remote \fBsynced/\fP branches, which were created +and pushed by \fBgit-annex push\fP or \fBgit-annex sync\fP. This option +prevents all other activities. +.IP +This can come in handy when you've pushed a change to remotes and now +want to reset your master branch back before that change. So you +run \fBgit reset\fP and force\-push the master branch to remotes, only +to find that the next \fBgit annex merge\fP or \fBgit annex pull\fP brings the +changes back. Why? Because the \fBsynced/master\fP branch is hanging +around and still has the change in it. Cleaning up the \fBsynced/\fP branches +prevents that problem. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-pull(1) +.PP +git-annex\-sync(1) +.PP +git-annex\-preferred\-content(1) +.PP +git-annex\-satisfy(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-readpresentkey.1 b/man/git-annex-readpresentkey.1 new file mode 100644 index 0000000000..5d63b64646 --- /dev/null +++ b/man/git-annex-readpresentkey.1 @@ -0,0 +1,28 @@ +.TH git-annex-readpresentkey 1 +.SH NAME +git-annex-readpresentkey \- read records of where key is present +.PP +.SH SYNOPSIS +git annex readpresentkey \fBkey uuid\fP +.PP +.SH DESCRIPTION +This plumbing\-level command reads git-annex's records about whether +the specified key's content is present in the remote with the specified +uuid. +.PP +It exits 0 if the key is recorded to be present and 1 if not. +.PP +Note that this does not do an active check to verify if the key +is present. To do such a check, use git-annex\-checkpresentkey(1) +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-recompute.1 b/man/git-annex-recompute.1 new file mode 100644 index 0000000000..a09afd2bc3 --- /dev/null +++ b/man/git-annex-recompute.1 @@ -0,0 +1,65 @@ +.TH git-annex-recompute 1 +.SH NAME +git-annex-recompute \- recompute computed files +.PP +.SH SYNOPSIS +git-annex recompute [path ...] +.PP +.SH DESCRIPTION +This updates computed files that were added with +git-annex\-addcomputed(1). +.PP +By default, this only recomputes files whose input files have changed. +The new contents of the input files are used to re\-run the computation. +.PP +When the output of the computation is different, the computed file is +updated with the new content. The updated file is staged in git. +.PP +.SH OPTIONS +.IP "\fB\-\-original\fP" +.IP +Re\-run the computation with the original input files content. +.IP +.IP "\fB\-\-remote=name\fP" +Only recompute files that were computed by this compute remote. +.IP +When this option is not used, all computed files are recomputed using +whatever compute remote was originally used to add them. (In cases where +a file can be computed by multiple remotes, the one with the lowest +configured cost is used.) +.IP +.IP "\fB\-\-unreproducible\fP, \fB\-u\fP" +Indicate that the computation is not expected to be fully reproducible. +It can vary, in ways that produce files that equivilant enough to +be interchangeable, but are not necessarily identical. +.IP +This is the default unless the compute remote indicates that it produces +reproducible output. +.IP +.IP "\fB\-\-reproducible\fP, \fB\-r\fP" +Indicate that the computation is expected to be fully reproducible. +.IP +This is the default when the compute remote indicates that it produces +reproducible output. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "matching options" +The git-annex\-matching\-options(1) can be used to control what +files to recompute. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-addcomputed(1) +.PP +git-annex\-findcomputed(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-registerurl.1 b/man/git-annex-registerurl.1 new file mode 100644 index 0000000000..418aa2c5fc --- /dev/null +++ b/man/git-annex-registerurl.1 @@ -0,0 +1,68 @@ +.TH git-annex-registerurl 1 +.SH NAME +git-annex-registerurl \- registers an url for a key +.PP +.SH SYNOPSIS +git annex registerurl \fB[key url]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command can be used to register urls where a +key can be downloaded from. +.PP +No verification is performed of the url's contents. +.PP +Normally the key is a git-annex formatted key. However, to make it easier +to use this to add urls, if the key cannot be parsed as a key, and is a +valid url, an URL key is constructed from the url. +.PP +Registering an url also makes git-annex treat the key as present in the +special remote that claims it. (Usually the web special remote.) +.PP +.SH OPTIONS +.IP "\fB\-\-remote=name|uuid\fP" +.IP +Indicate that the url is expected to be claimed by the specified remote. +If some other remote claims the url instead, registering it will fail. +.IP +Note that \fB\-\-remote=web\fP will prevent any other remote from claiming +the url. +.IP +.IP "\fB\-\-batch\fP" +In batch input mode, lines are read from stdin, and each line +should contain a key and url, separated by a single space. +.IP +For backwards compatability with old git-annex before this option +was added, when no key and url pair are specified on the command line, +batch input is used, the same as if the \-\-batch option were +specified. It is however recommended to use \-\-batch. +.IP +.IP "\fB\-z\fP" +When in batch mode, the input is delimited by nulls instead of the usual +newlines. +.IP +(Note that for this to be used, you have to explicitly enable batch mode +with \fB\-\-batch\fP) +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-addurl(1) +.PP +git-annex\-unregisterurl(1) +.PP +git-annex\-reregisterurl(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-reinit.1 b/man/git-annex-reinit.1 new file mode 100644 index 0000000000..87af987e1c --- /dev/null +++ b/man/git-annex-reinit.1 @@ -0,0 +1,46 @@ +.TH git-annex-reinit 1 +.SH NAME +git-annex-reinit \- initialize repository, reusing old UUID +.PP +.SH SYNOPSIS +git annex reinit \fBuuid|description\fP +.PP +.SH DESCRIPTION +Normally, initializing a repository generates a new, unique identifier +(UUID) for that repository. Occasionally it may be useful to reuse a +UUID \-\- for example, if a repository got deleted, and you're +setting it back up. +.PP +Use this with caution; it can be confusing to have two existing +repositories with the same UUID. +.PP +Make sure you run \fBgit annex fsck\fP after changing the UUID of a +repository to make sure location tracking information is recorded +correctly. +.PP +Like \fBgit annex init\fP, this attempts to enable any special remotes +that are configured with autoenable=true. +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-init(1) +.PP +git-annex\-fsck(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-reinject.1 b/man/git-annex-reinject.1 new file mode 100644 index 0000000000..4a10082ab3 --- /dev/null +++ b/man/git-annex-reinject.1 @@ -0,0 +1,88 @@ +.TH git-annex-reinject 1 +.SH NAME +git-annex-reinject \- inject content of file back into annex +.PP +.SH SYNOPSIS +git annex reinject \fB[src dest]\fP +.PP +git annex reinject \-\-known \fB[src]\fP +.PP +.SH DESCRIPTION +Moves the content of the src file or files into the annex. +Only known file contents will be reinjected. Any unknown src files will +be left unchanged. +.PP +This can be useful if you have obtained the content of a file from +elsewhere and want to put it in the local annex. For example, if a file's +content has been lost and you have a backup, you can restore the backup and +reinject it into your local repository. +.PP +There are two ways to use this command. Specifying a src file and the name +of a dest file (located inside the repository's working tree) +injects the src file as the content of the dest file. +.PP + git annex reinject /tmp/foo.iso foo.iso +.PP +Or the \fB\-\-known\fP option can be used to reinject all known src files, without +needing to specify the dest file. +.PP + git annex reinject \-\-known /tmp/*.iso +.PP +.SH OPTIONS +.IP "\fB\-\-known\fP" +.IP +With this option, each specified src file is hashed using the default +key\-value backend (or the one specified with \fB\-\-backend\fP), and if git-annex +has a record of the resulting key having been in the annex before, the +content is reinjected. +.IP +Note that, when using a key\-value backend that includes the filename +extension in the key, this will only work if the src files have the same +extensions as the files with the same content that was originally added +to git-annex. +.IP +Note that this will reinject old versions of files that have been +modified or deleted from the current git branch. +Use git-annex\-unused(1) to detect when such old and potentially +unused files have been reinjected. +.IP +.IP "\fB\-\-backend\fP" +Specify the key\-value backend to use when checking if a file is known +with the \fB\-\-known\fP option. +.IP +.IP "\fB\-\-guesskeys\fP" +With this option, each specified source file is checked to see if it +has the name of a git-annex key, and if so it is imported as the content +of that key. +.IP +This can be used to pluck git-annex objects out of \fBlost+found\fP, +as long as the original filename has not been lost, +and is particularly useful when using key\-value backends that don't hash +to the content of a file. +.IP +When the key\-value backend does support hashing, the content of the file +is verified before importing it. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-add(1) +.PP +git-annex\-unused(1) +.PP +git-annex\-fsck(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-rekey.1 b/man/git-annex-rekey.1 new file mode 100644 index 0000000000..0bd5290ad9 --- /dev/null +++ b/man/git-annex-rekey.1 @@ -0,0 +1,50 @@ +.TH git-annex-rekey 1 +.SH NAME +git-annex-rekey \- change keys used for files +.PP +.SH SYNOPSIS +git annex rekey \fB[file key ...]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command is similar to migrate, but you specify +both the file, and the new key to use for it. +.PP +Multiple pairs of file and key can be given in a single command line. +.PP +Note that, unlike \fBgit-annex migrate\fP, this does not copy over metadata, +urls, and other such information from the old to the new key +.PP +.SH OPTIONS +.IP "\fB\-\-force\fP" +.IP +Allow rekeying of even files whose content is not currently available. +Use with caution. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which lines are read from stdin. +Each line should contain the file, and the new key to use for that file, +separated by a single space. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-migrate(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-remotedaemon.1 b/man/git-annex-remotedaemon.1 new file mode 100644 index 0000000000..ced7394e99 --- /dev/null +++ b/man/git-annex-remotedaemon.1 @@ -0,0 +1,53 @@ +.TH git-annex-remotedaemon 1 +.SH NAME +git-annex-remotedaemon \- persistent communication with remotes +.PP +.SH SYNOPSIS +git annex remotedaemon +.PP +.SH DESCRIPTION +The remotedaemon provides persistent communication with remotes. +.PP +Several types of remotes are supported: +.PP +For ssh remotes, the remotedaemon tries to maintain a connection to the +remote git repository, and uses git-annex\-shell notifychanges to detect +when the remote git repository has changed, and fetches changes from it. +For this to work, the git remote must have git-annex\-shell(1) +installed, with notifychanges support. The first version of git-annex\-shell +that supports it is 5.20140405. +.PP +For tor\-annex remotes, the remotedaemon runs a tor hidden service, +accepting connections from other nodes and serving up the contents of the +repository. This is only done if you first run \fBgit annex enable\-tor\fP. +Use \fBgit annex p2p\fP to configure access to tor\-annex remotes. +.PP +Note that when \fBremote..annex\-pull\fP is set to false, the remotedaemon +will avoid fetching changes from that remote. +.PP +.SH OPTIONS +.IP "\fB\-\-foreground\fP" +.IP +Don't fork to the background, and communicate on stdin/stdout using a +simple textual protocol. The assistant runs the remotedaemon this way. +.IP +Commands in the protocol include LOSTNET, which tells the remotedaemon +that the network connection has been lost, and causes it to stop any TCP +connctions. That can be followed by RESUME when the network connection +comes back up. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-assistant(1) +.PP +git-annex\-enable\-tor(1) +.PP +git-annex\-p2p(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-renameremote.1 b/man/git-annex-renameremote.1 new file mode 100644 index 0000000000..57c88fdcb8 --- /dev/null +++ b/man/git-annex-renameremote.1 @@ -0,0 +1,43 @@ +.TH git-annex-renameremote 1 +.SH NAME +git-annex-renameremote \- changes name of a special remote +.PP +.SH SYNOPSIS +git annex renameremote \fBname|uuid|desc newname\fP +.PP +.SH DESCRIPTION +Changes the name that is used to enable a special remote. +.PP +Normally the current name is used to identify the special remote to rename, +but its uuid or description can also be used. +.PP +This is especially useful when an old special remote used a name, and now you +want to use that name for a new special remote. \fBgit annex initremote\fP +won't let you create a remote with a conflicting name, so rename the old +remote first. +.PP + git annex renameremote phone lost\-phone + git annex initremote phone ... +.PP +This only updates the name that git-annex has stored for use +by \fBgit annex enableremote\fP. It does not update the git config stanza +for the special remote to use the new name, but of course you can edit +the git config if you want to rename it there. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-initremote(1) +.PP +git-annex\-enableremote(1) +.PP +git-annex\-configremote(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-repair.1 b/man/git-annex-repair.1 new file mode 100644 index 0000000000..3ceec9713e --- /dev/null +++ b/man/git-annex-repair.1 @@ -0,0 +1,54 @@ +.TH git-annex-repair 1 +.SH NAME +git-annex-repair \- recover broken git repository +.PP +.SH SYNOPSIS +git annex repair +.PP +.SH DESCRIPTION +This can repair many of the problems with git repositories that \fBgit fsck\fP +detects, but does not itself fix. It's useful if a repository has become +badly damaged. One way this can happen is if a repository used by git-annex +is on a removable drive that gets unplugged at the wrong time. +.PP +This command can actually be used inside git repositories that do not +use git-annex at all; when used in a repository using git-annex, it +does additional repairs of the git-annex branch. +.PP +It works by deleting any corrupt objects from the git repository, and +retrieving all missing objects it can from the remotes of the repository. +.PP +If that is not sufficient to fully recover the repository, it can also +reset branches back to commits before the corruption happened, delete +branches that are no longer available due to the lost data, and remove any +missing files from the index. It will only do this if run with the +\fB\-\-force\fP option, since that rewrites history and throws out missing data. +Note that the \fB\-\-force\fP option never touches tags, even if they are no +longer usable due to missing data. +.PP +After running this command, you will probably want to run \fBgit fsck\fP to +verify it fixed the repository. Note that fsck may still complain about +objects referenced by the reflog, or the stash, if they were unable to be +recovered. This command does not try to clean up either the reflog or the +stash. +.PP +It is also a good idea to run \fBgit annex fsck \-\-fast\fP after this command, +to make sure that the git-annex branch reflects reality. +.PP +.SH OPTIONS +.IP "\fB\-\-force\fP" +.IP +Enable repair actions that involve deleting data that has been +lost due to git repository corruption. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-fsck(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-required.1 b/man/git-annex-required.1 new file mode 100644 index 0000000000..ffb971d21b --- /dev/null +++ b/man/git-annex-required.1 @@ -0,0 +1,49 @@ +.TH git-annex-required 1 +.SH NAME +git-annex-required \- get or set required content expression +.PP +.SH SYNOPSIS +git annex required \fBrepository [expression]\fP +.PP +.SH DESCRIPTION +When run with an expression, configures the content that is required +to be held in the repository. +.PP +Without an expression, displays the current required content setting +of the repository. +.PP +While git-annex\-wanted(1) is just a preference, this designates content +that should really not be removed. For example a file that is \fBwanted\fP can +be removed with \fBgit annex drop\fP, but if that file is \fBrequired\fP, it would +need to be removed with \fBgit annex drop \-\-force\fP. +.PP +Also, \fBgit-annex fsck\fP will warn about required contents that are not +present. +.PP +For example: +.PP + git annex required here "include=*.mp3 or include=*.ogg" +.PP +To return a repository to the original default behavior, use an empty +value for the expression, eg: +.PP +git-annex required here "" +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH NOTES +The \fBrequired\fP command was added in git-annex 5.20150420. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-wanted(1) +.PP +git-annex\-preferred\-content(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-reregisterurl.1 b/man/git-annex-reregisterurl.1 new file mode 100644 index 0000000000..c4226a1a79 --- /dev/null +++ b/man/git-annex-reregisterurl.1 @@ -0,0 +1,55 @@ +.TH git-annex-reregisterurl 1 +.SH NAME +git-annex-reregisterurl \- updates url registration information +.PP +.SH SYNOPSIS +git annex reregisterurl \fB[key]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command updates information about the urls that are +registered for a key. +.PP +.SH OPTIONS +.IP "\fB\-\-move\-from=name|uuid\fP" +.IP +For each key, update any urls that are currently claimed by the +specified remote to be instead used by the web special remote. +.IP +This could be used eg, when a special remote was needed to provide +authorization to get an url, but the url has now become publically +available and so the web special remote can be used. +.IP +Note that, like \fBgit-annex unregisterurl\fP, using this option unregisters +an url from a special remote, but it does not mark the content as not +present in that special remote. However, like \fBgit-annex registerurl\fP, +this option does mark content as being present in the web special remote. +.IP +.IP "\fB\-\-batch\fP" +In batch input mode, lines are read from stdin, and each line +should contain a key. +.IP +.IP "\fB\-z\fP" +When in batch mode, the input is delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-registerurl(1) +.PP +git-annex\-unregisterurl(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-resolvemerge.1 b/man/git-annex-resolvemerge.1 new file mode 100644 index 0000000000..d8e234533b --- /dev/null +++ b/man/git-annex-resolvemerge.1 @@ -0,0 +1,65 @@ +.TH git-annex-resolvemerge 1 +.SH NAME +git-annex-resolvemerge \- resolve merge conflicts +.PP +.SH SYNOPSIS +git annex resolvemerge +.PP +.SH DESCRIPTION +Automatically resolves a conflicted merge. This is done +automatically when using \fBgit annex sync\fP or \fBgit annex merge\fP. +.PP +When two trees being merged contain conflicting versions of an annexed +file, the merge conflict will be resolved by adding both versions to the +tree, using variants of the filename. +.PP +When one tree modified the file, and the other tree deleted the file, +the merge conflict will be resolved by adding the modified file using a +variant of the filename, leaving the original filename deleted. +.PP +When the merge conflict involves a file that is annexed in one +tree, but is not annexed in the other tree, it is +resolved by keeping the non\-annexed file as\-is, and adding the annexed +version using a variant of the filename. +.PP +Note that only merge conflicts that involve one or more annexed files +are resolved. Merge conflicts between two files that are not annexed +will not be automatically resolved. +.PP +.SH EXAMPLES +Suppose Alice commits a change to annexed file \fBfoo\fP, and Bob commits +a different change to the same file \fBfoo\fP. +.PP +Merging between them will then fail, and git will present the +merge conflict as a file \fBfoo\fP pointing to one version of the +git-annex symlink, with \fBgit status\fP indicating that \fBfoo\fP has an +unresolved conflict. +.PP +Running \fBgit annex resolvemerge\fP in this situation will resolve the merge +conflict, by replacing the file \fBfoo\fP with files named like +\fBfoo.variant\-c696\fP and \fBfoo.variant\-f16a\fP. One of the files has the content +that Alice committed, and the other has the content that Bob committed. +.PP +The user can then examine the two variants of the file, and either merge +the two changes into a single file, or rename one of them back to \fBfoo\fP +and delete the other. +.PP +Now suppose Alice commits a change to annexed file \fBbar\fP, while Bob commits +a deletion of the same file \fBbar\fP. Merging will fail. Running +\fBgit annex resolvemerge\fP in this situation will resolve the merge conflict +by making a file with a name like \fBbar.variant\-421f\fP containing Alice's +version. The \fBbar\fP file remains deleted. The user can later examine the +variant of the file and either rename it back to \fBbar\fP, or decide to delete +it too. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-restage.1 b/man/git-annex-restage.1 new file mode 100644 index 0000000000..872d838bc4 --- /dev/null +++ b/man/git-annex-restage.1 @@ -0,0 +1,31 @@ +.TH git-annex-restage 1 +.SH NAME +git-annex-restage \- restages unlocked files in the git index +.PP +.SH SYNOPSIS +git annex restage +.PP +.SH DESCRIPTION +Since getting or dropping an unlocked file modifies the file in the work +tree, git needs to be told that the modification does not change the +content that it has recorded (the annex pointer). Restaging the file +accomplishes that. +.PP +You do not normally need to run this command, because usually git-annex +is able to restage unlocked files itself. There are some situations +where git-annex needs to restage a file, but the git index is locked, +and so it cannot. It will then display a warning suggesting you run this +command. +.PP +It's safe to run this command even after you have made a modification to an +unlocked file. +.PP +.SH SEE ALSO +git-annex(1) +git-annex\-smudge(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-rmurl.1 b/man/git-annex-rmurl.1 new file mode 100644 index 0000000000..ae4be01610 --- /dev/null +++ b/man/git-annex-rmurl.1 @@ -0,0 +1,45 @@ +.TH git-annex-rmurl 1 +.SH NAME +git-annex-rmurl \- record file is not available at url +.PP +.SH SYNOPSIS +git annex rmurl \fB[file url ..]\fP +.PP +.SH DESCRIPTION +Record that the file is no longer available at the url. +.PP +Removing the last web url will make git-annex no longer treat content as being +present in the web special remote. If some other special remote +claims the url, unregistering the url will not update presence information +for it, because the content may still be present on the remote. +.PP +.SH OPTIONS +.IP "\fB\-\-batch\fP" +.IP +Enables batch mode, in which lines are read from stdin. +Each line should contain the file, and the url to remove from that file, +separated by a single space. +.IP +.IP "\fB\-z\fP" +Makes the \fB\-\-batch\fP input be delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-addurl(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-satisfy.1 b/man/git-annex-satisfy.1 new file mode 100644 index 0000000000..957329c7b1 --- /dev/null +++ b/man/git-annex-satisfy.1 @@ -0,0 +1,66 @@ +.TH git-annex-satisfy 1 +.SH NAME +git-annex-satisfy \- transfer and drop content as configured +.PP +.SH SYNOPSIS +git annex satisfy \fB[remote ...]\fP +.PP +.SH DESCRIPTION +This transfers and drops content of annexed files to work toward satisfying +the preferred content settings of the local repository and remotes. +.PP +It does the same thing as \fBgit-annex sync \-\-content\fP without the pulling +and pushing of git repositories, and without changing the trees that are +imported to or exported from special remotes. +.PP +Note that it (like git-annex\-sync or git-annex\-assist) does not work +specifically towards satisfying the git-annex\-numcopies setting, +unless the preferred content setting of the local repository is written to +do so by using eg \fBapproxlackingcopies=1\fP. +.PP +.SH OPTIONS +.IP "\fB[remote]\fP" +.IP +By default this command operates on all remotes, except for remotes +that have \fBremote..annex\-sync\fP set to false. +.IP +By specifying the names of remotes (or remote groups), you can control +which ones to operate on. +.IP +.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" +Operate on only files in the specified path. The default is to operate on +all files in the working tree. +.IP +This option can be repeated multiple times with different paths. +.IP +Note that this option does not prevent exporting other files to an +"exporttree=yes" remote. +.IP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +Enables parallel processing with up to the specified number of jobs +running at once. For example: \fB\-J10\fP +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Usually this command operates on annexed files in the current branch. +This option makes it operate on all available versions of all annexed files +(when preferred content settings allow). +.IP +Note that preferred content settings that use \fBinclude=\fP or \fBexclude=\fP +will only match the version of files currently in the work tree, but not +past versions of files. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-sync(1) +.PP +git-annex\-preferred\-content(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-schedule.1 b/man/git-annex-schedule.1 new file mode 100644 index 0000000000..a9e121290b --- /dev/null +++ b/man/git-annex-schedule.1 @@ -0,0 +1,50 @@ +.TH git-annex-schedule 1 +.SH NAME +git-annex-schedule \- get or set scheduled jobs +.PP +.SH SYNOPSIS +git annex schedule \fBrepository [expression]\fP +.PP +.SH DESCRIPTION +The git-annex\-assistant(1) daemon can be configured to run scheduled jobs. +This is similar to cron and anacron (and you can use them if you prefer), +but has the advantage of being integrated into git-annex, and so being able +to e.g., fsck a repository on a removable drive when the drive gets +connected. +.PP +When run with an expression, configures scheduled jobs to run at a +particular time. This can be used to make the assistant periodically run +incremental fscks. +.PP +When run without an expression, outputs the current scheduled jobs for +the repository. +.PP +.SH EXPRESSIONS +These actions are available: "fsck self", "fsck UUID" (where UUID +is the UUID of a remote to fsck). After the action comes the duration +to allow the action to run, and finally the schedule of when to run it. +.PP +To schedule multiple jobs, separate them with "; ". +.PP +Some examples: +.PP + fsck self 30m every day at any time + fsck self 1h every month at 3 AM + fsck self 1h on day 1 of every month at any time + fsck self 1h every week divisible by 2 at any time +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-assistant(1) +.PP +git-annex\-expire(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-semitrust.1 b/man/git-annex-semitrust.1 new file mode 100644 index 0000000000..49b0a3047e --- /dev/null +++ b/man/git-annex-semitrust.1 @@ -0,0 +1,40 @@ +.TH git-annex-semitrust 1 +.SH NAME +git-annex-semitrust \- return repository to default trust level +.PP +.SH SYNOPSIS +git annex semitrust \fB[repository ...]\fP +.PP +.SH DESCRIPTION +Returns a repository to the default semi trusted state. +.PP +Repositories can be specified using their remote name, their +description, or their UUID. For the current repository, use "here". +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-trust(1) +.PP +git-annex\-untrust(1) +.PP +git-annex\-dead(1) +.PP +git-annex\-expire(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-setkey.1 b/man/git-annex-setkey.1 new file mode 100644 index 0000000000..87b3661caf --- /dev/null +++ b/man/git-annex-setkey.1 @@ -0,0 +1,29 @@ +.TH git-annex-setkey 1 +.SH NAME +git-annex-setkey \- sets annexed content for a key +.PP +.SH SYNOPSIS +git annex setkey key file +.PP +.SH DESCRIPTION +This plumbing\-level command makes the content of the specified key +be set to the specified file. The file is moved into the annex. +.PP +It's generally a better idea to use git-annex\-reinject(1) instead of +this command. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-reinject(1) +.PP +git-annex\-dropkey(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-setpresentkey.1 b/man/git-annex-setpresentkey.1 new file mode 100644 index 0000000000..511c22a31b --- /dev/null +++ b/man/git-annex-setpresentkey.1 @@ -0,0 +1,37 @@ +.TH git-annex-setpresentkey 1 +.SH NAME +git-annex-setpresentkey \- change records of where key is present +.PP +.SH SYNOPSIS +git annex setpresentkey \fBkey uuid [1|0]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command changes git-annex's records about whether +the specified key's content is present in a remote with the specified uuid. +.PP +Use 1 to indicate the key is present, or 0 to indicate the key is +not present. +.PP +.SH OPTIONS +.IP "\fB\-\-batch\fP" +.IP +Enables batch mode, in which lines are read from stdin. +The line format is "key uuid [1|0]" +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-shell.1 b/man/git-annex-shell.1 new file mode 100644 index 0000000000..ef022a81e5 --- /dev/null +++ b/man/git-annex-shell.1 @@ -0,0 +1,174 @@ +.TH git-annex-shell 1 +.SH NAME +git-annex\-shell \- Restricted login shell for git-annex only SSH access +.PP +.SH SYNOPSIS +git-annex\-shell [\-c] command [params ...] +.PP +.SH DESCRIPTION +git-annex\-shell is a restricted shell, similar to git\-shell, which +can be used as a login shell for SSH accounts. +.PP +Since its syntax is identical to git\-shell's, it can be used as a drop\-in +replacement anywhere git\-shell is used. For example it can be used as a +user's restricted login shell. +.PP +.SH COMMANDS +Any command not listed below is passed through to git\-shell. +.PP +Note that the directory parameter should be an absolute path, otherwise +it is assumed to be relative to the user's home directory. Also the +first "/~/" or "/~user/" is expanded to the specified home directory. +.PP +.IP "configlist directory" +This outputs a subset of the git configuration, in the same form as +\fBgit config \-\-list\fP. This is used to get the annex.uuid of the remote +repository. +.IP +When run in a repository that does not yet have an annex.uuid, one +will be created, as long as a git-annex branch has already been pushed to +the repository, or if the autoinit=1 flag is used to indicate +initialization is desired. +.IP +.IP "p2pstdio directory uuid" +This causes git-annex\-shell to communicate using the git-annex p2p +protocol over stdio. +.IP +The uuid is the one belonging to the repository that will be +communicating with git-annex\-shell. +.IP +.IP "notifychanges directory" +This is used by \fBgit-annex remotedaemon\fP to be notified when +refs in the remote repository are changed. +.IP +.IP "gcryptsetup directory gcryptid" +Sets up a repository as a gcrypt repository. +.IP +.IP "inannex directory [key ...]" +This checks if all specified keys are present in the annex, +and exits zero if so. +.IP +Exits 1 if the key is certainly not present in the annex. +Exits 100 if it's unable to tell (perhaps the key is in the process of +being removed from the annex). +.IP +Used only by the gcrypt special remote. +.IP +.IP "recvkey directory key" +This runs rsync in server mode to receive the content of a key, +and stores the content in the annex. +.IP +Used only by the gcrypt special remote. +.IP +.IP "sendkey directory key" +This runs rsync in server mode to transfer out the content of a key. +.IP +Used only by the gcrypt special remote. +.IP +.IP "dropkey directory [key ...]" +This drops the annexed data for the specified keys. +.IP +Used only by the gcrypt special remote. +.IP +.SH OPTIONS +.IP "\-\-uuid=UUID" +.IP +git-annex uses this to specify the UUID of the repository it was expecting +git-annex\-shell to access. This is both a sanity check, and allows +git-annex shell to proxy access to remotes, when configured +by git-annex\-update\-proxy. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.IP "\-\- fields=val fields=val.. \-\-" +Additional fields may be specified this way, to retain compatibility with +past versions of git-annex\-shell (that ignore these, but would choke +on new dashed options). +.IP +Currently used fields are autoinit= and remoteuuid= +.IP +.SH HOOK +After content is received or dropped from the repository by git-annex\-shell, +it runs a hook, \fB.git/hooks/annex\-content\fP (or \fBhooks/annex\-content\fP on a bare +repository). The hook is not currently passed any information about what +changed. +.PP +.SH ENVIRONMENT +.IP "GIT_ANNEX_SHELL_READONLY" +.IP +If set, disallows any action that could modify the git-annex +repository. +.IP +Note that this does not prevent passing commands on to git\-shell. +For that, you also need ... +.IP +.IP "GIT_ANNEX_SHELL_LIMITED" +If set, disallows running git\-shell to handle unknown commands. +.IP +.IP "GIT_ANNEX_SHELL_APPENDONLY" +If set, allows data to be written to the git-annex repository, +but does not allow data to be removed from it. +.IP +Note that this does not prevent passing commands on to git\-shell, +so you will have to separately configure git to reject pushes that +overwrite branches or are otherwise not appends. The git pre\-receive +hook may be useful for accomplishing this. +.IP +It's a good idea to enable annex.securehashesonly in a repository +that's set up this way. +.IP +.IP "GIT_ANNEX_SHELL_DIRECTORY" +If set, git-annex\-shell will refuse to run commands that do not operate +on the specified directory. +.IP +.SH EXAMPLES +To make a \fB~/.ssh/authorized_keys\fP file that only allows git-annex\-shell +to be run, and not other commands, pass the original command to the \-c +option: +.PP + command="git-annex\-shell \-c \\"$SSH_ORIGINAL_COMMAND\\"",no\-agent\-forwarding,no\-port\-forwarding,no\-X11\-forwarding ssh\-rsa AAAAB3NzaC1y[...] user@example.com +.PP +To further restrict git-annex\-shell to a particular repository, +and fully lock it down to read\-only mode: +.PP + command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_LIMITED=true GIT_ANNEX_SHELL_READONLY=true git-annex\-shell \-c \\"$SSH_ORIGINAL_COMMAND\\"",restrict ssh\-rsa AAAAB3NzaC1y[...] user@example.com +.PP +Obviously, \fBssh\-rsa AAAAB3NzaC1y[...] user@example.com\fP needs to +replaced with your SSH key. The above also assumes \fBgit-annex\-shell\fP +is available in your \fB$PATH\fP, use an absolute path if it is not the +case. Also note how the above uses the \fBrestrict\fP option instead of an +explicit list of functionality to disallow. This only works in certain +OpenSSH releases, starting from 7.1p2. +.PP +To only allow adding new objects to the repository, the +\fBGIT_ANNEX_SHELL_APPENDONLY\fP variable can be used as well: +.PP +command="GIT_ANNEX_SHELL_DIRECTORY=/srv/annex GIT_ANNEX_SHELL_APPENDONLY=true git-annex\-shell \-c \\"$SSH_ORIGINAL_COMMAND\\"",restrict ssh\-rsa AAAAB3NzaC1y[...] user@example.com +.PP +This will not keep an attacker from destroying the git history, as +explained above. For this you might want to disallow certain +operations, like branch deletion and force\-push, with options from +git\-config(1). For example: +.PP +git config receive.denyDeletes true +git config receive.denyNonFastForwards true +.PP +With this configuration, git commits can still remove files, +but they will still be available in the git history and git-annex will +retain their contents. Changes to \fBgit-annex\fP branch, however, can +negatively impact git-annex's location tracking information and might +cause data loss. To work around this problem, more complex hooks +are required, see for example the \fBupdate\-paranoid\fP hook in the git +source distribution. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git\-shell(1) +.PP +.SH AUTHOR +Joey Hess +.PP + +.PP +.PP + diff --git a/man/git-annex-sim.1 b/man/git-annex-sim.1 new file mode 100644 index 0000000000..e3bf307798 --- /dev/null +++ b/man/git-annex-sim.1 @@ -0,0 +1,374 @@ +.TH git-annex-sim 1 +.SH NAME +git-annex-sim \- simulate a network of repositories +.PP +.SH SYNOPSIS +git annex sim start [my.sim] +.PP +git annex sim command +.PP +git annex sim show +.PP +git annex sim end +.PP +git annex sim run my.sim +.PP +.SH DESCRIPTION +This command simulates the behavior of git-annex in a network of +repositories, determining which files would reach which repositories +according to the configuration of preferred content, numcopies, +trust level, etc. +.PP +The input to the simulation is a sim file, and/or sim commands that are +run after starting it. These are in the form "git annex sim command" +with the command in the same format used in the sim file (see sim commands +list below). For example, "git annex sim step 1" runs the simulation one step. +.PP +The simulation keeps a log as it runs, which contains the +entire simulation input, as well as the actions performed in the +simulation, and the results of the simulation. Use "git-annex sim show" +to display the log. This allows re\-running the same simulation later, +as well as analyzing the results of the simulation. +.PP +Use "git annex sim end" to finish the simulation, and clean up. +.PP +As a convenience, to run a sim from a file, and then stop it, use +"git-annex sim run". If there is a problem running the sim, it will be +shown before it is stopped. +.PP +Note that interrupting this command while it is running may leave the +simulation in an inconsistent state. And running multiple sim commands at +the same time can as well, although it is safe to run "git annex sim visit" +while running other sim commands. +.PP +.SH THE SIM FILE +This text file is used to configure the simulation and also to report on +the results of the simulation. Each line takes the form of a command +followed by parameters to the command. Lines starting with "#" or "\-\-" +are comments. +.PP +Here is an example sim file: +.PP + # add repositories to the simulation and connect them as remotes + init foo + init bar + connect foo <\-> bar + + # add a special remote + initremote baz + connect foo \-> baz <\- bar + + # configure repositories + numcopies 2 + group foo client + wanted foo standard + group bar archive + wanted bar standard + wanted baz include=*.mp3 + + # add annexed files in the working tree to the simulation, as if they + # were just added to repository foo + addtree foo include=*.mp3 + addtree foo include=*.jpg + addtree foo include=bigfiles/ + + # add simulated annexed files + add bigfile 100gb bar + add hugefile 10tb foo + + # run the simulation forward by ten steps + step 10 + + # remove foo's remote bar and see if a new file added to foo reaches bar + disconnect foo \-> bar + add foo.mp3 2mb foo + step 5 +.PP +.SH SIM COMMANDS +This is the full set of commands that can be used in the sim file as well +as passed to "git annex sim" while a simulation is running. +.PP +.IP "\fBinit name\fP" +Initialize a simulated repository, giving it a name that will be used +in the simulation. +.IP +.IP "\fBinitremote name\fP" +Initialize a simulated special remote. +.IP +.IP "\fBuse name here|remote|description|uuid\fP" +Use an existing repository in the simulation, with its existing +configuration (trust level, groups, preferred and required content, +maxsize, and the groupwanted configuration of its groups). +.IP +The repository is given a name for the purposes of the simulation. +The repository to use can be specified by remote name, uuid, etc. +Example: "use myrepo here" +.IP +.IP "\fBvisit repo [command]\fP" +Runs the specified shell command inside the simulated repository, +and waits for it to exit. +.IP +When no shell command is specified, it runs an interactive shell. +.IP +The command is run in a git repository whosegit-annex branch contains +the state of that simulated repository. This allows running any +git-annex commands, such as \fBgit-annex whereis\fP to examine the +state of the simulation. You should avoid making any changes to +git-annex state. +.IP +.IP "\fBconnect repo [<\-|\->|<\->] repo [...]\fP" +Add a connection between two or more repositories. The arrow indicates +which direction the connection runs, and it can be bidirectional. For +example, "connect foo \-> bar" makes bar be a remote of foo, while +"connect foo <\-> bar" makes each be the remote of the other. A chain +of connections can extend to many repositories, eg +"connect foo \-> bar \-> baz \-> foo" +.IP +.IP "\fBdisconnect repo [<\-|\->|<\->] repo [...]\fP" +Removes connections between repositories. +.IP +For example, "disconnect foo \-> bar" makes foo no longer have bar as a +remote. +.IP +.IP "\fBaddtree repo expression\fP" +Adds annexed files from the git repository to the simulation making them +be present in the specified repository. +.IP +The expression is a preferred content expression +(see git-annex\-preferred\-content(1)) specifying which annexed files +to add. While it is possible to include all or a large number of files +this way, note that often it's more efficient to simulate a small +quantity of files that have the particular properties you are interested +in. +.IP +When run in a subdirectory of the repository, only files in that +subdirectory are considered for addition. +.IP +This can be used with the same files more than once, to make multiple +repositories in the simulation contain the same files. +.IP +.IP "\fBadd filename size repo [repo ...]\fP" +Create a simulated annexed file with the specified filename and size, +that is present in the specified repository, or repositories. +.IP +The size can be specified using any usual units, eg "10mb" or +"3.3terabytes" +.IP +The filename cannot contain a space. +.IP +This stages a file in the index, so that regular git-annex commands can +be used to query the state of the simulated annexed file. If there is +already an annexed file by that name, it will be overwritten with the new +file. +.IP +Note that the simulation does not cover adding conflicting files to +different repositories. The files in the simulation are the same across +all simulated repositories. +.IP +.IP "addmulti N suffix minsize maxsize repo [repo ...]" +Add multiple simulated annexed files, with random sizes in the range +between minsize and maxsize. +.IP +The files are named by combining the number, which starts at 1 and goes +up to N, with the suffix. +.IP +For example: +.IP + addmulti 100 testfile.jpg 100kb 10mb foo +.IP +That adds files named "1testfile.jpg", 2testfile.jpg", etc. +.IP +Note that adding a large number of files to the simulation can slow it +down and make it use a lot of memory. +.IP +.IP "\fBstep N\fP" +Run the simulation forward by this many steps. +.IP +On each step of the simulation, one file is either transferred +or dropped, according to the preferred content and other configuration. +.IP +If there are no more files that can be either transferred or dropped +according to the current configuration, a message will be displayed +to indicate that the simulation has stabilized. +.IP +This also simulates git pull and git push being run in each repository, +as needed in order to find additional things to do. +.IP +.IP "\fBstepstable N\fP" +Run the simulation forward by this many steps, at which point it is +expected to have stabilized. +.IP +If the simulation does not stabilize, the command will exit with a +nonzero exit state. +.IP +.IP "\fBaction repo getwanted remote\fP" +Simulate the repository getting files it wants from the remote. +.IP +.IP "\fBaction repo dropunwanted\fP" +Simulate the repository dropping files it does not want, +when it is able to verify enough copies exist on remotes. +.IP +.IP "\fBaction repo dropunwantedfrom remote\fP" +Simulate the repository dropping files from the remote that the remote +does not want, when it is able to verify enouh copies exist. +.IP +.IP "\fBaction repo sendwanted remote\fP" +Simulate the repository sending files that the remote wants to it. +.IP +.IP "\fBaction repo gitpush remote\fP" +Simulate the repository pushing the git-annex branch to the remote. +.IP +.IP "\fBaction repo gitpull remote\fP" +Simulate the repository pulling the git-annex branch from the remote. +.IP +.IP "\fBaction repo pull remote\fP" +Simulate the equivilant of git-annex\-pull(1), by combining +the actions gitpull, getwanted, and dropunwanted. +.IP +.IP "\fBaction repo push remote\fP" +Simulate the equivilant of git-annex\-push(1) by combining +the actions sendwanted, dropunwantedfrom, and gitpush. +.IP +.IP "\fBaction repo sync remote\fP" +Simulate the equivilant of git-annex\-sync(1) by combining +the actions gitpull, getwanted, sendwanted, dropunwanted, and gitpush. +.IP +.IP "\fBaction [...] while action [...]\fP" +Simulate running the two actions concurrently. While the simulation only +actually simulates one thing happening at a time, when the actions each +operate on multiple files, they will be interleaved randomly. +.IP +Any number of actions can be combined this way. +.IP +For example: +.IP + action foo dropunwanted while action bar getwanted foo +.IP +In this example, bar may or may not get a file before foo drops it. +.IP +.IP "\fBseed N\fP" +Sets the random seed to a given number. Using this should make the +results of the simulation deterministic. The output sim file +always has the random seed included in it, so it can be used to replay +the simulation. +.IP +.IP "\fBpresent repo file\fP" +This indicates the expected state of the simulation at this point. The +repository should contain the content of the file. If it does not, the +discrepancy will be indicated on standard error, and the \fBgit-annex sim\fP +command will eventually exit nonzero. +.IP +This is added to the output sim file as the simulation runs. +.IP +.IP "\fBnotpresent repo file\fP " +This indicates the expected state of the simulation at this point. The +repository should not contain the content of the file. If it does, the +discrepancy will be indicated on standard error, and the \fBgit-annex sim\fP +command will eventually exit nonzero. +.IP +This is added to the output sim file as the simulation runs. +.IP +.IP "\fBnumcopies N\fP" +Sets the desired number of copies. This is equivilant to +git-annex\-numcopies(1). +.IP +Note that other configuration that sets numcopies, such as .gitattributes +files, is not used by the simulation. +.IP +.IP "\fBmincopies N\fP" +Sets the minimum number of copies. This is equivilant to +git-annex\-mincopies(1). +.IP +.IP "\fBtrustlevel repo trusted|untrusted|semitrusted|dead\fP" +Sets the trust level of the repository. This is equivilant to +git-annex\-trust(1), git-annex\-untrust(1), etc. +.IP +.IP "\fBwanted repo expression\fP" +Configure the preferred content of a repository. This is equivilant +to git-annex\-wanted(1). +.IP +.IP "\fBrequired repo expression\fP" +Configure the required content of a repository. This is equivilant +to git-annex\-required(1). +.IP +.IP "\fBgroupwanted group expression\fP" +Configure the groupwanted expression. This is equivilant to +git-annex\-groupwanted(1). +.IP +.IP "\fBrandomwanted repo term...\fP" +Configure the preferred content of a repository to a random expression +generated by combining a random selection of the provided terms with +"and", "or", and "not". +.IP +For example, "randomwanted foo exclude=*.x include=*.x largerthan=100kb" +might generate an expression of "exclude=*.x or not largerthan=100kb and include=*.x" +or it might generate an expression of "include=*.x and exclude=*.x" +.IP +.IP "\fBrandomrequired repo term...\fP" +Configure the required content of a repository to a random expression. +.IP +.IP "\fBrandomgroupwanted group term...\fP" +Configure the groupwanted to a random expression. +.IP +.IP "\fBgroup repo group\fP" +Add a repository to a group. This is equivilant to +git-annex\-group(1). +.IP +.IP "\fBungroup repo group\fP" +Remove a repository from a group. This is equivilant to +git-annex\-ungroup(1). +.IP +.IP "\fBmetadata filename expression\fP" +Change the metadata of the simulated file. The expression is +in the same format as the \-\-set option of the git-annex\-metadata +command. For example: \fBmetadata foo year=2025\fP +.IP +.IP "\fBmaxsize repo size\fP" +Configure the maximum size of a repository. This is equivilant to +git-annex\-maxsize(1). +.IP +.IP "\fBrebalance [on|off]\fP" +Setting "rebalance on" is the equivilant of passing the \-\-rebalance +option to git-annex. Setting "rebalance off" undoes that. +.IP +For example: +.IP + maxsize foo 1tb + rebalance on + step 100 + rebalance off +.IP +.IP "\fBclusternode name repo\fP" +Simulate a repository being a node of a cluster, which can be referred to +using the specified name. +.IP +Rather than a cluster gateway being simulated as a separate entity, any +connection to a cluster node with that name is treated as accessing that +repository via the same cluster gateway. +.IP +Since a cluster gateway knows about all changes that are made to nodes +via it, every repository that has a connection to a cluster node will +immediately know about changes that are made via that node, without +needing a simulated git pull. +.IP +To simulate a repository being a node of more than one cluster, or behind +multiple gateways in the same cluster, use this command to give it +multiple names. +.IP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH EXAMPLES +git-annex includes a collection of sim files, +at +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-test(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-smudge.1 b/man/git-annex-smudge.1 new file mode 100644 index 0000000000..8832c5ba7d --- /dev/null +++ b/man/git-annex-smudge.1 @@ -0,0 +1,62 @@ +.TH git-annex-smudge 1 +.SH NAME +git-annex-smudge \- git filter driver for git-annex +.PP +.SH SYNOPSIS +git annex smudge [\-\-clean] file +.PP +git annex smudge \-\-update +.PP +.SH DESCRIPTION +This command lets git-annex be used as a git filter driver which lets +annexed files in the git repository to be unlocked, instead +of being symlinks, and lets \fBgit add\fP store files in the annex. +.PP +When adding a file with \fBgit add\fP, the annex.largefiles config is +consulted to decide if a given file should be added to git as\-is, +or if its content are large enough to need to use git-annex. +The annex.gitaddtoannex setting overrides that; setting it to false +prevents \fBgit add\fP from adding files to the annex. +.PP +However, if git-annex can tell that a file was annexed before, +it will still be added to the annex even when those configs would normally +prevent it. Two examples of this are adding a modified version of an +annexed file, and moving an annexed file to a new filename and adding that. +.PP +The git configuration to use this command as a filter driver is as follows. +This is normally set up for you by git-annex init, so you should +not need to configure it manually. +.PP + [filter "annex"] + smudge = git-annex smudge %f + clean = git-annex smudge \-\-clean %f +.PP +To make git use that filter driver, it needs to be configured in +the \fB.gitattributes\fP file or in \fB.git/info/attributes\fP. The latter +is normally configured when a repository is initialized, with the following +contents: +.PP + * filter=annex +.PP +The smudge filter does not provide git with the content of annexed files, +because that would be slow and triggers memory leaks in git. Instead, +it records which worktree files need to be updated, and +\fBgit annex smudge \-\-update\fP later updates the work tree to contain +the content. That is run by several git hooks, including post\-checkout +and post\-merge. However, a few git commands, notably \fBgit stash\fP and +\fBgit cherry\-pick\fP, do not run any hooks, so after using those commands +you can manually run \fBgit annex smudge \-\-update\fP to update the working +tree. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +git-annex\-filter\-process(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-status.1 b/man/git-annex-status.1 new file mode 100644 index 0000000000..8d0a6bfbe4 --- /dev/null +++ b/man/git-annex-status.1 @@ -0,0 +1,39 @@ +.TH git-annex-status 1 +.SH NAME +git-annex-status \- show the working tree status (deprecated) +.PP +.SH SYNOPSIS +git annex status \fB[path ...]\fP +.PP +.SH DESCRIPTION +Similar to \fBgit status \-\-short\fP, this command displays the status of the files +in the working tree. +.PP +Show files that are not checked into git (?), deleted (D), +modified (M), added but not committed (A), and type changed/unlocked (T). +.PP +.SH OPTIONS +.IP "\fB\-\-ignore\-submodules=when\fP" +.IP +This option is passed on to git status, see its man page for +details. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git\-status(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-sync.1 b/man/git-annex-sync.1 new file mode 100644 index 0000000000..fa68335e3c --- /dev/null +++ b/man/git-annex-sync.1 @@ -0,0 +1,82 @@ +.TH git-annex-sync 1 +.SH NAME +git-annex-sync \- synchronize local repository with remotes +.PP +.SH SYNOPSIS +git annex sync \fB[remote ...]\fP +.PP +.SH DESCRIPTION +This command synchronizes the local repository with its remotes. +.PP +This command first commits any local changes to files that have +previously been added to the repository. Then it does the equivilant of +git-annex\-pull(1) followed by git-annex\-push(1). +.PP +However, unlike those commands, this command does not transfer annexed +content by default. That will change in a future version of git-annex, +when syncing with repositories that have preferred content configured. +.PP +.SH OPTIONS +.IP "\fB\-\-content\fP, \fB\-\-no\-content\fP, \fB\-g\fP" +.IP +The \-\-content option causes the content of annexed files +to also be pulled and pushed. +.IP +The \-\-no\-content and \-g options cause the content of annexed files to +not be pulled and pushed. +.IP +The \fBannex.synccontent\fP configuration can be set to true to make +\fB\-\-content\fP be enabled by default. +.IP +.IP "\fB\-\-content\-of=path\fP \fB\-C path\fP" +This option causes the content of annexed files in the given +path to also be pulled and pushed. +.IP +This option can be repeated multiple times with different paths. +.IP +Note that this option does not prevent exporting other files to an +"exporttree=yes" remote. +.IP +.IP "\fB\-\-commit\fP, \fB\-\-no\-commit\fP" +A commit is done by default (unless \fBannex.autocommit\fP is set to false). +.IP +Use \-\-no\-commit to avoid committing local changes. +.IP +.IP "\fB\-\-message=msg\fP \fB\-m msg\fP" +Use this option to specify a commit message. +.IP +If multiple \-m options are given, their values are concatenated +as separate paragraphs. +.IP +.IP "\fB\-\-pull\fP, \fB\-\-no\-pull\fP" +Use this option to disable pulling. +.IP +When \fBremote..annex\-sync\fP is set to false, pulling is disabled +for that remote, and using \fB\-\-pull\fP will not enable it. +.IP +.IP "\fB\-\-push\fP, \fB\-\-no\-push\fP " +Use this option to disable pushing. +.IP +When \fBremote..annex\-sync\fP is set to false, pushing is disabled for +that remote, and using \fB\-\-push\fP will not enable it. +.IP +.IP "Also all options supported by git-annex\-pull(1) and" +git-annex\-push(1) can be used. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-pull(1) +.PP +git-annex\-push(1) +.PP +git-annex\-assist(1) +.PP +git-annex\-satisfy(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-test.1 b/man/git-annex-test.1 new file mode 100644 index 0000000000..8b846abf30 --- /dev/null +++ b/man/git-annex-test.1 @@ -0,0 +1,63 @@ +.TH git-annex-test 1 +.SH NAME +git-annex-test \- run built\-in test suite +.PP +.SH SYNOPSIS +git annex test +.PP +.SH DESCRIPTION +This runs git-annex's built\-in test suite. +.PP +The test suite runs in the \fB.t\fP subdirectory of the current directory. +.PP +It can be useful to run the test suite on different filesystems, +or to verify your local installation of git-annex. +.PP +.SH OPTIONS +There are several options, provided by Haskell's tasty test +framework. Pass \-\-help for details about those. +.PP +.IP "\fB\-\-jobs=N\fP \fB\-JN\fP" +How many tests to run in parallel. The default is "cpus", which will +runs one job per CPU core. +.IP +.IP "\fB\-\-keep\-failures\fP" +When there are test failures, leave the \fB.t\fP directory populated with +repositories that demonstate the failures, for later analysis. +.IP +.IP "\fB\-\-test\-git\-config name=value\fP" +The test suite prevents git from reading any git configuration files. +Usually it is a good idea to run the test suite with a standard +git configuration. However, this option can be useful to see what +effect a git configuration setting has on the test suite. +.IP +Some configuration settings will break the test suite, in ways that are +due to a bug in git-annex. But it is possible that changing a +configuration can find a legitimate bug in git-annex. +.IP +One valid use of this is to change a git configuration to a value that +is planned to be the new default in a future version of git. +.IP +Also, some things can only be tested with a git configuration. For +example, annex.shared\-sop\-command has to be set for the test suite to +test using that command. +.IP +.IP "\fB\-\-test\-debug\fP" +Normally output of commands run by the test suite is hidden, so even +when annex.debug or \-\-debug is enabled, it will not be displayed. +This option makes the full output of commands run by the test suite be +displayed. It also makes the test suite run git-annex with \-\-debug. +.IP +It's a good idea to use \fB\-J1\fP in combinaton with this, otherwise +the output of concurrent tests will be mixed together. +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-testremote(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-testremote.1 b/man/git-annex-testremote.1 new file mode 100644 index 0000000000..60b0e6de5a --- /dev/null +++ b/man/git-annex-testremote.1 @@ -0,0 +1,53 @@ +.TH git-annex-testremote 1 +.SH NAME +git-annex-testremote \- test transfers to/from a remote +.PP +.SH SYNOPSIS +git annex testremote \fBremote\fP +.PP +.SH DESCRIPTION +This tests a remote by sending objects to it, downloading objects from it, +etc. +.PP +It's safe to run in an existing repository (the repository contents are +not altered), although it may perform expensive data transfers. +.PP +It's best to make a new remote for testing purposes. While the test +tries to clean up after itself, if the remote being tested had a bug, +the cleanup might fail, leaving test data in the remote. Also, +some special remotes don't support removal of data that has been stored +in them, so test data won't be able to be cleaned up when testing those. +.PP +Testing will use the remote's configuration, automatically varying +the chunk sizes, and with simple shared encryption disabled and enabled, +and exporttree disabled and enabled. If the remote is readonly, testing +is limited to checking various properties of downloading from it. +.PP +.SH OPTIONS +.IP "\fB\-\-fast\fP" +.IP +Perform a smaller set of tests. +.IP +.IP "\fB\-\-test\-readonly=file\fP" +Normally, random objects are generated for the test and are sent to the +remote. When a readonly remote is being tested, that cannot be done, +and so you need to specify some annexed files to use in the testing, +using this option. Their content needs to be present in the readonly remote +being tested, and in the local repository. +.IP +This option can be repeated. +.IP +.IP "\fB\-\-size=NUnits\fP" +Tune the base size of generated objects. The default is 1MiB. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-test(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-transferkey.1 b/man/git-annex-transferkey.1 new file mode 100644 index 0000000000..3f34336316 --- /dev/null +++ b/man/git-annex-transferkey.1 @@ -0,0 +1,32 @@ +.TH git-annex-transferkey 1 +.SH NAME +git-annex-transferkey \- transfers a key from or to a remote +.PP +.SH SYNOPSIS +git annex transferkey \fBkey [\-\-from=remote|\-\-to=remote]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command is used to request a single key be +transferred. +.PP +.SH OPTIONS +.IP "\fB\-\-from=remote\fP" +.IP +Download the content of the key from the remote. +.IP +.IP "\fB\-\-to=remote\fP" +Upload the content of the key to the remote. +.IP +.IP "\fB\-\-file=name\fP" +Provides a hint about the name of the file associated with the key. +(This name is only used in progress displays.) +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-transferkeys.1 b/man/git-annex-transferkeys.1 new file mode 100644 index 0000000000..b65dbe5b63 --- /dev/null +++ b/man/git-annex-transferkeys.1 @@ -0,0 +1,27 @@ +.TH git-annex-transferkeys 1 +.SH NAME +git-annex-transferkeys \- transfers keys (deprecated) +.PP +.SH SYNOPSIS +git annex transferkeys +.PP +.SH DESCRIPTION +This plumbing\-level command is used to transfer data, by the assistant +in git-annex version 8.20201127 and older. It is still included only +to prevent breakage during upgrades. +.PP +It is a long\-running process, which is fed instructions about the keys +to transfer using an internal stdio protocol, which is +intentionally not documented (as it may change at any time). +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-transferrer.1 b/man/git-annex-transferrer.1 new file mode 100644 index 0000000000..f4e72a6201 --- /dev/null +++ b/man/git-annex-transferrer.1 @@ -0,0 +1,24 @@ +.TH git-annex-transferrer 1 +.SH NAME +git-annex-transferrer \- transfers content +.PP +.SH SYNOPSIS +git annex transferrer +.PP +.SH DESCRIPTION +This plumbing\-level command is used to transfer data. +It is a long\-running process, which is fed instructions about +what to transfer using an internal stdio protocol, which is +intentionally not documented (as it may change at any time). +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-trust.1 b/man/git-annex-trust.1 new file mode 100644 index 0000000000..899d9ec8c0 --- /dev/null +++ b/man/git-annex-trust.1 @@ -0,0 +1,46 @@ +.TH git-annex-trust 1 +.SH NAME +git-annex-trust \- trust a repository +.PP +.SH SYNOPSIS +git annex trust \fB[repository ...]\fP +.PP +.SH DESCRIPTION +Records that a repository is trusted to not unexpectedly lose +content. Use with care. +.PP +Repositories can be specified using their remote name, their +description, or their UUID. To trust the current repository, use "here". +.PP +Before trusting a repository, consider this scenario. Repository A +is trusted and B is not; both contain the same content. \fBgit-annex drop\fP +is run on repository A, which checks that B still contains the content, +and so the drop proceeds. Then \fBgit-annex drop\fP is run on repository B, +which trusts A to still contain the content, so the drop succeeds. Now +the content has been lost. +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-semitrust(1) +.PP +git-annex\-untrust(1) +.PP +git-annex\-dead(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-unannex.1 b/man/git-annex-unannex.1 new file mode 100644 index 0000000000..2a8c51820e --- /dev/null +++ b/man/git-annex-unannex.1 @@ -0,0 +1,48 @@ +.TH git-annex-unannex 1 +.SH NAME +git-annex-unannex \- undo accidental add command +.PP +.SH SYNOPSIS +git annex unannex \fB[path ...]\fP +.PP +.SH DESCRIPTION +Use this to undo an accidental \fBgit annex add\fP command. It puts the +file back how it was before the add. +.PP +Note that for safety, the content of the file remains in the annex, +until you use \fBgit annex unused\fP and \fBgit annex dropunused\fP. +.PP +This is not the command you should use if you intentionally added a +file some time ago, and don't want its contents any more. In that +case you should use \fBgit annex drop\fP instead, and you can also +\fBgit rm\fP the file. +.PP +.SH OPTIONS +.IP "\fB\-\-fast\fP" +.IP +Normally this does a slow copy of the file. In \fB\-\-fast\fP mode, it +instead makes a hard link from the file to the content in the annex. +But use \-\-fast mode with caution, because editing the file will +change the content in the annex. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "file matching options" +The git-annex\-matching\-options(1) +can be used to specify files to unannex. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-undo.1 b/man/git-annex-undo.1 new file mode 100644 index 0000000000..e223da3710 --- /dev/null +++ b/man/git-annex-undo.1 @@ -0,0 +1,43 @@ +.TH git-annex-undo 1 +.SH NAME +git-annex-undo \- undo last change to a file or directory +.PP +.SH SYNOPSIS +git annex \fB[filename|directory] ...\fP +.PP +.SH DESCRIPTION +When passed a filename, undoes the last change that was made to that +file. +.PP +When passed a directory, undoes the last change that was made to the +contents of that directory. +.PP +Running undo a second time will undo the undo, returning the working +tree to the same state it had before. To support undoing an undo of +staged changes, any staged changes are first committed by the +undo command. +.PP +Note that this does not undo get/drop of a file's content; it only +operates on the file tree committed to git. +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "The git-annex\-common\-options(1) can also be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-add(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-ungroup.1 b/man/git-annex-ungroup.1 new file mode 100644 index 0000000000..c27ea708c0 --- /dev/null +++ b/man/git-annex-ungroup.1 @@ -0,0 +1,23 @@ +.TH git-annex-ungroup 1 +.SH NAME +git-annex-ungroup \- remove a repository from a group +.PP +.SH SYNOPSIS +git annex ungroup \fBrepository groupname\fP +.PP +.SH DESCRIPTION +Removes a repository from a group. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-group(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-uninit.1 b/man/git-annex-uninit.1 new file mode 100644 index 0000000000..223e643db6 --- /dev/null +++ b/man/git-annex-uninit.1 @@ -0,0 +1,35 @@ +.TH git-annex-uninit 1 +.SH NAME +git-annex-uninit \- de\-initialize git-annex and clean out repository +.PP +.SH SYNOPSIS +git annex uninit +.PP +.SH DESCRIPTION +Use this to stop using git annex. It will unannex every file in the +repository, and remove all of git-annex's other data, leaving you with a +git repository plus the previously annexed files. +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-unannex(1) +.PP +git-annex\-init(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-unlock.1 b/man/git-annex-unlock.1 new file mode 100644 index 0000000000..a94c07b8c7 --- /dev/null +++ b/man/git-annex-unlock.1 @@ -0,0 +1,71 @@ +.TH git-annex-unlock 1 +.SH NAME +git-annex-unlock \- unlock files for modification +.PP +.SH SYNOPSIS +git annex unlock \fB[path ...]\fP +.PP +.SH DESCRIPTION +Normally, the content of annexed files is protected from being changed. +Unlocking an annexed file allows it to be modified. When no files are +specified, all annexed files in the current directory are unlocked. +.PP +Unlocking a file changes how it is stored in the git repository (from a +symlink to a pointer file), so this command will make a change that you +can commit. +.PP +The content of an unlocked file is still stored in git-annex, not git, +and when you commit modifications to the file, the modifications will also +be stored in git-annex, with only the pointer file stored in git. +.PP +If you use \fBgit add\fP to add a file to the annex, it will be added in unlocked form from +the beginning. This allows workflows where a file starts out unlocked, is +modified as necessary, and is locked once it reaches its final version. +.PP +Normally, unlocking a file requires a copy to be made of its content, so +that its original content is preserved, while the copy can be modified. To +use less space, annex.thin can be set to true; this makes a hard link to +the content be made instead of a copy. (Only when supported by the file +system.) While this can save considerable disk space, any modification made +to a file will cause the old version of the file to be lost from the local +repository. So, enable annex.thin with care. +.PP +.SH EXAMPLES + # git annex unlock disk\-image + # git commit \-m "unlocked to allow VM to make changes as it runs" +.PP + # git annex unlock photo.jpg + # gimp photo.jpg + # git annex add photo.jpg + # git annex lock photo.jpg + # git commit \-m "redeye removal" +.PP +.SH OPTIONS +.IP "file matching options" +.IP +The git-annex\-matching\-options(1) +can be used to specify files to unlock. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-edit(1) +.PP +git-annex\-add(1) +.PP +git-annex\-lock(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-unregisterurl.1 b/man/git-annex-unregisterurl.1 new file mode 100644 index 0000000000..152d43b1db --- /dev/null +++ b/man/git-annex-unregisterurl.1 @@ -0,0 +1,59 @@ +.TH git-annex-unregisterurl 1 +.SH NAME +git-annex-unregisterurl \- unregisters an url for a key +.PP +.SH SYNOPSIS +git annex unregisterurl \fB[key url]\fP +.PP +.SH DESCRIPTION +This plumbing\-level command can be used to unregister urls when keys can +no longer be downloaded from them. +.PP +Normally the key is a git-annex formatted key. However, if the key cannot be +parsed as a key, and is a valid url, an URL key is constructed from the url. +.PP +Unregistering a key's last web url will make git-annex no longer treat content +as being present in the web special remote. If some other special remote +claims the url, unregistering the url will not update presence information +for it, because the content may still be present on the remote. +.PP +.SH OPTIONS +.IP "\fB\-\-remote=name|uuid\fP" +.IP +Indicate that the url is expected to be claimed by the specified remote. +If some other remote claims the url instead, unregistering it will fail. +.IP +Note that \fB\-\-remote=web\fP will prevent any other remote from claiming +the url. +.IP +.IP "\fB\-\-batch\fP" +In batch input mode, lines are read from stdin, and each line +should contain a key and url, separated by a single space. +.IP +.IP "\fB\-z\fP" +When in batch mode, the input is delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-registerurl(1) +.PP +git-annex\-reregisterurl(1) +.PP +git-annex\-rmurl(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-untrust.1 b/man/git-annex-untrust.1 new file mode 100644 index 0000000000..d8ebaf6b50 --- /dev/null +++ b/man/git-annex-untrust.1 @@ -0,0 +1,39 @@ +.TH git-annex-untrust 1 +.SH NAME +git-annex-untrust \- do not trust a repository +.PP +.SH SYNOPSIS +git annex untrust \fB[repository ...]\fP +.PP +.SH DESCRIPTION +Records that a repository is not trusted and could lose content +at any time. +.PP +Repositories can be specified using their remote name, their +description, or their UUID. To untrust the current repository, use "here". +.PP +.SH OPTIONS +.IP "\fB\-\-json\fP" +.IP +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-trust(1) +.PP +git-annex\-semitrust(1) +.PP +git-annex\-dead(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-unused.1 b/man/git-annex-unused.1 new file mode 100644 index 0000000000..23904414af --- /dev/null +++ b/man/git-annex-unused.1 @@ -0,0 +1,100 @@ +.TH git-annex-unused 1 +.SH NAME +git-annex-unused \- look for unused file content +.PP +.SH SYNOPSIS +git annex unused +.PP +.SH DESCRIPTION +Checks the annex for data that does not correspond to any files present +in any tag or branch, or in the git index, and prints a numbered list +of the data. +.PP +After running this command, you can use the \fB\-\-unused\fP option with many +other git-annex commands to operate on all the unused data that was found. +.PP +For example, to move all unused data to origin: +.PP + git annex unused; git annex move \-\-unused \-\-to origin +.PP +.SH OPTIONS +.IP "\fB\-\-fast\fP" +.IP +Only show unused temp and bad files. +.IP +.IP "\fB\-\-from=repository\fP" +Check for unused data that is located in a repository. +.IP +The repository should be specified using the name of a configured remote, +or the UUID or description of a repository. +.IP +.IP "\fB\-\-used\-refspec=+ref:\-ref\fP" +By default, any data that the git index uses, or that any refs in the git +repository point to is considered to be used. If you only want to use +some refs, you can use this option to specify the ones to use. Data that +is not in the specified refs (and not used by the index) will then be +considered unused. +.IP +See REFSPEC FORMAT below for details of the format of this setting. +.IP +The git configuration annex.used\-refspec can be used to configure +this in a more permanent fashion. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH REFSPEC FORMAT +The refspec format for \-\-used\-refspec and annex.used\-refspec is +a colon\-separated list of additions and removals of refs. +A somewhat contrived example: +.PP + +refs/heads/*:+HEAD^:+refs/tags/*:\-refs/tags/old\-tag:reflog +.PP +This adds all refs/heads/ refs, as well as the previous version +of HEAD. It also adds all tags, except for old\-tag. And it adds +all refs from the reflog. +.PP +The default behavior is equivilant to \fB\-\-used\-refspec=+refs/*:+HEAD\fP +.PP +The refspec is processed by starting with an empty set of refs, +and walking the list in order from left to right. +.PP +Each + using a glob is matched against all relevant refs +(a subset of \fBgit show\-ref\fP) and all matching refs are added +to the set. +For example, "+refs/remotes/*" adds all remote refs. +.PP +Each + without a glob adds the literal value to the set. +For example, "+HEAD^" adds "HEAD^". +.PP +Each \- is matched against the set of refs accumulated so far. +Any refs with names that match are removed from the set. +.PP +"reflog" adds all the refs from the reflog. This will make past versions +of files not be considered to be unused until the ref expires from the +reflog (by default for 90 days). Note that this may make git-annex unused +take some time to complete, it if needs to check every ref from the +reflog. +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-dropunused(1) +.PP +git-annex\-addunused(1) +.PP +git-annex\-whereused(1) +.PP +git-annex\-oldkeys(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-updatecluster.1 b/man/git-annex-updatecluster.1 new file mode 100644 index 0000000000..e065d8dee4 --- /dev/null +++ b/man/git-annex-updatecluster.1 @@ -0,0 +1,38 @@ +.TH git-annex-updatecluster 1 +.SH NAME +git-annex-updatecluster \- update records of cluster nodes +.PP +.SH SYNOPSIS +git-annex updatecluster +.PP +.SH DESCRIPTION +This command is used to record the nodes of a cluster in the git-annex +branch, and set up proxying to the nodes. It should be run in the +repository that will serve as a gateway to the cluster. +.PP +It looks at the git config \fBremote.name.annex\-cluster\-node\fP of +each remote. When that is set to the name of a cluster that has been +initialized with \fBgit-annex initcluster\fP, the node will be recorded in the +git-annex branch. +.PP +To remove a node from a cluster, unset \fBremote.name.annex\-cluster\-node\fP +and run this command. +.PP +To add additional gateways to a cluster, after running this command, +use git-annex\-extendcluster. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +.IP "git-annex(1)" +.IP "git-annex\-initcluster(1)" +.IP "git-annex\-extendcluster(1)" +.IP "git-annex\-updateproxy(1)" +.IP "" +.IP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-updateproxy.1 b/man/git-annex-updateproxy.1 new file mode 100644 index 0000000000..59881f6d45 --- /dev/null +++ b/man/git-annex-updateproxy.1 @@ -0,0 +1,52 @@ +.TH git-annex-updateproxy 1 +.SH NAME +git-annex-updateproxy \- update records with proxy configuration +.PP +.SH SYNOPSIS +git annex updateproxy +.PP +.SH DESCRIPTION +A git-annex repository can act as a proxy for its remotes. That allows +annexed content to be stored and removed from the proxy's remotes, by +repositories that do not have a direct connection to the remotes. +.PP +By default, no proxying is done. To configure the local repository to act +as a proxy for its remote named "foo", run \fBgit config remote.foo.annex\-proxy\fP +true. +.PP +After setting or unsetting \fBremote..annex\-proxy\fP git configurations, +run \fBgit-annex updateproxy\fP to record the proxy configuration in the +git-annex branch. That tells other repositories about the proxy +configuration. +.PP +Suppose, for example, that remote "work" has had this command run in +it. Then after pulling from "work", git-annex will know about an +additional remote, "work\-foo". That remote will be accessed using "work" as +a proxy. +.PP +Proxies can only be accessed via ssh or by an annex+http url. +.PP +To set up proxying to a special remote that is configured with +exporttree=yes, its necessary for it to also be configured with +annexobjects=yes. And, "remote..annex\-tracking\-branch" needs to +be configured to the branch that will be exported to the special remote. +When that branch is pushed to the proxy, it will update the tree exported +to the special remote. When files are copied to the remote via the proxy, +it will also update the exported tree. +.PP +Note that proxying for a special remote can temporarily use disk space +in the repository, to temporarily hold the content of annexed files. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +.IP "git-annex(1)" +.IP "git-annex\-updatecluster(1)" +.IP "git-annex\-export(1)" +.IP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-upgrade.1 b/man/git-annex-upgrade.1 new file mode 100644 index 0000000000..ae25569930 --- /dev/null +++ b/man/git-annex-upgrade.1 @@ -0,0 +1,53 @@ +.TH git-annex-upgrade 1 +.SH NAME +git-annex-upgrade \- upgrade repository +.PP +.SH SYNOPSIS +git annex upgrade +.PP +.SH DESCRIPTION +Upgrades the repository to the latest version. +.PP +Each git-annex repository has an annex.version in its git configuration, +that indicates the repository version. When an old repository version +becomes deprecated, git-annex will automatically upgrade it +(unless annex.autoupgraderepository is set to false). To manually upgrade, +you can use this command. +.PP +Sometimes there's a newer repository version that is not the default yet, +and then you can use this command to upgrade to it. +.PP +Currently, git-annex supports upgrades all the way back to version 0, which +was only used by its author. It's expected that git-annex will always +support upgrading from all past repository versions \-\- this is necessary to +allow archives to be taken offline for years and later used. +.PP +.SH OPTIONS +.IP "\-\-autoonly" +.IP +Only do whatever automatic upgrade can be done, don't necessarily +upgrade to the latest version. This is used internally by git-annex. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-migrate(1) +.PP +Upgrades procedures and history: +.PP +News and release notes: +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-vadd.1 b/man/git-annex-vadd.1 new file mode 100644 index 0000000000..c57a0b8ab7 --- /dev/null +++ b/man/git-annex-vadd.1 @@ -0,0 +1,38 @@ +.TH git-annex-vadd 1 +.SH NAME +git-annex-vadd \- add subdirs to current view +.PP +.SH SYNOPSIS +git annex vadd \fB[field=glob ...] [field=value ...] [tag ...] [?tag ...] [field?=glob]\fP +.PP +.SH DESCRIPTION +Changes the current view, adding an additional level of directories +to categorize the files. +.PP +For example, when the view is by author/tag, \fBvadd year=*\fP will +change it to year/author/tag. +.PP +So will \fBvadd year=2014 year=2013\fP, but limiting the years in view +to only those two. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-metadata(1) +.PP +git-annex\-view(1) +.PP +git-annex\-vpop(1) +.PP +git-annex\-vfilter(1) +.PP +git-annex\-vcycle(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-vcycle.1 b/man/git-annex-vcycle.1 new file mode 100644 index 0000000000..38231ae28f --- /dev/null +++ b/man/git-annex-vcycle.1 @@ -0,0 +1,34 @@ +.TH git-annex-vcycle 1 +.SH NAME +git-annex-vcycle \- switch view to next layout +.PP +.SH SYNOPSIS +git annex vcycle +.PP +.SH DESCRIPTION +When a view involves nested subdirectories, this cycles the order. +.PP +For example, when the view is by year/author/tag, \fBvcycle\fP will switch +it to author/tag/year. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-metadata(1) +.PP +git-annex\-view(1) +.PP +git-annex\-vpop(1) +.PP +git-annex\-vadd(1) +.PP +git-annex\-vfilter(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-version.1 b/man/git-annex-version.1 new file mode 100644 index 0000000000..4288100c8a --- /dev/null +++ b/man/git-annex-version.1 @@ -0,0 +1,33 @@ +.TH git-annex-version 1 +.SH NAME +git-annex-version \- show version info +.PP +.SH SYNOPSIS +git annex version +.PP +.SH DESCRIPTION +Shows the version of git-annex, as well as repository version information. +.PP +git-annex's version is in the form MAJOR.DATE, where MAJOR is a number +like 5, which corresponds to the current repository version, and DATE +is the date of the last release, like 20150320. +.PP +Daily builds of git-annex will append a "\-gREF" to the version, which +corresponds to the git ref from git-annex's source repository that was +built. Therefore, "5.20150320\-gdd35cf3" is a daily build, and +"5.20150401" is an April 1st release made a bit later. +.PP +.SH OPTIONS +.IP "\fB\-\-raw\fP" +.IP +Causes only git-annex's version to be output, and nothing else. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-vfilter.1 b/man/git-annex-vfilter.1 new file mode 100644 index 0000000000..1a7ded0a87 --- /dev/null +++ b/man/git-annex-vfilter.1 @@ -0,0 +1,32 @@ +.TH git-annex-vfilter 1 +.SH NAME +git-annex-vfilter \- filter current view +.PP +.SH SYNOPSIS +git annex vfilter \fB[tag ...] [field=value ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]\fP +.PP +.SH DESCRIPTION +Filters the current view to only the files that have the +specified field values and tags. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-metadata(1) +.PP +git-annex\-view(1) +.PP +git-annex\-vpop(1) +.PP +git-annex\-vadd(1) +.PP +git-annex\-vcycle(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-vicfg.1 b/man/git-annex-vicfg.1 new file mode 100644 index 0000000000..8de9a32d44 --- /dev/null +++ b/man/git-annex-vicfg.1 @@ -0,0 +1,28 @@ +.TH git-annex-vicfg 1 +.SH NAME +git-annex-vicfg \- edit configuration in git-annex branch +.PP +.SH SYNOPSIS +git annex vicfg +.PP +.SH DESCRIPTION +Opens EDITOR on a temp file containing all of git-annex's +configuration settings that are stored in the git-annex branch, +and when it exits, stores any changes made back to the git-annex branch. +.PP +Unlike git config settings, these configuration settings can be seen +by all clones of the repository. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git\-config(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-view.1 b/man/git-annex-view.1 new file mode 100644 index 0000000000..8b31537fc9 --- /dev/null +++ b/man/git-annex-view.1 @@ -0,0 +1,73 @@ +.TH git-annex-view 1 +.SH NAME +git-annex-view \- enter a view branch +.PP +.SH SYNOPSIS +git annex view \fB[tag ...] [field=value ...] [field=glob ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]\fP +.PP +.SH DESCRIPTION +Uses metadata to build a view branch of the files in the current branch, +and checks out the view branch. Only files in the current branch whose +metadata matches all the specified field values and tags will be +shown in the view. +.PP +Multiple values for a metadata field can be specified, either by using +a glob (\fBfield="*"\fP) or by listing each wanted value. The resulting view +will put files in subdirectories according to the value of their fields. +.PP +Once within such a view, you can make additional directories, and +copy or move files into them. When you commit, the metadata will +be updated to correspond to your changes. Deleting files and committing +also updates the metadata. +.PP +As well as the usual metadata, there are fields available corresponding +to the path to the file. So a file "foo/bar/baz/file" has fields "/=foo", +"foo/=bar", and "foo/bar/=baz". These location fields can be used the +same as other metadata to construct the view. +.PP +For example, \fB/=foo\fP will only include files from the foo +directory in the view, while \fBfoo/=*\fP will preserve the +subdirectories of the foo directory in the view. +.PP +To enter a view containing only files that lack a given metadata +value or tag, specify field!=value or !tag. (Globs cannot be used here.) +.PP +\fBfield?=*\fP is like \fBfield=*\fP but adds an additional directory named \fB_\fP (by +default) that contains files that do not have the field set to any value. +Similarly, \fB?tag\fP adds an additional directory named \fB_\fP that contains +files that do not have any tags set. Moving files from the \fB_\fP directory to +another directory and committing will set the metadata. And moving files +into the \fB_\fP directory and committing will unset the metadata. +.PP +The name of the \fB_\fP directory can be changed using the annex.viewunsetdirectory +git config. +.PP +Filenames in the view branch include their path within the original branch, to +ensure that they are unique. The path comes after the main filename, and +before any extensions. For example, "foo/bar.baz" will have a name +like "bar_%foo%.baz". annex.maxextensionlength can be used to configure +what is treated as an extension. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-metadata(1) +.PP +git-annex\-vpop(1) +.PP +git-annex\-vfilter(1) +.PP +git-annex\-vadd(1) +.PP +git-annex\-vcycle(1) +.PP +git-annex\-adjust(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-vpop.1 b/man/git-annex-vpop.1 new file mode 100644 index 0000000000..f2b8ad54f9 --- /dev/null +++ b/man/git-annex-vpop.1 @@ -0,0 +1,34 @@ +.TH git-annex-vpop 1 +.SH NAME +git-annex-vpop \- switch back to previous view +.PP +.SH SYNOPSIS +git annex vpop \fB[N]\fP +.PP +.SH DESCRIPTION +Switches from the currently active view back to the previous view. +Or, from the first view back to original branch. +.PP +The optional number tells how many views to pop. +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-metadata(1) +.PP +git-annex\-view(1) +.PP +git-annex\-vfilter(1) +.PP +git-annex\-vadd(1) +.PP +git-annex\-vcycle(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-wanted.1 b/man/git-annex-wanted.1 new file mode 100644 index 0000000000..7e59032d08 --- /dev/null +++ b/man/git-annex-wanted.1 @@ -0,0 +1,40 @@ +.TH git-annex-wanted 1 +.SH NAME +git-annex-wanted \- get or set preferred content expression +.PP +.SH SYNOPSIS +git annex wanted \fBrepository [expression]\fP +.PP +.SH DESCRIPTION +When run with an expression, configures the content that is preferred +to be held in the repository. See git-annex\-preferred\-content(1) +.PP +For example: +.PP + git annex wanted here "include=*.mp3 or include=*.ogg" +.PP +Without an expression, displays the current preferred content setting +of the repository. +.PP +To return a repository to the original default behavior, use an empty +value for the expression, eg: +.PP +git-annex wanted here "" +.PP +.SH OPTIONS +.IP "The git-annex\-common\-options(1) can be used." +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-required(1) +.PP +git-annex\-preferred\-content(1) +.PP +git-annex\-groupwanted(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-watch.1 b/man/git-annex-watch.1 new file mode 100644 index 0000000000..08e529482f --- /dev/null +++ b/man/git-annex-watch.1 @@ -0,0 +1,41 @@ +.TH git-annex-watch 1 +.SH NAME +git-annex-watch \- daemon to watch for changes +.PP +.SH SYNOPSIS +git annex watch +.PP +.SH DESCRIPTION +Watches for changes to files in the current directory and its subdirectories, +and takes care of automatically adding new files, as well as dealing with +deleted, copied, and moved files. With this running as a daemon in the +background, you no longer need to manually run git commands when +manipulating your files. +.PP +By default, all new files in the directory will be added to the repository. +(Including dotfiles.) To block some files from being added, use +\fB.gitignore\fP files. +.PP +By default, all files that are added are added to the annex, the same +as when you run \fBgit annex add\fP. If you configure annex.largefiles, +files that it does not match will instead be added with \fBgit add\fP. +.PP +.SH OPTIONS +.IP "\fB\-\-foreground\fP" +.IP +Avoid forking to the background. +.IP +.IP "\fB\-\-stop\fP" +Stop a running daemon in the current repository. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-assistant(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-webapp.1 b/man/git-annex-webapp.1 new file mode 100644 index 0000000000..062bf93db0 --- /dev/null +++ b/man/git-annex-webapp.1 @@ -0,0 +1,53 @@ +.TH git-annex-webapp 1 +.SH NAME +git-annex-webapp \- launch webapp +.PP +.SH SYNOPSIS +git annex webapp +.PP +.SH DESCRIPTION +Opens a web app, that allows easy setup of a git-annex repository, +and control of the git-annex assistant. If the assistant is not +already running, it will be started. This will cause new files to +be added and syncing operations to be performed. +.PP +By default, the webapp can only be accessed from localhost, and running +it opens a browser window. +.PP +.SH OPTIONS +.IP "\fB\-\-listen=address\fP" +.IP +Useful for using the webapp on a remote computer. This makes the webapp +listen on the specified IP address. (Or on the address that a specified +hostname resolves to.) +.IP +This disables running a local web browser, and outputs the url you +can use to open the webapp. +.IP +Set annex.listen in the git config to make the webapp always +listen on an IP address. +.IP +.IP "\fB\-\-port=number\fP" +Use this option to specify a port for the webapp. +By default, the webapp picks an unused port. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH USING HTTPS +When using the webapp on a remote computer, you'll almost certainly +want to enable HTTPS. The webapp will use HTTPS if it finds +a .git/annex/privkey.pem and .git/annex/certificate.pem. Here's +one way to generate those files, using a self\-signed certificate: +.PP + openssl genrsa \-out .git/annex/privkey.pem 4096 + openssl req \-new \-x509 \-key .git/annex/privkey.pem > .git/annex/certificate.pem +.PP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-assistant(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-whereis.1 b/man/git-annex-whereis.1 new file mode 100644 index 0000000000..47e5e8584e --- /dev/null +++ b/man/git-annex-whereis.1 @@ -0,0 +1,107 @@ +.TH git-annex-whereis 1 +.SH NAME +git-annex-whereis \- lists repositories that have file content +.PP +.SH SYNOPSIS +git annex whereis \fB[path ...]\fP +.PP +.SH DESCRIPTION +Displays information about where the contents of files are located. +.PP +For example: +.PP + # git annex whereis + whereis my_cool_big_file (1 copy) + 0c443de8\-e644\-11df\-acbf\-f7cd7ca6210d \-\- laptop + whereis other_file (3 copies) + 0c443de8\-e644\-11df\-acbf\-f7cd7ca6210d \-\- laptop + 62b39bbe\-4149\-11e0\-af01\-bb89245a1e61 \-\- usb drive [here] + 7570b02e\-15e9\-11e0\-adf0\-9f3f94cb2eaa \-\- backup drive +.PP +Note that this command does not contact remotes to verify if they still +have the content of files. It only reports on the last information that was +received from remotes. +.PP +.SH OPTIONS +.IP "matching options" +.IP +The git-annex\-matching\-options(1) +can be used to control what to act on. +.IP +.IP "\fB\-\-key=keyname\fP" +Show where a particular git-annex key is located. +.IP +.IP "\fB\-\-all\fP \fB\-A\fP" +Show whereis information for all known keys. +.IP +(Except for keys that have been marked as dead, +see git-annex\-dead(1).) +.IP +.IP "\fB\-\-branch=ref\fP" +Show whereis information for files in the specified branch or treeish. +.IP +.IP "\fB\-\-unused\fP" +Show whereis information for files found by last run of git-annex unused. +.IP +.IP "\fB\-\-batch\fP" +Enables batch mode, in which a file is read in a line from stdin, +its information displayed, and repeat. +.IP +Note that if the file is not an annexed file, or does not match +specified matching options, an empty line will be +output instead. +.IP +.IP "\fB\-\-batch\-keys\fP" +This is like \fB\-\-batch\fP but the lines read from stdin are parsed as keys. +.IP +.IP "\fB\-z\fP" +Makes batch input be delimited by nulls instead of the usual +newlines. +.IP +.IP "\fB\-\-json\fP" +Enable JSON output. This is intended to be parsed by programs that use +git-annex. Each line of output is a JSON object. +.IP +.IP "\fB\-\-json\-error\-messages\fP" +Messages that would normally be output to standard error are included in +the JSON instead. +.IP +.IP "\fB\-\-format=value\fP" +Use custom output formatting. +.IP +The value is a format string, in which '${var}' is expanded to the +value of a variable. To right\-justify a variable with whitespace, +use '${var;width}' ; to left\-justify a variable, use '${var;\-width}'; +to escape unusual characters (including control characters) +in a variable, use '${escaped_var}' +.IP +These variables are available for use in formats: file, key, uuid, +url, backend, bytesize, humansize, keyname, hashdirlower, hashdirmixed, +mtime (for the mtime field of a WORM key). +.IP +Also, '\\n' is a newline, '\\000' is a NULL, etc. +.IP +When the format contains the uuid variable, it will be expanded in turn +for each repository that contains the file content. For example, +with \-\-format="${file} ${uuid}\\n", output will look like: +.IP + foo 00000000\-0000\-0000\-0000\-000000000001 + foo a7f7ddd0\-9a08\-11ea\-ab66\-8358e4209d30 + bar a7f7ddd0\-9a08\-11ea\-ab66\-8358e4209d30 +.IP +The same applies when the url variable is used and a file has multiple +recorded urls. +.IP +.IP "Also the git-annex\-common\-options(1) can be used." +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-find(1) +.PP +git-annex\-list(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex-whereused.1 b/man/git-annex-whereused.1 new file mode 100644 index 0000000000..e23632031b --- /dev/null +++ b/man/git-annex-whereused.1 @@ -0,0 +1,47 @@ +.TH git-annex-whereused 1 +.SH NAME +git-annex-whereused \- find what files use or used a key +.PP +.SH SYNOPSIS +git annex whereused \fB\-\-key=keyname|\-\-unused\fP +.PP +.SH DESCRIPTION +Finds what files use or used a key. +.PP +For each file in the working tree that uses a key, this outputs one line, +starting with the key, then a space, and then the name of the file. +When multiple files use the same key, they will all be listed. When +nothing is found that uses the key, there will be no output. +.PP +The default is to find only files in the current working tree that use a +key. The \fB\-\-historical\fP option makes it also find past versions of files. +.PP +.SH OPTIONS +.IP "\fB\-\-key=keyname\fP" +.IP +Operate on this key. +.IP +.IP "\fB\-\-unused\fP" +Operate on keys found by last run of git-annex unused. +.IP +Usually these keys won't be used by any files in the current working +tree, or any tags or branches. Combining this option with \fB\-\-historical\fP +will find past uses of the keys. +.IP +.IP "\fB\-\-historical\fP" +When no files in the current working tree use a key, this causes more +work to be done, looking at past versions of the current branch, other +branches, tags, and the reflog, to find somewhere that the key was used. +It stops after finding one use of the key, and outputs a git rev that +refers to where it was used, eg "HEAD@{40}:somefile" +.IP +.SH SEE ALSO +git-annex(1) +.PP +git-annex\-unused(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-annex.1 b/man/git-annex.1 new file mode 100644 index 0000000000..8cbd47b80b --- /dev/null +++ b/man/git-annex.1 @@ -0,0 +1,2138 @@ +.TH git-annex 1 +.SH NAME +git-annex \- manage files with git, without checking their contents in +.PP +.SH SYNOPSIS +git annex command [params ...] +.PP +.SH DESCRIPTION +git-annex allows managing files with git, without checking the file +contents into git. While that may seem paradoxical, it is useful when +dealing with files larger than git can currently easily handle, whether due +to limitations in memory, checksumming time, or disk space. +.PP +Even without file content tracking, being able to manage files with git, +move files around and delete files with versioned directory trees, and use +branches and distributed clones, are all very handy reasons to use git. And +annexed files can co\-exist in the same git repository with regularly +versioned files, which is convenient for maintaining documents, Makefiles, +etc that are associated with annexed files but that benefit from full +revision control. +.PP +When a file is annexed, its content is moved into a key\-value store, and +a symlink is made that points to the content. These symlinks are checked into +git and versioned like regular files. You can move them around, delete +them, and so on. Pushing to another git repository will make git-annex +there aware of the annexed file, and it can be used to retrieve its +content from the key\-value store. +.PP +.SH EXAMPLES + # git annex get video/hackity_hack_and_kaxxt.mov + get video/hackity_hack_and_kaxxt.mov (not available) + I was unable to access these remotes: server + Try making some of these repositories available: + 5863d8c0\-d9a9\-11df\-adb2\-af51e6559a49 \-\- my home file server + 58d84e8a\-d9ae\-11df\-a1aa\-ab9aa8c00826 \-\- portable USB drive + ca20064c\-dbb5\-11df\-b2fe\-002170d25c55 \-\- backup SATA drive + failed + # sudo mount /media/usb + # git remote add usbdrive /media/usb + # git annex get video/hackity_hack_and_kaxxt.mov + get video/hackity_hack_and_kaxxt.mov (from usbdrive...) ok + + # git annex add iso + add iso/Debian_5.0.iso ok + + # git annex drop iso/Debian_4.0.iso + drop iso/Debian_4.0.iso ok + + # git annex move iso \-\-to=usbdrive + move iso/Debian_5.0.iso (moving to usbdrive...) ok +.PP +.SH COMMONLY USED COMMANDS +.IP "\fBhelp\fP" +.IP +Display built\-in help. +.IP +For help on a specific command, use \fBgit annex help command\fP +.IP +.IP "\fBadd [path ...]\fP" +Adds files to the annex. +.IP +See git-annex\-add(1) for details. +.IP +.IP "\fBget [path ...]\fP" +Makes the content of annexed files available in this repository. +.IP +See git-annex\-get(1) for details. +.IP +.IP "\fBdrop [path ...]\fP" +Drops the content of annexed files from this repository. +.IP +See git-annex\-drop(1) for details. +.IP +.IP "\fBmove [path ...] [\-\-from=remote|\-\-to=remote]\fP" +Moves the content of files from or to another remote. +.IP +See git-annex\-move(1) for details. +.IP +.IP "\fBcopy [path ...] [\-\-from=remote|\-\-to=remote]\fP" +Copies the content of files from or to another remote. +.IP +See git-annex\-copy(1) for details. +.IP +.IP "\fBstatus [path ...]\fP" +Show the working tree status. (deprecated) +.IP +See git-annex\-status(1) for details. +.IP +.IP "\fBunlock [path ...]\fP" +Unlock annexed files for modification. +.IP +See git-annex\-unlock(1) for details. +.IP +.IP "\fBedit [path ...]\fP" +This is an alias for the unlock command. May be easier to remember, +if you think of this as allowing you to edit an annexed file. +.IP +.IP "\fBlock [path ...]\fP" +Use this to undo an unlock command if you don't want to modify +the files, or have made modifications you want to discard. +.IP +See git-annex\-lock(1) for details. +.IP +.IP "\fBpull [remote ...]\fP" +Pull content from remotes. +.IP +See git-annex\-pull(1) for details. +.IP +.IP "\fBpush [remote ...]\fP" +Push content to remotes. +.IP +See git-annex\-push(1) for details. +.IP +.IP "\fBsync [remote ...]\fP" +Synchronize local repository with remotes. +.IP +See git-annex\-sync(1) for details. +.IP +.IP "\fBassist [remote ...]\fP" +Add files and sync changes with remotes. +.IP +See git-annex\-assist(1) for details. +.IP +.IP "\fBsatisfy [remote ...]\fP" +Satisfy preferred content settings by transferring and dropping content. +.IP +See git-annex\-satisfy(1) for details. +.IP +.IP "\fBmirror [path ...] [\-\-to=remote|\-\-from=remote]\fP" +Mirror content of files to/from another repository. +.IP +See git-annex\-mirror(1) for details. +.IP +.IP "\fBaddurl [url ...]\fP" +Downloads each url to its own file, which is added to the annex. +.IP +See git-annex\-addurl(1) for details. +.IP +.IP "\fBrmurl file url\fP" +Record that the file is no longer available at the url. +.IP +See git-annex\-rmurl(1) for details. +.IP +.IP "\fBimport \-\-from remote branch[:subdir] | [path ...]\fP" +Add a tree of files to the repository. +.IP +See git-annex\-import(1) for details. +.IP +.IP "\fBimportfeed [url ...]\fP" +Imports the contents of podcast feeds into the annex. +.IP +See git-annex\-importfeed(1) for details. +.IP +.IP "\fBexport treeish \-\-to remote\fP" +Export content to a remote. +.IP +See git-annex\-export(1) for details. +.IP +.IP "\fBundo [filename|directory] ...\fP" +Undo last change to a file or directory. +.IP +See git-annex\-undo(1) for details. +.IP +.IP "\fBaddcomputed\fP" +Adds computed files to the repository. +.IP +See git-annex\-addcomputed(1) for details. +.IP +.IP "\fBrecompute\fP" +Recomputes computed files. +.IP +See git-annex\-recompute(1) for details. +.IP +.IP "\fBfindcomputed\fP" +Lists computed files. +.IP +See git-annex\-findcomputed(1) for details. +.IP +.IP "\fBmulticast\fP" +Multicast file distribution. +.IP +See git-annex\-multicast(1) for details. +.IP +.IP "\fBwatch\fP" +Daemon to watch for changes and autocommit. +.IP +See git-annex\-watch(1) for details. +.IP +.IP "\fBassistant\fP" +Daemon to automatically sync changes. +.IP +See git-annex\-assistant(1) for details. +.IP +.IP "\fBwebapp\fP" +Opens a web app, that allows easy setup of a git-annex repository, +and control of the git-annex assistant. If the assistant is not +already running, it will be started. +.IP +See git-annex\-webapp(1) for details. +.IP +.IP "\fBp2phttp\fP" +Allows a git-annex repository to be accessed over HTTP using git-annex +p2p protocol. +.IP +See git-annex\-p2phttp(1) for details. +.IP +.IP "\fBremotedaemon\fP" +Persistant communication with remotes. +.IP +See git-annex\-remotedaemon(1) for details. +.IP +.SH REPOSITORY SETUP COMMANDS +.IP "\fBinit [description]\fP" +.IP +Until a repository (or one of its remotes) has been initialized, +git-annex will refuse to operate on it, to avoid accidentally +using it in a repository that was not intended to have an annex. +.IP +See git-annex\-init(1) for details. +.IP +.IP "\fBdescribe repository description\fP" +Changes the description of a repository. +.IP +See git-annex\-describe(1) for details. +.IP +.IP "\fBinitremote name type=value [param=value ...]\fP" +Creates a new special remote, and adds it to \fB.git/config\fP. +.IP +See git-annex\-initremote(1) for details. +.IP +.IP "\fBenableremote name [param=value ...]\fP" +Enables use of an existing special remote in the current repository. +.IP +See git-annex\-enableremote(1) for details. +.IP +.IP "\fBconfigremote name [param=value ...]\fP" +Changes configuration of an existing special remote. +.IP +See git-annex\-configremote(1) for details. +.IP +.IP "\fBrenameremote\fP" +Renames a special remote. +.IP +See git-annex\-renameremote(1) for details. +.IP +.IP "\fBenable\-tor\fP" +Sets up tor hidden service. +.IP +See git-annex\-enable\-tor(1) for details. +.IP +.IP "\fBnumcopies [N]\fP" +Configure desired number of copies. +.IP +See git-annex\-numcopies(1) for details. +.IP +.IP "\fBmincopies [N]\fP" +Configure minimum number of copies. +.IP +See git-annex\-mincopies(1) for details. +.IP +.IP "\fBtrust [repository ...]\fP" +Records that a repository is trusted to not unexpectedly lose +content. Use with care. +.IP +See git-annex\-trust(1) for details. +.IP +.IP "\fBuntrust [repository ...]\fP" +Records that a repository is not trusted and could lose content +at any time. +.IP +See git-annex\-untrust(1) for details. +.IP +.IP "\fBsemitrust [repository ...]\fP" +Returns a repository to the default semi trusted state. +.IP +See git-annex\-semitrust(1) for details. +.IP +.IP "\fBgroup repository groupname\fP" +Add a repository to a group. +.IP +See git-annex\-group(1) for details. +.IP +.IP "\fBungroup repository groupname\fP" +Removes a repository from a group. +.IP +See git-annex\-ungroup(1) for details. +.IP +.IP "\fBwanted repository [expression]\fP" +Get or set preferred content expression. +.IP +See git-annex\-wanted(1) for details. +.IP +.IP "\fBgroupwanted groupname [expression]\fP" +Get or set groupwanted expression. +.IP +See git-annex\-groupwanted(1) for details. +.IP +.IP "\fBrequired repository [expression]\fP" +Get or set required content expression. +.IP +See git-annex\-required(1) for details. +.IP +.IP "\fBmaxsize repository [size]\fP" +Get or set maximum size of repository. +.IP +.IP "\fBinitcluster\fP" +Initializes a new cluster. +.IP +See git-annex\-initcluster(1) for details. +.IP +.IP "\fBupdatecluster\fP" +Update records of cluster nodes. +.IP +See git-annex\-updatecluster(1) for details. +.IP +.IP "\fBextendcluster\fP" +Adds an additional gateway to a cluster. +.IP +See git-annex\-extendcluster(1) for details. +.IP +.IP "\fBupdateproxy\fP" +Update records with proxy configuration. +.IP +See git-annex\-updateproxy(1) for details. +.IP +.IP "\fBschedule repository [expression]\fP" +Get or set scheduled jobs. +.IP +See git-annex\-schedule(1) for details. +.IP +.IP "\fBconfig\fP" +Get and set other configuration stored in git-annex branch. +.IP +See git-annex\-config(1) for details. +.IP +.IP "\fBvicfg\fP" +Opens EDITOR on a temp file containing most of the above configuration +settings, as well as a few others, and when it exits, stores any changes +made back to the git-annex branch. +.IP +See git-annex\-vicfg(1) for details. +.IP +.IP "\fBadjust\fP" +Switches a repository to use an adjusted branch, which can automatically +unlock all files, etc. +.IP +See git-annex\-adjust(1) for details. +.IP +.IP "\fBdirect\fP" +Switches a repository to use direct mode. (deprecated) +.IP +See git-annex\-direct(1) for details. +.IP +.IP "\fBindirect\fP" +Switches a repository to use indirect mode. (deprecated) +.IP +See git-annex\-indirect(1) for details. +.IP +.SH REPOSITORY MAINTENANCE COMMANDS +.IP "\fBfsck [path ...]\fP" +.IP +Checks the annex consistency, and warns about or fixes any problems found. +This is a good complement to \fBgit fsck\fP. +.IP +See git-annex\-fsck(1) for details. +.IP +.IP "\fBexpire [repository:]time ...\fP" +Expires repositories that have not recently performed an activity +(such as a fsck). +.IP +See git-annex\-expire(1) for details. +.IP +.IP "\fBunused\fP" +Checks the annex for data that does not correspond to any files present +in any tag or branch, and prints a numbered list of the data. +.IP +See git-annex\-unused(1) for details. +.IP +.IP "\fBdropunused [number|range ...]\fP" +Drops the data corresponding to the numbers, as listed by the last +\fBgit annex unused\fP +.IP +See git-annex\-dropunused(1) for details. +.IP +.IP "\fBaddunused [number|range ...]\fP" +Adds back files for the content corresponding to the numbers or ranges, +as listed by the last \fBgit annex unused\fP. +.IP +See git-annex\-addunused(1) for details. +.IP +.IP "\fBfix [path ...]\fP" +Fixes up symlinks that have become broken to again point to annexed content. +.IP +See git-annex\-fix(1) for details. +.IP +.IP "\fBmerge\fP" +Automatically merge changes from remotes. +.IP +See git-annex\-merge(1) for details. +.IP +.IP "\fBupgrade\fP" +Upgrades the repository. +.IP +See git-annex\-upgrade(1) for details. +.IP +.IP "\fBdead [repository ...] [\-\-key key]\fP" +Indicates that a repository or a single key has been irretrievably lost. +.IP +See git-annex\-dead(1) for details. +.IP +.IP "\fBforget\fP" +Causes the git-annex branch to be rewritten, throwing away historical +data about past locations of files. +.IP +See git-annex\-forget(1) for details. +.IP +.IP "\fBfilter\-branch\fP" +Produces a filtered version of the git-annex branch. +.IP +See git-annex\-filter\-branch(1) for details. +.IP +.IP "\fBrepair\fP" +This can repair many of the problems with git repositories that \fBgit fsck\fP +detects, but does not itself fix. It's useful if a repository has become +badly damaged. One way this can happen is if a repository used by git-annex +is on a removable drive that gets unplugged at the wrong time. +.IP +See git-annex\-repair(1) for details. +.IP +.IP "\fBp2p\fP" +Configure peer\-2\-Peer links between repositories. +.IP +See git-annex\-p2p(1) for details. +.IP +.SH QUERY COMMANDS +.IP "\fBfind [path ...]\fP" +.IP +Outputs a list of annexed files in the specified path. With no path, +finds files in the current directory and its subdirectories. +.IP +See git-annex\-find(1) for details. +.IP +.IP "\fBwhereis [path ...]\fP" +Displays information about where the contents of files are located. +.IP +See git-annex\-whereis(1) for details. +.IP +.IP "\fBlist [path ...]\fP" +Displays a table of remotes that contain the contents of the specified +files. This is similar to whereis but a more compact display. +.IP +See git-annex\-list(1) for details. +.IP +.IP "\fBwhereused\fP" +Finds what files use or used a key. +.IP +.IP "\fBlog [path ...]\fP" +Displays the location log for the specified file or files, +showing each repository they were added to ("+") and removed from ("\-"). +.IP +See git-annex\-log(1) for details. +.IP +.IP "\fBoldkeys [path ...]\fP" +List keys used for old versions of files. +.IP +See git-annex\-oldkeys(1) for details. +.IP +.IP "\fBinfo [directory|file|remote|uuid ...]\fP" +Displays statistics and other information for the specified item, +which can be a directory, or a file, or a remote, or the uuid of a +repository. +.IP +When no item is specified, displays statistics and information +for the repository as a whole. +.IP +See git-annex\-info(1) for details. +.IP +.IP "\fBversion\fP" +Shows the version of git-annex, as well as repository version information. +.IP +See git-annex\-version(1) for details. +.IP +.IP "\fBmap\fP" +Generate map of repositories. +.IP +See git-annex\-map(1) for details. +.IP +.IP "\fBinprogress\fP" +Access files while they're being downloaded. +.IP +See git-annex\-inprogress(1) for details. +.IP +.IP "\fBfindkeys\fP" +Similar to \fBgit-annex find\fP, but operating on keys. +.IP +See git-annex\-findkeys(1) for details. +.IP +.SH METADATA COMMANDS +.IP "\fBmetadata [path ...]\fP" +.IP +The content of an annexed file can have any number of metadata fields +attached to it to describe it. Each metadata field can in turn +have any number of values. +.IP +This command can be used to set metadata, or show the currently set +metadata. +.IP +See git-annex\-metadata(1) for details. +.IP +.IP "\fBview [tag ...] [field=value ...] [field=glob ...] [?tag ...] [field?=glob] [!tag ...] [field!=value ...]\fP" +Uses metadata to build a view branch of the files in the current branch, +and checks out the view branch. Only files in the current branch whose +metadata matches all the specified field values and tags will be +shown in the view. +.IP +See git-annex\-view(1) for details. +.IP +.IP "\fBvpop [N]\fP" +Switches from the currently active view back to the previous view. +Or, from the first view back to original branch. +.IP +See git-annex\-vpop(1) for details. +.IP +.IP "\fBvfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]\fP" +Filters the current view to only the files that have the +specified field values and tags. +.IP +See git-annex\-vfilter(1) for details. +.IP +.IP "\fBvadd [field=glob ...] [field=value ...] [tag ...]\fP" +Changes the current view, adding an additional level of directories +to categorize the files. +.IP +See git-annex\-vfilter(1) for details. +.IP +.IP "\fBvcycle\fP" +When a view involves nested subdirectories, this cycles the order. +.IP +See git-annex\-vcycle(1) for details. +.IP +.SH UTILITY COMMANDS +.IP "\fBmigrate [path ...]\fP" +.IP +Changes the specified annexed files to use a different key\-value backend. +.IP +See git-annex\-migrate(1) for details. +.IP +.IP "\fBreinject src dest\fP" +Moves the src file into the annex as the content of the dest file. +This can be useful if you have obtained the content of a file from +elsewhere and want to put it in the local annex. +.IP +See git-annex\-reinject(1) for details. +.IP +.IP "\fBunannex [path ...]\fP" +Use this to undo an accidental \fBgit annex add\fP command. It puts the +file back how it was before the add. +.IP +See git-annex\-unannex(1) for details. +.IP +.IP "\fBuninit\fP" +De\-initialize git-annex and clean out repository. +.IP +See git-annex\-uninit(1) for details. +.IP +.IP "\fBreinit uuid|description\fP" +Initialize repository, reusing old UUID. +.IP +See git-annex\-reinit(1) for details. +.IP +.SH PLUMBING COMMANDS +.IP "\fBpre\-commit [path ...]\fP" +.IP +This is meant to be called from git's pre\-commit hook. \fBgit annex init\fP +automatically creates a pre\-commit hook using this. +.IP +See git-annex\-pre\-commit(1) for details. +.IP +.IP "\fBpost\-receive\fP" +This is meant to be called from git's post\-receive hook. \fBgit annex init\fP +automatically creates a post\-receive hook using this. +.IP +See git-annex\-post\-receive(1) for details. +.IP +.IP "\fBlookupkey [file ...]\fP" +Looks up key used for file. +.IP +See git-annex\-lookupkey(1) for details. +.IP +.IP "\fBcalckey [file ...]\fP" +Calculates the key that would be used to refer to a file. +.IP +See git-annex\-calckey(1) for details. +.IP +.IP "\fBcontentlocation [key ..]\fP" +Looks up location of annexed content for a key. +.IP +See git-annex\-contentlocation(1) for details. +.IP +.IP "\fBexaminekey [key ...]\fP" +Print information that can be determined purely by looking at the key. +.IP +See git-annex\-examinekey(1) for details. +.IP +.IP "\fBmatchexpression\fP" +Checks if a preferred content expression matches provided data. +.IP +See git-annex\-matchexpression(1) for details. +.IP +.IP "\fBfromkey [key file]\fP" +Manually set up a file in the git repository to link to a specified key. +.IP +See git-annex\-fromkey(1) for details. +.IP +.IP "\fBregisterurl [key url]\fP" +Registers an url for a key. +.IP +See git-annex\-registerurl(1) for details. +.IP +.IP "\fBunregisterurl [key url]\fP" +Unregisters an url for a key. +.IP +See git-annex\-unregisterurl(1) for details. +.IP +.IP "\fBreregisterurl [key url]\fP" +Updates url registration information. +.IP +See git-annex\-reregisterurl(1) for details. +.IP +.IP "\fBsetkey key file\fP" +Moves a file into the annex as the content of a key. +.IP +See git-annex\-setkey(1) for details. +.IP +.IP "\fBdropkey [key ...]\fP" +Drops annexed content for specified keys. +.IP +See git-annex\-dropkey(1) for details. +.IP +.IP "\fBtransferkey key [\-\-from=remote|\-\-to=remote]\fP" +Transfers a key from or to a remote. +.IP +See git-annex\-transferkey(1) for details. +.IP +.IP "\fBtransferrer\fP" +Used internally by git-annex to transfer content. +.IP +See git-annex\-transferrer(1) for details. +.IP +.IP "\fBtransferkeys\fP" +Used internally by old versions of the assistant. +.IP +See git-annex\-transferkey(1) for details. +.IP +.IP "\fBsetpresentkey key uuid [1|0]\fP" +This plumbing\-level command changes git-annex's records about whether +the specified key's content is present in a remote with the specified uuid. +.IP +See git-annex\-setpresentkey(1) for details. +.IP +.IP "\fBreadpresentkey key uuid\fP" +Read records of where key is present. +.IP +See git-annex\-readpresentkey(1) for details. +.IP +.IP "\fBcheckpresentkey key remote\fP" +Check if key is present in remote. +.IP +See git-annex\-checkpresentkey(1) for details. +.IP +.IP "\fBrekey [file key ...]\fP" +Change keys used for files. +.IP +See git-annex\-rekey(1) for details. +.IP +.IP "\fBresolvemerge\fP" +Resolves a conflicted merge, by adding both conflicting versions of the +file to the tree, using variants of their filename. This is done +automatically when using \fBgit annex sync\fP or \fBgit-annex pull\fP +or \fBgit annex merge\fP. +.IP +See git-annex\-resolvemerge(1) for details. +.IP +.IP "\fBdiffdriver\fP" +This can be used to make \fBgit diff\fP diff the content of annexed files. +.IP +See git-annex\-diffdriver(1) for details. +.IP +.IP "\fBsmudge\fP" +This command lets git-annex be used as a git filter driver, allowing +annexed files in the git repository to be unlocked regular files instead +of symlinks. +.IP +See git-annex\-smudge(1) for details. +.IP +.IP "\fBfilter\-process\fP" +An alternative implementation of a git filter driver, that is faster +in some situations and slower in others than \fBgit-annex smudge\fP. +.IP +See git-annex\-filter\-process(1) for details. +.IP +.IP "\fBrestage\fP" +Restages unlocked files in the git index. +.IP +See git-annex\-restage(1) for details. +.IP +.IP "\fBfindref [ref]\fP" +Lists files in a git ref. (deprecated) +.IP +See git-annex\-findref(1) for details. +.IP +.IP "\fBproxy \-\- git cmd [options]\fP" +Bypass direct mode guard. (deprecated) +.IP +See git-annex\-proxy(1) for details. +.IP +.SH TESTING COMMANDS +.IP "\fBtest\fP" +.IP +This runs git-annex's built\-in test suite. +.IP +See git-annex\-test(1) for details. +.IP +.IP "\fBtestremote remote\fP" +This tests a remote by generating some random objects and sending them to +the remote, then redownloading them, removing them from the remote, etc. +.IP +It's safe to run in an existing repository (the repository contents are +not altered), although it may perform expensive data transfers. +.IP +See git-annex\-testremote(1) for details. +.IP +.IP "\fBsim\fP" +This simulates a network of git-annex repositories. It can be used to +test a configuration before using it in the real world. +.IP +See git-annex\-sim(1) for details. +.IP +.IP "\fBfuzztest\fP" +Generates random changes to files in the current repository, +for use in testing the assistant. +.IP +See git-annex\-fuzztest(1) for details. +.IP +.IP "\fBbenchmark\fP" +This runs git-annex's built\-in benchmarks, if it was built with +benchmarking support. +.IP +See git-annex\-benchmark(1) for details. +.IP +.SH ADDON COMMANDS +In addition to all the commands listed above, more commands can be added to +git-annex by dropping commands named like "git-annex\-foo" into a directory +in the PATH. +.PP +.SH CONFIGURATION +Like other git commands, git-annex is configured via \fB.git/config\fP. +These settings, as well as relevant git config settings, are +the ones git-annex uses. +.PP +(Some of these settings can also be set, across all clones of the +repository, using git-annex\-config. See its man page for a list.) +.PP +.IP "\fBannex.uuid\fP" +A unique UUID for this repository (automatically set). +.IP +.IP "\fBannex.backend\fP" +Name of the default key\-value backend to use when adding new files +to the repository. See git-annex\-backends(1) for information about +available backends. +.IP +This is overridden by annex annex.backend configuration in the +\&.gitattributes files, and by the \-\-backend option. +.IP +(This used to be named \fBannex.backends\fP, and that will still be used +if set.) +.IP +.IP "\fBannex.securehashesonly\fP" +Set to true to indicate that the repository should only use +cryptographically secure hashes (SHA2, SHA3) and not insecure +hashes (MD5, SHA1) for content. +.IP +When this is set, the contents of files using cryptographically +insecure hashes will not be allowed to be added to the repository. +.IP +Also, \fBgit-annex fsck\fP will complain about any files present in +the repository that use insecure hashes. And, +\fBgit-annex import \-\-no\-content\fP will refuse to import files +from special remotes using insecure hashes. +.IP +To configure the behavior in new clones of the repository, +this can be set using git-annex\-config. +.IP +.IP "\fBannex.maxextensionlength\fP" +Maximum length, in bytes, of what is considered a filename extension. +This is used when adding a file to a backend that preserves filename extensions, +and also when generating a view branch. +.IP +The default length is 4, which allows extensions like "jpeg". The dot before +the extension is not counted part of its length. +.IP +.IP "\fBannex.maxextensions\fP" +Maximum number of filename extensions to preserve when using a backend +that preserves filename extensions, and also when generating a view +branch. +.IP +The default is 2, which allows for compound extensions like ".tar.gz". +When set to 1, it will only preserve the last extension, eg ".gz". +.IP +.IP "\fBannex.diskreserve\fP" +Amount of disk space to reserve. Disk space is checked when transferring +annexed content to avoid running out, and additional free space can be +reserved via this option, to make space for other data (such as git +commit logs). Can be specified with any commonly used units, for +example, "0.5 gb", "500M", or "100 KiloBytes" +.IP +The default reserve is 100 megabytes. +.IP +.IP "\fBannex.fullybalancedthreshhold\fP" +Configures the percent full a repository must be in order for +the "fullybalanced" preferred content expression to consider it +to be full. The default is 90. +.IP +.IP "\fBannex.skipunknown\fP" +Set to true to make commands like "git-annex get" silently skip over +items that are listed in the command line, but are not checked into git. +.IP +Set to false to make it an error for commands like "git-annex get" +to be asked to operate on files that are not checked into git. +(This is the default in recent versions of git-annex.) +.IP +Note that, when annex.skipunknown is false, a command like "git-annex get +\&." will fail if no files in the current directory are checked into git. +Commands like "git-annex get foo/" will fail if no files in the directory +are checked into git, but if at least one file is, it will ignore other +files that are not. This is all the same as the behavior of "git\-ls files +\-\-error\-unmatch". +.IP +Also note that git-annex skips files that are checked into git, but are +not annexed files; this setting does not affect that. +.IP +.IP "\fBannex.largefiles\fP" +Used to configure which files are large enough to be added to the annex. +It is an expression that matches the large files, eg +"\fBinclude=*.mp3 or largerthan=500kb\fP" +See git-annex\-matching\-expression(1) for details on the syntax. +.IP +Overrides any annex.largefiles attributes in \fB.gitattributes\fP files. +.IP +To configure a default annex.largefiles for all clones of the repository, +this can be set in git-annex\-config(1). +.IP +This configures the behavior of both git-annex and git when adding +files to the repository. By default, \fBgit-annex add\fP adds all files +to the annex (except dotfiles and files in dotdirs), and \fBgit add\fP +adds files to git (unless they were added to the annex previously). +When annex.largefiles is configured, both +\fBgit annex add\fP and \fBgit add\fP will add matching large files to the +annex, and the other files to git. +.IP +Other git-annex commands also honor annex.largefiles, including +\fBgit annex import\fP, \fBgit annex addurl\fP, \fBgit annex importfeed\fP, +\fBgit-annex assist\fP, and the \fBgit-annex assistant\fP. +.IP +.IP "\fBannex.dotfiles\fP" +Normally, dotfiles and files inside dotdirs are assumed to be +configuration files like .gitignore, whose content should always +be part of the git repository, so they will not be added to the annex. +Setting annex.dotfiles to true makes these files be added to the +annex the same as any other file. +.IP +To annex only some dotfiles, set this and configure annex.largefiles +to match the ones you want. For example, to match only dotfiles ending +in ".big" +.IP + git config annex.largefiles "(include=.*.big or include=*/.*.big) or (exclude=.* and exclude=*/.*)" + git config annex.dotfiles true +.IP +To configure a default annex.dotfiles for all clones of the repository, +this can be set in git-annex\-config(1). +.IP +.IP "\fBannex.gitaddtoannex\fP" +Setting this to false will prevent \fBgit add\fP from adding +files to the annex, despite the annex.largefiles configuration. +.IP +.IP "\fBannex.addsmallfiles\fP" +Controls whether small files (files not matching annex.largefiles, or +dotfiles) should be checked into git by \fBgit annex add\fP. Defaults to true; +set to false to instead make small files be skipped. +.IP +.IP "\fBannex.addunlocked\fP" +Commands like \fBgit-annex add\fP default to adding files to the repository +in locked form. This can make them add the files in unlocked form, +the same as if git-annex\-unlock(1) were run on the files. +.IP +This can be set to "true" to add everything unlocked, or it can be a more +complicated expression that matches files by name, size, or content. See +git-annex\-matching\-expression(1) for details. +.IP +To configure a default annex.addunlocked for all clones of the repository, +this can be set in git-annex\-config(1). +.IP +(Using \fBgit add\fP always adds files in unlocked form and it is not +affected by this setting.) +.IP +When a repository has core.symlinks set to false, or has an adjusted +unlocked branch checked out, this setting is ignored, and files are +always added to the repository in unlocked form. +.IP +.IP "\fBannex.numcopies\fP" +This is a deprecated setting. You should instead use the +\fBgit annex numcopies\fP command to configure how many copies of files +are kept across all repositories, or the annex.numcopies .gitattributes +setting. +.IP +This config setting is only looked at when \fBgit annex numcopies\fP has +never been configured, and when there's no annex.numcopies setting in the +\&.gitattributes file. +.IP +.IP "\fBannex.genmetadata\fP" +Set this to \fBtrue\fP to make git-annex automatically generate some metadata +when adding files to the repository. +.IP +In particular, it stores year, month, and day metadata, from the file's +modification date. +.IP +When importfeed is used, it stores additional metadata from the feed, +such as the author, title, etc. +.IP +.IP "\fBannex.used\-refspec\fP" +This controls which refs \fBgit-annex unused\fP considers to be used. +See REFSPEC FORMAT in git-annex\-unused(1) for details. +.IP +.IP "\fBannex.jobs\fP" +Configure the number of concurrent jobs to run. Default is 1. +.IP +Only git-annex commands that support the \-\-jobs option will +use this. +.IP +Setting this to "cpus" will run one job per CPU core. +.IP +When the \fB\-\-batch\fP option is used, this configuration is ignored. +.IP +.IP "\fBannex.adjustedbranchrefresh\fP" +When git-annex\-adjust(1) is used to set up an adjusted branch +that needs to be refreshed after getting or dropping files, this config +controls how frequently the branch is refreshed. +.IP +Refreshing the branch takes some time, so doing it after every file +can be too slow. (It also can generate a lot of dangling git objects.) +The default value is 0 (or false), which does not +refresh the branch. Setting 1 (or true) will refresh only once, +after git-annex has made other changes. Setting 2 refreshes after every +file, 3 after every other file, and so on; setting 100 refreshes after +every 99 files. +.IP +(If git-annex gets faster in the future, refresh rates will increase +proportional to the speed improvements.) +.IP +.IP "\fBannex.queuesize\fP" +git-annex builds a queue of git commands, in order to combine similar +commands for speed. By default the size of the queue is limited to +10240 commands; this can be used to change the size. If you have plenty +of memory and are working with very large numbers of files, increasing +the queue size can speed it up. +.IP +.IP "\fBannex.bloomcapacity\fP" +The \fBgit annex unused\fP and \fBgit annex sync \-\-content\fP commands use +a bloom filter to determine what files are present in eg, the work tree. +The default bloom filter is sized to handle +up to 500000 files. If your repository is larger than that, +you should increase this value. Larger values will +make \fBgit-annex unused\fP and \fBgit annex sync \-\-content\fP consume more memory; +run \fBgit annex info\fP for memory usage numbers. +.IP +.IP "\fBannex.bloomaccuracy\fP" +Adjusts the accuracy of the bloom filter used by +\fBgit annex unused\fP and \fBgit annex sync \-\-content\fP. +The default accuracy is 10000000 \-\- 1 unused file out of 10000000 +will be missed by \fBgit annex unused\fP. Increasing the accuracy will make +\fBgit annex unused\fP consume more memory; run \fBgit annex info\fP +for memory usage numbers. +.IP +.IP "\fBannex.sshcaching\fP" +By default, git-annex caches ssh connections using ssh's +ControlMaster and ControlPersist settings +(if built using a new enough ssh). To disable this, set to \fBfalse\fP. +.IP +.IP "\fBannex.adviceNoSshCaching\fP" +When git-annex is unable to use ssh connection caching, or has been +configured not to, and concurrency is enabled, it will warn that +this might result in multiple ssh processes prompting for passwords +at the same time. To disable that warning, eg if you have configured ssh +connection caching yourself, or have ssh agent caching passwords, +set this to \fBfalse\fP. +.IP +.IP "\fBannex.alwayscommit\fP" +By default, git-annex automatically commits data to the git-annex branch +after each command is run. If you have a series +of commands that you want to make a single commit, you can +run the commands with \fB\-c annex.alwayscommit=false\fP. You can later +commit the data by running \fBgit annex merge\fP (or by automatic merges) +or \fBgit annex sync\fP. +.IP +.IP "\fBannex.commitmessage\fP" +When git-annex updates the git-annex branch, it usually makes up +its own commit message (eg "update"), since users rarely look at or +care about changes to that branch. If you do care, you can +specify this setting by running commands with +\fB\-c annex.commitmessage=whatever\fP +.IP +This works well in combination with annex.alwayscommit=false, +to gather up a set of changes and commit them with a message you specify. +.IP +.IP "\fBannex.commitmessage\-command\fP" +This command is run and its output is used as the commit message to the +git-annex branch. +.IP +Alternatively, a hook script can be installed in +\fB.git/hooks/commitmessage\-annex\fP +.IP +.IP "\fBannex.post\-update\-command\fP" +This command is run after git-annex updates the git-annex branch. +.IP +When publishing a git-annex repository by http, this can be used to run +\fBgit update\-server\-info\fP +.IP +Alternatively, a hook script can be installed in +\fB.git/hooks/post\-update\-annex\fP +.IP +.IP "\fBannex.pre\-commit\-command\fP" +This command is run whenever a commit is made to the HEAD branch of +the git repository, either by git commit, or by git-annex. +.IP +Alternatively, a hook script can be installed in +\fB.git/hooks/pre\-commit\-annex\fP +.IP +.IP "\fBannex.pre\-init\-command\fP" +This command is run before the repository is initialized, either by +\fBgit-annex init\fP, or automatic initialization. It can configure +the repository in any way needed. If it exits nonzero, the repository +initialization will fail. +.IP +Alternatively, a hook script can be installed in +\fB.git/hooks/pre\-init\-annex\fP +.IP +.IP "\fBannex.alwayscompact\fP" +By default, git-annex compacts data it records in the git-annex branch. +Setting this to false avoids doing that compaction in some cases, which +can speed up operations that populate the git-annex branch with a lot +of data. However, when used with operations that overwrite old values in +the git-annex branch, that may cause the git-annex branch to use more disk +space, and so slow down reading data from it. +.IP +An example of a command that can be sped up by using +\fB\-c annex.alwayscompact=false\fP is \fBgit-annex registerurl \-\-batch\fP, +when adding a large number of urls to the same key. +.IP +This option was first supported by git-annex version 10.20220724. +It is not entirely safe to set this option in a repository that may also +be used by an older version of git-annex at the same time as a version +that supports this option. +.IP +.IP "\fBannex.allowsign\fP" +By default git-annex avoids gpg signing commits that it makes when +they're not the purpose of a command, but only a side effect. +That default avoids lots of gpg password prompts when +commit.gpgSign is set. A command like \fBgit annex sync\fP or \fBgit annex merge\fP +will gpg sign its commit, but a command like \fBgit annex get\fP, +that updates the git-annex branch, will not. The assistant also avoids +signing commits. +.IP +Setting annex.allowsign to true lets all commits be signed, as +controlled by commit.gpgSign and other git configuration. +.IP +.IP "\fBannex.merge\-annex\-branches\fP" +By default, git-annex branches that have been pulled from remotes +are automatically merged into the local git-annex branch, so that +git-annex has the most up\-to\-date possible knowledge. +.IP +To avoid that merging, set this to "false". +.IP +This can be useful particularly when you don't have write permission +to the repository. While git-annex is mostly able to work in a read\-only +repository with unmerged git-annex branches, some things do not work, +and when it does work it will be slower due to needing to look at each of +the unmerged branches. +.IP +.IP "\fBannex.private\fP" +When this is set to true, no information about the repository will be +recorded in the git-annex branch. +.IP +For example, to make a repository without any mention of it ever +appearing in the git-annex branch: +.IP + git init myprivate + cd myprivaterepo + git config annex.private true + git annex init +.IP +.IP "\fBannex.hardlink\fP" +Set this to \fBtrue\fP to make file contents be hard linked between the +repository and its remotes when possible, instead of a more expensive copy. +.IP +Use with caution \-\- This can invalidate numcopies counting, since +with hard links, fewer copies of a file can exist. So, it is a good +idea to mark a repository using this setting as untrusted. +.IP +When a repository is set up using \fBgit clone \-\-shared\fP, git-annex init +will automatically set annex.hardlink and mark the repository as +untrusted. +.IP +When \fBannex.thin\fP is also set, setting \fBannex.hardlink\fP has no effect. +.IP +.IP "\fBannex.thin\fP" +Set this to \fBtrue\fP to make unlocked files be a hard link to their content +in the annex, rather than a second copy. This can save considerable +disk space, but when a modification is made to a file, you will lose the +local (and possibly only) copy of the old version. Any other, locked +files in the repository that pointed to that content will get broken +as well (\fBgit-annex fsck\fP will detect and clean up after that). +So, enable this with care. +.IP +After setting (or unsetting) this, you should run \fBgit annex fix\fP to +fix up the annexed files in the work tree to be hard links (or copies). +.IP +Note that this has no effect when the filesystem does not support hard links. +And when multiple files in the work tree have the same content, only +one of them gets hard linked to the annex. +.IP +.IP "\fBannex.supportunlocked\fP" +By default git-annex supports unlocked files as well as locked files, +so this defaults to true. If set to false, git-annex will only support +locked files. That will avoid doing the work needed to support unlocked +files. +.IP +Note that setting this to false does not prevent a repository from +having unlocked files added to it, and in that case the content of the +files will not be accessible until they are locked. +.IP +After changing this config, you need to re\-run \fBgit-annex init\fP for it +to take effect. +.IP +.IP "\fBannex.url\fP" +When a remote has a http url, the first time git-annex uses the remote +it will check if it can download its \fB.git/config\fP file. If it is able +to, and the file has this config set to an "annex+http" or "annex+https" +url, that url will be copied into \fBremote..annexUrl\fP. +.IP +.IP "\fBannex.resolvemerge\fP" +Set to false to prevent merge conflicts in the checked out branch +being automatically resolved by the \fBgit-annex assitant\fP, +\fBgit-annex assist\fP, \fBgit-annex sync\fP, \fBgit-annex pull\fP, \fBgit-annex merge\fP, +and the git-annex post\-receive hook. +.IP +To configure the behavior in all clones of the repository, +this can be set in git-annex\-config(1). +.IP +.IP "\fBannex.synccontent\fP" +Set to true to make \fBgit-annex sync\fP default to transferring +annexed content. +.IP +Set to false to prevent \fBgit-annex assist\fP, \fBgit-annex pull\fP and +\fBgit-annex push\fP from transferring annexed content. +.IP +To configure the behavior in all clones of the repository, +this can be set in git-annex\-config(1). +.IP +.IP "\fBannex.synconlyannex\fP" +Set to true to make \fBgit-annex assist\fP, \fBgit-annex sync\fP, +\fBgit-annex pull\fP, and \fBgit-annex push\fP default to only operating +on the git-annex branch and annexed content. +.IP +To configure the behavior in all clones of the repository, +this can be set in git-annex\-config(1). +.IP +.IP "\fBannex.syncmigrations\fP" +Set to false to prevent \fBgit-annex sync\fP and \fBgit-annex pull\fP +from scanning for migrations and updating the local +repository for those migrations. +.IP +.IP "\fBannex.viewunsetdirectory\fP" +This configures the name of a directory that is used in a view to contain +files that do not have metadata set. The default name for the directory +is \fB"_"\fP. See git-annex\-view(1) for details. +.IP +.IP "\fBannex.debug\fP" +Set to true to enable debug logging by default. +.IP +.IP "\fBannex.debugfilter\fP" +Set to configure which debug messages to display (when debug message +display has been enabled by annex.debug or \-\-debug). The value is one +or more module names, separated by commas. +.IP +.IP "\fBannex.version\fP" +The current version of the git-annex repository. This is +maintained by git-annex and should never be manually changed. +.IP +.IP "\fBannex.autoupgraderepository\fP" +When an old git-annex repository version is no longer supported, +git-annex will normally automatically upgrade the repository to +the new version. It may also sometimes upgrade from an old repository +version that is still supported but that is not as good as a later +version. +.IP +If this is set to false, git-annex won't automatically upgrade the +repository. If the repository version is not supported, git-annex +will instead exit with an error message. If it is still supported, +git-annex will continue to work. +.IP +You can run \fBgit annex upgrade\fP yourself when you are ready to upgrade the +repository. +.IP +.IP "\fBannex.crippledfilesystem\fP" +Set to true if the repository is on a crippled filesystem, such as FAT, +which does not support symbolic links, or hard links, or unix permissions. +This is automatically probed by "git annex init". +.IP +.IP "\fBannex.pidlock\fP" +Normally, git-annex uses fine\-grained lock files to allow multiple +processes to run concurrently without getting in each others' way. +That works great, unless you are using git-annex on a filesystem that +does not support POSIX fcntl locks. This is sometimes the case when +using NFS or Lustre filesystems. +.IP +To support such situations, you can set annex.pidlock to true, and it +will fall back to a single top\-level pid file lock. +.IP +Although, often, you'd really be better off fixing your networked +filesystem configuration to support POSIX locks.. And, some networked +filesystems are so inconsistent that one node can't reliably tell when +the other node is holding a pid lock. Caveat emptor. +.IP +.IP "\fBannex.pidlocktimeout\fP" +git-annex will wait up to this many seconds for the pid lock +file to go away, and will then abort if it cannot continue. Default: 300 +.IP +When using pid lock files, it's possible for a stale lock file to get +left behind by previous run of git-annex that crashed or was interrupted. +This is mostly avoided, but can occur especially when using a network +file system. This timeout prevents git-annex waiting forever in such a +situation. +.IP +.IP "\fBannex.dbdir\fP" +The directory where git-annex should store its sqlite databases. +The default location is inside \fB.git/annex/\fP. +.IP +Certian filesystems, such as cifs, may not support locking operations +that sqlite needs, and setting this to a directory on another filesystem +can work around such a problem. +.IP +This can safely be set to the same directory in the configuration of +multiple repositories; each repository will use a subdirectory for its +sqlite database. +.IP +.IP "\fBannex.cachecreds\fP" +When "true" (the default), git-annex will cache credentials used to +access special remotes in files in .git/annex/creds/ +that only you can read. To disable that caching, set to "false", +and credentials will only be read from the environment, or if +they have been embedded in encrypted form in the git repository, will +be extracted and decrypted each time git-annex needs to access the +remote. +.IP +.IP "\fBannex.secure\-erase\-command\fP" +This can be set to a command that should be run whenever git-annex +removes the content of a file from the repository. +.IP +In the command line, %file is replaced with the file that should be +erased. +.IP +For example, to use the wipe command, set it to \fBwipe \-f %file\fP. +.IP +Alternatively to setting the git config, a hook script can be installed +in \fB.git/hooks/secure\-erase\-annex\fP. The hook is passed the file to be +erased as its only parameter. +.IP +.IP "\fBannex.freezecontent\-command\fP, \fBannex.thawcontent\-command\fP" +Usually the write permission bits are unset to protect annexed objects +from being modified or deleted. Freezecontent is run after +git-annex has removed (or attempted to remove) the write bit, and can +be used to prevent writing in some other way. +Thawcontent should undo its effect, and is run before +git-annex restores the write bit. +.IP +In the command line, %path is replaced with the file or directory to +operate on. +.IP +(When annex.crippledfilesystem is set, git-annex will not try to +remove/restore the write bit, but it will still run freezecontent and +thawcontent.) +.IP +Alternatively to setting the git config, hook scripts can be installed +in \fB.git/hooks/freezecontent\-annex\fP and \fB.git/hooks/thawcontent\-annex\fP. +The hook is passed the file or directory to operate on as its only +parameter. +.IP +.IP "\fBannex.tune.objecthash1\fP, \fBannex.tune.objecthashlower\fP, \fBannex.tune.branchhash1\fP" +These can be passed to \fBgit annex init\fP to tune the repository. +They cannot be safely changed in a running repository and should never be +set in global git configuration. +For details, see . +.IP +.IP "\fBannex.cluster.\fP" +This is set to make the repository be a gateway to a cluster. +The value is the cluster UUID. Note that cluster UUIDs are not +the same as repository UUIDs, and a repository UUID cannot be used here. +.IP +Usually this is set up by running git-annex\-initcluster or +git-annex\-extendcluster. +.IP +.SH CONFIGURATION OF REMOTES +Remotes are configured using these settings in \fB.git/config\fP. +.PP +.IP "\fBremote..annex\-cost\fP" +When determining which repository to +transfer annexed files from or to, ones with lower costs are preferred. +The default cost is 100 for local repositories, and 200 for remote +repositories. +.IP +.IP "\fBremote..annex\-cost\-command\fP" +If set, the command is run, and the number it outputs is used as the cost. +This allows varying the cost based on e.g., the current network. +.IP +.IP "\fBremote..annex\-start\-command\fP" +A command to run when git-annex begins to use the remote. This can +be used to, for example, mount the directory containing the remote. +.IP +The command may be run repeatedly when multiple git-annex processes +are running concurrently. +.IP +.IP "\fBremote..annex\-stop\-command\fP" +A command to run when git-annex is done using the remote. +.IP +The command will only be run once *all* running git-annex processes +are finished using the remote. +.IP +.IP "\fBremote..annex\-shell\fP" +Specify an alternative git-annex\-shell executable on the remote +instead of looking for "git-annex\-shell" on the PATH. +.IP +This is useful if the git-annex\-shell program is outside the PATH +or has a non\-standard name. +.IP +.IP "\fBremote..annex\-ignore\fP" +If set to \fBtrue\fP, prevents git-annex from storing or retrieving annexed +file contents on this remote by default. +(You can still request it be used with the \fB\-\-from\fP and \fB\-\-to\fP options.) +.IP +This is, for example, useful if the remote is located somewhere +without git-annex\-shell. (For example, if it's on GitHub). +Or, it could be used if the network connection between two +repositories is too slow to be used normally. +.IP +This does not prevent \fBgit-annex sync\fP, \fBgit-annex pull\fP, \fBgit-annex push\fP, +\fBgit-annex assist\fP or the \fBgit-annex assistant\fP from operating on the +git repository. It only affects annexed content. +.IP +.IP "\fBremote..annex\-ignore\-command\fP" +If set, the command is run, and if it exits nonzero, that's the same +as setting annex\-ignore to true. This allows controlling behavior based +on e.g., the current network. +.IP +.IP "\fBremote..annex\-sync\fP" +If set to \fBfalse\fP, prevents \fBgit-annex sync\fP (and \fBgit-annex pull\fP, +\fBgit-annex push\fP, \fBgit-annex assist\fP, and the \fBgit-annex assistant\fP) +from operating on this remote by default. +.IP +.IP "\fBremote..annex\-sync\-command\fP" +If set, the command is run, and if it exits nonzero, that's the same +as setting annex\-sync to false. This allows controlling behavior based +on e.g., the current network. +.IP +.IP "\fBremote..annex\-pull\fP" +If set to \fBfalse\fP, prevents \fBgit-annex pull\fP, \fBgit-annex sync\fP, +\fBgit-annex assist\fP and the \fBgit-annex assistant\fP from ever pulling +(or fetching) from the remote. +.IP +.IP "\fBremote..annex\-push\fP" +If set to \fBfalse\fP, prevents \fBgit-annex push\fP, \fBgit-annex sync\fP, +\fBgit-annex assist\fP and the \fBgit-annex assistant\fP from ever pushing +to the remote. +.IP +.IP "\fBremote..annex\-readonly\fP" +If set to \fBtrue\fP, prevents git-annex from making changes to a remote. +This prevents \fBgit-annex sync\fP and \fBgit-annex assist\fP from pushing +changes to a git repository. And it prevents storing or removing +files from read\-only remote. +.IP +.IP "\fBremote..annex\-verify\fP, \fBannex.verify\fP" +By default, git-annex will verify the checksums of objects downloaded +from remotes. If you trust a remote and don't want the overhead +of these checksums, you can set this to \fBfalse\fP. +.IP +Note that even when this is set to \fBfalse\fP, git-annex does verification +in some edge cases, where it's likely the case than an +object was downloaded incorrectly, or when needed for security. +.IP +.IP "\fBremote..annex\-tracking\-branch\fP" +This is for use with special remotes that support exports and imports. +.IP +When set to eg, "master", this tells git-annex that you want the +special remote to track that branch. +.IP +When set to eg, "master:subdir", the special remote tracks only +the subdirectory of that branch. +.IP +Setting this enables some other commands to work with these special +remotes: \fBgit-annex pull\fP will import changes from the remote and merge them into +the annex\-tracking\-branch. And \fBgit-annex push\fP will export changes to +the remote. Higher\-level commands \fBgit-annex sync \-\-content\fP +and \fBgit-annex assist\fP both import and export. +.IP +.IP "\fBremote..annex\-export\-tracking\fP" +Deprecated name for \fBremote..annex\-tracking\-branch\fP. Will still be used +if it's configured and \fBremote..annex\-tracking\-branch\fP is not. +.IP +.IP "\fBremote..annexUrl\fP" +Can be used to specify a different url than the regular \fBremote..url\fP +for git-annex to use for accessing the remote. Similar to the \fBpushUrl\fP +used by git\-push. +.IP +When this is set to an annex+http or annex+https url, that url is used +for git-annex operations only, and the \fBremote..url\fP is used for +git operations. This allows using git-annex\-p2phttp to serve a +git-annex repository over http. +.IP +When this and the \fBremote..url\fP contain the same hostname, +and this is an annex+http(s) url, and that is also a http(s) url, +git-annex assumes that the same username and password can be used +for both urls. When password caching is configured, this allows +you to only be prompted once for a password when using both git and +git-annex. See gitcredentials(7) for how to set up password caching. +.IP +.IP "\fBurl..annexInsteadOf\fP" +This works similarly to git's \fBurl..pushInsteadOf\fP, rewriting +a remote url that starts with the value of this config to instead +start with \fB\fP. +.IP +The rewritten url is used by git-annex for accessing the remote, +and works the same as \fBremote..annexUrl\fP, including supporting +annex+http urls. +.IP +Note that git-annex also supports git's \fBurl..insteadOf\fP +configuration. When both are set, the remote's url is first rewritten +by insteadOf, and that rewritten url can then be further +rewritten using annexInsteadOf. +.IP +.IP "\fBremote..annex\-uuid\fP" +git-annex caches UUIDs of remote repositories here. +.IP +.IP "\fBremote..annex\-config\-uuid\fP" +Used for some special remotes, points to a different special remote +configuration to use. +.IP +.IP "\fBremote..annex\-retry\fP, \fBannex.retry\fP" +Number of times a transfer that fails can be retried. (default 0) +.IP +.IP "\fBremote..annex\-forward\-retry\fP, \fBannex.forward\-retry\fP" +If a transfer made some forward progress before failing, +this allows it to be retried even when \fBannex.retry\fP does not. +The value is the maximum number of times to do that. (default 5) +.IP +When both \fBannex.retry\fP and this are set, the maximum number of +retries is the larger of the two. +.IP +.IP "\fBremote..annex\-retry\-delay\fP, \fBannex.retry\-delay\fP" +Number of seconds to delay before the first retry of a transfer. +When making multiple retries of the same transfer, the delay +doubles after each retry. (default 1) +.IP +.IP "\fBremote..annex\-bwlimit\fP, \fBannex.bwlimit\fP" +This can be used to limit how much bandwidth is used for a transfer +from or to a remote. +.IP +For example, to limit transfers to 1 mebibyte per second: +\fBgit config annex.bwlimit "1MiB"\fP +.IP +This will work with many remotes, including git remotes, but not +for remotes where the transfer is run by a separate program than +git-annex. +.IP +.IP "\fBremote..annex\-bwlimit\-download\fP, \fBannex.bwlimit\-download\fP" +Limit bandwith for downloads from a remote. +.IP +Overrides \fBremote..annex\-bwlimit\fP and \fBannex.bwlimit\fP +.IP +.IP "\fBremote..annex\-bwlimit\-upload\fP, \fBannex.bwlimit\-upload\fP" +Limit bandwith for uploads to a remote. +.IP +Overrides \fBremote..annex\-bwlimit\fP and \fBannex.bwlimit\fP +.IP +.IP "\fBremote..annex\-stalldetection\fP, \fBannex.stalldetection\fP" +Configuring this lets stalled or too\-slow transfers be detected, and +dealt with, so rather than getting stuck, git-annex will cancel the +stalled operation. The transfer will be considered to have failed, so +settings like annex.retry will control what it does next. +.IP +The default is to automatically detect when transfers that have probably +stalled, and suggest configuring this, but not cancel the stalled +operations. For this to work, a remote needs to update its progress +consistently. Remotes that do not will not have automatic stall detection +done. And it may take a while for git-annex to decide a remote is really +stalled when using automatic stall detection, since it needs to be +conservative about what looks like a stall. +.IP +Set to "false" to avoid all attempts at stall detection. +.IP +To detect and cancel stalled transfers, set this to a value in the form +"$amount/$timeperiod" which specifies how much data git-annex should +expect to see flowing, minimum, over a given period of time. +.IP +For example, to detect outright stalls where no data has been transferred +after 30 seconds: \fBgit config annex.stalldetection "1KB/30s"\fP +.IP +Or, if you have a remote on a USB drive that is normally capable of +several megabytes per second, but has bad sectors where it gets +stuck for a long time, you could use: +\fBgit config remote.usbdrive.annex\-stalldetection "1MB/1m"\fP +.IP +Some remotes don't report transfer progress, and stalls cannot be +detected when using those. +.IP +Some remotes only report transfer progress occasionally, eg +after each chunk. To avoid false timeouts in such a situation, if the +first progress update takes longer to arrive than the configured time +period, the stall detection will be automically adjusted to use a longer +time period. For example, if the first progress update comes after 10 +minutes, but annex.stalldetection is "1MB/1m", it will be treated as eg +"30MB/30m". +.IP +Configuring stall detection can make git-annex use more resources. To be +able to cancel stalls, git-annex has to run transfers in separate +processes (one per concurrent job). So it may need to open more +connections to a remote than usual, or the communication with those +processes may make it a bit slower. +.IP +.IP "\fBremote..annex\-stalldetection\-download\fP, \fBannex.stalldetection\-download\fP" +Stall detection for downloads from a remote. +.IP +For example, if a remote is often fast, but sometimes is very slow, +and there is another remote that is consistently medium speed +and that contains the same data, this could be set to treat the fast +remote as stalled when it's slow. Then a command like \fBgit-annex get\fP +will fall back to downloading from the medium speed remote. +.IP +Overrides \fBremote..annex\-stalldetection\fP, \fBannex.stalldetection\fP +.IP +.IP "\fBremote..annex\-stalldetection\-upload\fP, \fBannex.stalldetection\-upload\fP" +Stall detection for uploads to a remote. +.IP +Overrides \fBremote..annex\-stalldetection\fP, \fBannex.stalldetection\fP +.IP +.IP "\fBremote..annex\-checkuuid\fP" +This only affects remotes that have their url pointing to a directory on +the same system. git-annex normally checks the uuid of such +remotes each time it's run, which lets it transparently deal with +different drives being mounted to the location at different times. +.IP +Setting annex\-checkuuid to false will prevent it from checking the uuid +at startup (although the uuid is still verified before making any +changes to the remote repository). This may be useful to set to prevent +unnecessary spin\-up or automounting of a drive. +.IP +.IP "\fBremote..annex\-trustlevel\fP" +Configures a local trust level for the remote. This overrides the value +configured by the trust and untrust commands. The value can be any of +"trusted", "semitrusted" or "untrusted". +.IP +.IP "\fBremote..annex\-speculate\-present\fP" +Set to "true" to make git-annex speculate that this remote may contain the +content of any file, even though its normal location tracking does not +indicate that it does. This will cause git-annex to try to get all file +contents from the remote. Can be useful in setting up a caching remote. + +.IP "\fBremote..annex\-proxy\fP" +.IP +Set to "true" to make the local repository able to act as a proxy to this +remote. The remote can be a git-annex repository or a special remote. +.IP +After configuring this, run [[git-annex\-updateproxy](1) to store +the new configuration in the git-annex branch. +.IP +.IP "\fBremote..annex\-proxied\-by\fP" +Usually this is used internally, when git-annex sets up proxied remotes, +and will not need to be configured. The value is the UUID of the +git-annex repository that proxies access to this remote. +.IP +.IP "\fBremote..annex\-cluster\-node\fP" +Set to the name of a cluster to make this remote be part of +the cluster. Names of multiple clusters can be separated by +whitespace to make a remote be part of more than one cluster. +.IP +After configuring this, run [[git-annex\-updatecluster](1) to store +the new configuration in the git-annex branch. +.IP +.IP "\fBremote..annex\-cluster\-gateway\fP" +Set to the UUID of a cluster that this remote serves as a gateway for. +Multiple UUIDs can be listed, separated by whitespace. When the local +repository is also a gateway for that cluster, it will proxy for the +nodes of the remote gateway. +.IP +Usually this is set up by running git-annex\-extendcluster. +.IP +.IP "\fBremote..annex\-private\fP" +When this is set to true, no information about the remote will be +recorded in the git-annex branch. This is mostly useful for special +remotes, and is set when using git-annex\-initremote(1) with the +\fB\-\-private\fP option. +.IP +.IP "\fBremote..annex\-max\-git\-bundles\fP, \fBannex.max\-git\-bundles\fP" +When using git\-remote\-annex to store a git repository in a special +remote, this configures how many separate git bundle objects to store +in the special remote before re\-uploading a single git bundle that contains +the entire git repository. +.IP +The default is 100, which aims to avoid often needing to often re\-upload, +while preventing a clone or fetch needing to download too many objects. +Set to 0 to disable re\-uploading. +.IP +.IP "\fBremote..annex\-allow\-encrypted\-gitrepo\fP" +Setting this to true allows using git\-remote\-annex to push the git +repository to an encrypted special remote. +.IP +That is not allowed by default, because it is impossible to git clone +from an encrypted special remote, since it needs encryption keys stored +in the remote. So take care that, if you set this, you don't rely +on the encrypted special remote being the only copy of your git repository. +.IP +.IP "\fBremote..annex\-bare\fP" +Can be used to tell git-annex if a remote is a bare repository +or not. Normally, git-annex determines this automatically. +.IP +.IP "\fBremote..annex\-availability\fP" +This configuration setting is no longer used. +.IP +.IP "\fBremote..annex\-ssh\-options\fP" +Options to use when using ssh to talk to this remote. +.IP +.IP "\fBremote..annex\-rsync\-options\fP" +Options to use when using rsync +to or from this remote. For example, to force IPv6, and limit +the bandwidth to 100Kbyte/s, set it to \fB\-6 \-\-bwlimit 100\fP +.IP +Note that git-annex\-shell has a whitelist of allowed rsync options, +and others will not be be passed to the remote rsync. So using some +options may break the communication between the local and remote rsyncs. +.IP +.IP "\fBremote..annex\-rsync\-upload\-options\fP" +Options to use when using rsync to upload a file to a remote. +.IP +These options are passed after other applicable rsync options, +so can be used to override them. For example, to limit upload bandwidth +to 10Kbyte/s, set \fB\-\-bwlimit 10\fP. +.IP +.IP "\fBremote..annex\-rsync\-download\-options\fP" +Options to use when using rsync to download a file from a remote. +.IP +These options are passed after other applicable rsync options, +so can be used to override them. +.IP +.IP "\fBremote..annex\-rsync\-transport\fP" +The remote shell to use to connect to the rsync remote. Possible +values are \fBssh\fP (the default) and \fBrsh\fP, together with their +arguments, for instance \fBssh \-p 2222 \-c blowfish\fP; Note that the +remote hostname should not appear there, see rsync(1) for details. +When the transport used is \fBssh\fP, connections are automatically cached +unless \fBannex.sshcaching\fP is unset. +.IP +.IP "\fBremote..annex\-bup\-split\-options\fP" +Options to pass to bup split when storing content in this remote. +For example, to limit the bandwidth to 100Kbyte/s, set it to \fB\-\-bwlimit 100k\fP +(There is no corresponding option for bup join.) +.IP +.IP "\fBremote..annex\-gnupg\-options\fP" +Options to pass to GnuPG when it's encrypting data. For instance, to +use the AES cipher with a 256 bits key and disable compression, set it +to \fB\-\-cipher\-algo AES256 \-\-compress\-algo none\fP. (These options take +precedence over the default GnuPG configuration, which is otherwise +used.) +.IP +.IP "\fBremote..annex\-gnupg\-decrypt\-options\fP" +Options to pass to GnuPG when it's decrypting data. (These options take +precedence over the default GnuPG configuration, which is otherwise +used.) +.IP +.IP "\fBremote..annex\-shared\-sop\-command\fP" +Use this command, which is an implementation of the Stateless OpenPGP +command line interface, rather than GnuPG for encrypting and decrypting +data. This is only used when a special remote is configured with +encryption=shared. +.IP +For example, to use Sequoia PGP's sqop command, set this to "sqop". +.IP +.IP "\fBremote..annex\-shared\-sop\-profile\fP" +When encrypting with a Stateless OpenPGP command, this can be used +to specify the profile to use, such as "rfc4880". +.IP +For a list of available profiles, run eg "sqop list\-profiles encrypt" +.IP +sqop list\-profiles encrypt +.IP +.IP "\fBannex.ssh\-options\fP, \fBannex.rsync\-options\fP," +\fBannex.rsync\-upload\-options\fP, \fBannex.rsync\-download\-options\fP, +\fBannex.bup\-split\-options\fP, \fBannex.gnupg\-options\fP, +\fBannex.gnupg\-decrypt\-options\fP, +\fBannex.shared\-sop\-command\fP, \fBannex.shared\-sop\-profile\fP +.IP +Default options to use if a remote does not have more specific options +as described above. +.IP +.IP "\fBremote..annex\-rsyncurl\fP" +Used by rsync special remotes, this configures +the location of the rsync repository to use. Normally this is automatically +set up by \fBgit annex initremote\fP, but you can change it if needed. +.IP +.IP "\fBremote..annex\-buprepo\fP" +Used by bup special remotes, this configures +the location of the bup repository to use. Normally this is automatically +set up by \fBgit annex initremote\fP, but you can change it if needed. +.IP +.IP "\fBremote..annex\-borgrepo\fP" +Used by borg special remotes, this configures +the location of the borg repository to use. Normally this is automatically +set up by \fBgit annex initremote\fP, but you can change it if needed. +.IP +.IP "\fBremote..annex\-compute\fP" +Used to identify compute special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-ddarrepo\fP" +Used by ddar special remotes, this configures +the location of the ddar repository to use. Normally this is automatically +set up by \fBgit annex initremote\fP, but you can change it if needed. +.IP +.IP "\fBremote..annex\-directory\fP" +Used by directory special remotes, this configures +the location of the directory where annexed files are stored for this +remote. Normally this is automatically set up by \fBgit annex initremote\fP, +but you can change it if needed. +.IP +.IP "\fBremote..annex\-adb\fP" +Used to identify remotes on Android devices accessed via adb. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-androiddirectory\fP" +Used by adb special remotes, this is the directory on the Android +device where files are stored for this remote. Normally this is +automatically set up by \fBgit annex initremote\fP, but you can change +it if needed. +.IP +.IP "\fBremote..annex\-androidserial\fP" +Used by adb special remotes, this is the serial number of the Android +device used by the remote. Normally this is automatically set up by +\fBgit annex initremote\fP, but you can change it if needed, eg when +upgrading to a new Android device. +.IP +.IP "\fBremote..annex\-s3\fP" +Used to identify Amazon S3 special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-glacier\fP" +Used to identify Amazon Glacier special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-rclone\fP" +Used to identify rclone special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-web\fP" +Used to identify web special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-webdav\fP" +Used to identify webdav special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-tahoe\fP" +Used to identify tahoe special remotes. +Points to the configuration directory for tahoe. +.IP +.IP "\fBremote..annex\-gcrypt\fP" +Used to identify gcrypt special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +It is set to "true" if this is a gcrypt remote. +If the gcrypt remote is accessible over ssh and has git-annex\-shell +available to manage it, it's set to "shell". +.IP +.IP "\fBremote..annex\-git\-lfs\fP" +Used to identify git\-lfs special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +It is set to "true" if this is a git\-lfs remote. +.IP +.IP "\fBremote..annex\-httpalso\fP" +Used to identify httpalso special remotes. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-mask\fP" +Used by mask special remotes, this is set to the name of the remote +that is masked. If this is set to "true", then any remote with the +right UUID will be used. +Normally this is automatically set up by \fBgit annex initremote\fP. +.IP +.IP "\fBremote..annex\-externaltype\fP" +Used by external special remotes to record the type of the remote. +.IP +Eg, if this is set to "foo", git-annex will run a "git-annex\-remote\-foo" +program to communicate with the external special remote. +.IP +If this is set to "readonly", then git-annex will not run any external +special remote program, but will try to access things stored in the +remote using http. That only works for some external special remotes, +so consult the documentation of the one you are using. +.IP +.IP "\fBremote..annex\-hooktype\fP" +Used by hook special remotes to record the type of the remote. +.IP +.IP "\fBannex.web\-options\fP, \fBremote..annex\-web\-options\fP" +Options to pass to curl when git-annex uses it to download urls +(rather than the default built\-in url downloader). +.IP +For example, to force IPv4 only, set it to "\-4". +.IP +Setting this makes git-annex use curl, but only +when annex.security.allowed\-ip\-addresses is configured in a +specific way. See its documentation. +.IP +Setting this prevents git-annex from using git\-credential +for prompting for http passwords. Instead, you can include "\-\-netrc" +to make curl use your ~/.netrc file and record the passwords there. +.IP +.IP "\fBannex.youtube\-dl\-options\fP" +Options to pass to yt\-dlp (or deprecated youtube\-dl) when using it to +find the url to download for a video. +.IP +Some options may break git-annex's integration with yt\-dlp. For +example, the \-\-output option could cause it to store files somewhere +git-annex won't find them. Avoid setting here or in the yt\-dlp config +file any options that cause it to download more than one file, +or to store the file anywhere other than the current working directory. +.IP +.IP "\fBannex.youtube\-dl\-command\fP" +Default is to use "yt\-dlp" or if that is not available in the PATH, +to use "youtube\-dl". +.IP +.IP "\fBannex.aria\-torrent\-options\fP" +Options to pass to aria2c when using it to download a torrent. +.IP +.IP "\fBannex.http\-headers\fP" +HTTP headers to send when downloading from the web. Multiple lines of +this option can be set, one per header. +.IP +.IP "\fBannex.http\-headers\-command\fP" +If set, the command is run and each line of its output is used as a HTTP +header. This overrides annex.http\-headers. +.IP +Alternatively, a hook script can be installed in +\fB.git/hooks/http\-headers\-annex\fP +.IP +.IP "\fBannex.security.allowed\-url\-schemes\fP" +List of URL schemes that git-annex is allowed to download content from. +The default is "http https ftp". +.IP +Think very carefully before changing this; there are security +implications. For example, if it's changed to allow "file" URLs, then +anyone who can get a commit into your git-annex repository could +\fBgit-annex addurl\fP a pointer to a private file located outside that +repository, possibly causing it to be copied into your repository +and transferred on to other remotes, exposing its content. +.IP +Any url schemes supported by curl can be listed here, but you will +also need to configure annex.security.allowed\-ip\-addresses to allow +using curl. +.IP +Some special remotes support their own domain\-specific URL +schemes; those are not affected by this configuration setting. +.IP +.IP "\fBannex.security.allowed\-ip\-addresses\fP" +By default, git-annex only makes connections to public IP addresses; +it will refuse to use HTTP and other servers on localhost or on a +private network. +.IP +This setting can override that behavior, allowing access to particular +IP addresses that would normally be blocked. For example "127.0.0.1 ::1" +allows access to localhost (both IPV4 and IPV6). +To allow access to all IP addresses, use "all" +.IP +Think very carefully before changing this; there are security +implications. Anyone who can get a commit into your git-annex repository +could \fBgit annex addurl\fP an url on a private server, possibly +causing it to be downloaded into your repository and transferred to +other remotes, exposing its content. +.IP +Note that, since the interfaces of curl and yt\-dlp do not allow +these IP address restrictions to be enforced, curl and yt\-dlp will +never be used unless annex.security.allowed\-ip\-addresses=all. +.IP +To allow accessing local or private IP addresses on only specific ports, +use the syntax "[addr]:port". For example, +"[127.0.0.1]:80 [127.0.0.1]:443 [::1]:80 [::1]:443" allows +localhost on the http ports only. +.IP +.IP "\fBannex.security.allowed\-http\-addresses\fP" +Old name for annex.security.allowed\-ip\-addresses. +If set, this is treated the same as having +annex.security.allowed\-ip\-addresses set. +.IP +.IP "\fBannex.security.allow\-unverified\-downloads\fP" +For security reasons, git-annex refuses to download content from +most special remotes when it cannot check a hash to verify +that the correct content was downloaded. This particularly impacts +downloading the content of URL or WORM keys, which lack hashes. +.IP +The best way to avoid problems due to this is to migrate files +away from such keys, before their content reaches a special remote. +See git-annex\-migrate(1). +.IP +When the content is only available from a special remote, you can +use this configuration to force git-annex to download it. +But you do so at your own risk, and it's very important you read and +understand the information below first! +.IP +Downloading unverified content from encrypted special remotes is +prevented, because the special remote could send some other encrypted +content than what you expect, causing git-annex to decrypt data that you +never checked into git-annex, and risking exposing the decrypted +data to any non\-encrypted remotes you send content to. +.IP +Downloading unverified content from (non\-encrypted) +external special remotes is prevented, because they could follow +http redirects to web servers on localhost or on a private network, +or in some cases to a file:/// url. +.IP +If you decide to bypass this security check, the best thing to do is +to only set it temporarily while running the command that gets the file. +The value to set the config to is "ACKTHPPT". +For example: +.IP + git \-c annex.security.allow\-unverified\-downloads=ACKTHPPT annex get myfile +.IP +It would be a good idea to check that it downloaded the file you expected, +too. +.IP +.IP "\fBremote..annex\-security\-allow\-unverified\-downloads\fP" +Per\-remote configuration of annex.security.allow\-unverified\-downloads. +.IP +.IP "\fBannex.security.allowed\-compute\-programs\fP" +This is a space separated list of compute programs eg +"git-annex\-compute\-foo git-annex\-compute\-bar". Listing a compute +program here allows compute special remotes that use that program to be +enabled by \fBgit-annex enableremote\fP or autoenabled. +.IP +.SH CONFIGURATION OF ASSISTANT +.IP "\fBannex.delayadd\fP" +.IP +Makes the watch and assistant commands delay for the specified number of +seconds before adding a newly created file to the annex. Normally this +is not needed, because they already wait for all writers of the file +to close it. +.IP +Note that this only delays adding files created while the daemon is +running. Changes made when it is not running will be added immediately +the next time it is started up. +.IP +.IP "\fBannex.expireunused\fP" +Controls what the assistant does about unused file contents +that are stored in the repository. +.IP +The default is \fBfalse\fP, which causes +all old and unused file contents to be retained, unless the assistant +is able to move them to some other repository (such as a backup repository). +.IP +Can be set to a time specification, like "7d" or "1m", and then +file contents that have been known to be unused for a week or a +month will be deleted. +.IP +.IP "\fBannex.fscknudge\fP" +When set to false, prevents the webapp from reminding you when using +repositories that lack consistency checks. +.IP +.IP "\fBannex.autoupgrade\fP" +When set to ask (the default), the webapp will check for new versions +and prompt if they should be upgraded to. When set to true, automatically +upgrades without prompting (on some supported platforms). When set to +false, disables any upgrade checking. +.IP +Note that upgrade checking is only done when git-annex is installed +from one of the prebuilt images from its website. This does not +bypass e.g., a Linux distribution's own upgrade handling code. +.IP +This setting also controls whether to restart the git-annex assistant +when the git-annex binary is detected to have changed. That is useful +no matter how you installed git-annex. +.IP +.IP "\fBannex.autocommit\fP" +Set to false to prevent the \fBgit-annex assistant\fP, \fBgit-annex assist\fP, +and \fBgit-annex sync\fP from automatically committing changes to files in +the repository. +.IP +To configure the behavior in all clones of the repository, +this can be set in git-annex\-config(1). +.IP +.IP "\fBannex.startupscan\fP" +Set to false to prevent the git-annex assistant from scanning the +repository for new and changed files on startup. This will prevent it +from noticing changes that were made while it was not running, but can be +a useful performance tweak for a large repository. +.IP +.IP "\fBannex.listen\fP" +Configures which IP address the webapp listens on. +The default is localhost. Can be either an IP address, +or a hostname that resolves to the desired address. +.IP +.IP "\fBannex.port\fP" +Configures which port address the webapp listens on. +The default is to pick an unused port. +.IP +.SH CONFIGURATION VIA .gitattributes +The key\-value backend used when adding a new file to the annex can be +configured on a per\-file\-type basis via \fB.gitattributes\fP files. In the file, +the \fBannex.backend\fP attribute can be set to the name of the backend to +use. (See git-annex\-backends(1) for information about +available backends.) +For example, this here's how to use the WORM backend by default, +but the SHA256E backend for ogg files: +.PP + * annex.backend=WORM + *.ogg annex.backend=SHA256E +.PP +There is a annex.largefiles attribute, which is used to configure which +files are large enough to be added to the annex. Since attributes cannot +contain spaces, it is difficult to use for more complex annex.largefiles +settings. Setting annex.largefiles in git-annex\-config(1) is an easier +way to configure it across all clones of the repository. +See git-annex\-matching\-expression(1) for details on the syntax. +.PP +The numcopies and mincopies settings can also be configured on a +per\-file\-type basis via the \fBannex.numcopies\fP and \fBannex.mincopies\fP +attributes in \fB.gitattributes\fP files. This overrides other settings. +For example, this makes two copies be needed for wav files and 3 copies +for flac files: +.PP + *.wav annex.numcopies=2 + *.flac annex.numcopies=3 +.PP +These settings are honored by git-annex whenever it's operating on a +matching file. However, when using \-\-all, \-\-unused, or \-\-key to specify +keys to operate on, git-annex is operating on keys and not files, so will +not honor the settings from .gitattributes. For this reason, the git annex +numcopies\fB and \fPgit annex mincopies commands are useful to configure a +global default. +.PP +Also note that when using views, only the toplevel .gitattributes file is +preserved in the view, so other settings in other files won't have any +effect. +.PP +.SH EXIT STATUS +git-annex itself will exit 0 on success and 1 on failure, unless +the \fB\-\-size\-limit\fP or \fB\-\-time\-limit\fP option is hit, in +which case it exits 101. +.PP +A few git-annex subcommands have other exit statuses used to indicate +specific problems, which are documented on their individual man pages. +.PP +.SH ENVIRONMENT +These environment variables are used by git-annex when set: +.PP +.IP "\fBGIT_WORK_TREE\fP, \fBGIT_DIR\fP" +Handled the same as they are by git, see git(1) +.IP +.IP "\fBGIT_SSH\fP, \fBGIT_SSH_COMMAND\fP" +Handled similarly to the same as described in git(1). +The one difference is that git-annex will sometimes pass an additional +"\-n" parameter to these, as the first parameter, to prevent ssh from +reading from stdin. Since that can break existing uses of these +environment variables that don't expect the extra parameter, you will +need to set \fBGIT_ANNEX_USE_GIT_SSH=1\fP to make git-annex support +these. +.IP +Note that setting either of these environment variables prevents +git-annex from automatically enabling ssh connection caching +(see \fBannex.sshcaching\fP), so it will slow down some operations with +remotes over ssh. It's up to you to enable ssh connection caching +if you need it; see ssh's documentation. +.IP +Also, \fBannex.ssh\-options\fP and \fBremote..annex\-ssh\-options\fP +won't have any effect when these envionment variables are set. +.IP +Usually it's better to configure any desired options through your +~/.ssh/config file, or by setting \fBannex.ssh\-options\fP. +.IP +.IP "\fBGIT_ANNEX_VECTOR_CLOCK\fP" +Normally git-annex timestamps lines in the log files committed to the +git-annex branch. Setting this environment variable to a number +will make git-annex use that (or a larger number) +rather than the current number of seconds since the UNIX epoch. +Note that decimal seconds are supported. +.IP +This is only provided for advanced users who either have a better way to +tell which commit is current than the local clock, or who need to avoid +embedding timestamps for policy reasons. +.IP +.IP "Some special remotes use additional environment variables" +for authentication etc. For example, \fBAWS_ACCESS_KEY_ID\fP +and \fBGIT_ANNEX_P2P_AUTHTOKEN\fP. See special remote documentation. +.IP +.SH FILES +These files are used by git-annex: +.PP +\fB.git/annex/objects/\fP in your git repository contains the annexed file +contents that are currently available. Annexed files in your git +repository symlink to that content. +.PP +\fB.git/annex/\fP in your git repository contains other run\-time information +used by git-annex. +.PP +\fB~/.config/git-annex/autostart\fP is a list of git repositories +to start the git-annex assistant in. +.PP +.SH SEE ALSO +More git-annex documentation is available on its web site, + +.PP +If git-annex is installed from a package, a copy of its documentation +should be included, in, for example, \fB/usr/share/doc/git-annex/\fP. +.PP +.IP "git-annex\-shell(1)" +.IP "git\-remote\-annex(1)" +.IP "git\-remote\-tor\-annex(1)" +.SH AUTHOR +Joey Hess +.PP + +.PP +.PP + diff --git a/man/git-remote-annex.1 b/man/git-remote-annex.1 new file mode 100644 index 0000000000..4e77017001 --- /dev/null +++ b/man/git-remote-annex.1 @@ -0,0 +1,105 @@ +.TH git-remote-annex 1 +.SH NAME +git\-remote\-annex \- remote helper program to store a git repository in a git-annex special remote +.PP +.SH SYNOPSIS +git fetch annex::uuid?param=value¶m=value... +.PP +.SH DESCRIPTION +This is a git remote helper program that allows git to clone, +pull and push from a git repository that is stored in a git-annex +special remote with an URL that starts with "annex::" +.PP +The special remote needs to have a \fBremote..url\fP +configured to use this. That is set up automatically when git +cloning from a special remote. +.PP +To make git-annex\-initremote(1) and git-annex\-enableremote(1) +configure the url, pass them the \fB\-\-with\-url\fP option. +.PP +Or, to configure an existing special remote with a shorthand URL, run: +.PP +git config remote.name.url annex:: +.PP +Once the URL is configured, you can use \fBgit pull\fP, \fBgit push\fP, etc +with the special remote much like with any other git remote. +But see CONFLICTING PUSHES below for some situations where it behaves +slightly differently. +.PP +.SH URL FORMAT +This uses an URL that starts with "annex::". There are three forms of such +URLs: +.PP +.IP "Complete URL" +This contains the UUID and all configuration parameters +of the special remote that were passed when using +\fBgit-annex initremote\fP. +.IP +For example, to clone from a directory special remote: +.IP +git clone annex::358ff77e\-0bc3\-11ef\-bc49\-872e6695c0e3?type=directory&encryption=none&directory=/mnt/foo/ +.IP +.IP "Shorthand URL" +This makes it easy to configure an existing special remote with an URL +without having to come up with the complete URL. +.IP +annex:: +.IP +When using this shorthand URL, the full URL will be displayed each time you +git pull or push, when it's possible for git-annex to determine it. +(Although in some cases, like the directory special remote, some +parameters may be left off of the displayed URL.) +.IP +.IP "Web URL" +This URL points at a file on the web, which contains the complete annex:: +URL. +.IP +annex::https://example.com/foo\-repo +.IP +Not all special remotes can be accessed by such an URL, +for security reasons. Currently, this is limited to httpalso special +remotes. +.IP +.SH CONFLICTING PUSHES +Like any git repository, a git repository stored on a special remote can +have conflicting things pushed to it from different places. This mostly +works the same as any other git repository, eg a push that overwrites other +work will be prevented unless forced. +.PP +However, it is possible, when conflicting pushes are being done at the same +time, for one of the pushes to be overwritten by the other one. In this +situation, the overwritten push will appear to have succeeded, but pulling +later will show the true situation. +.PP +.SH REPOSITORY FORMAT +The git repository is stored in the special remote using special annex objects +with names starting with "GITMANIFEST" and "GITBUNDLE". For details, see: + +.PP +Pushes to a special remote are usually done incrementally. However, +sometimes the whole git repository is re\-uploaded. That is done when force +pushing a ref, or deleting a ref from the remote. It's also done when too +many git bundles accumulate in the special remote, as configured by the +\fBremote..annex\-max\-git\-bundles\fP git config. +.PP +Note that a re\-upload of the repository does not delete old GITBUNDLE +objects from it. This means that refs pushed to the special +remote can still be accessed even after deleting or overwriting them. +.PP +A push that deletes every ref from the special remote will delete all +the accumulated GITBUNDLE objects. But of course, making such a push +means that someone who clones from the special remote at that point in time +will see an empty remote. +.PP +.SH SEE ALSO +gitremote\-helpers(1) +.PP +git-annex(1) +.PP +git-annex\-initremote(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP + diff --git a/man/git-remote-tor-annex.1 b/man/git-remote-tor-annex.1 new file mode 100644 index 0000000000..5185e598f5 --- /dev/null +++ b/man/git-remote-tor-annex.1 @@ -0,0 +1,33 @@ +.TH git-remote-tor-annex 1 +.SH NAME +git\-remote\-tor\-annex \- remote helper program to talk to git-annex over tor +.PP +.SH SYNOPSIS +git fetch tor\-annex::address.onion:port +.PP +git remote add tor tor\-annex::address.onion:port +.PP +.SH DESCRIPTION +This is a git remote helper program that allows git to pull and push +over tor(1), communicating with a tor hidden service. +.PP +The tor hidden service probably requires an authtoken to use it. +The authtoken can be provided in the environment variable +\fBGIT_ANNEX_P2P_AUTHTOKEN\fP. Or, if there is a file in +\fB.git/annex/creds/\fP matching the onion address of the hidden +service, its first line is used as the authtoken. +.PP +.SH SEE ALSO +gitremote\-helpers(1) +.PP +git-annex(1) +.PP +git-annex\-enable\-tor(1) +.PP +git-annex\-remotedaemon(1) +.PP +.SH AUTHOR +Joey Hess +.PP +.PP +