diff options
100 files changed, 3639 insertions, 954 deletions
diff --git a/.gitignore b/.gitignore index 0e90a5f80..bacfc4df3 100644 --- a/.gitignore +++ b/.gitignore @@ -13,8 +13,7 @@ Build/OSXMkLibs Build/LinuxMkLibs Build/BuildVersion git-annex -git-annex.1 -git-annex-shell.1 +man git-union-merge git-union-merge.1 doc/.ikiwiki diff --git a/Build/mdwn2man b/Build/mdwn2man index aadb13cdf..a29ce649e 100755 --- a/Build/mdwn2man +++ b/Build/mdwn2man @@ -2,6 +2,8 @@ # Warning: hack my $prog=shift; +$prog=~s/\.\d+$//; +$prog=~s/man\///; my $section=shift; print ".TH $prog $section\n"; diff --git a/Command/Assistant.hs b/Command/Assistant.hs index 0fad6b619..590a2e437 100644 --- a/Command/Assistant.hs +++ b/Command/Assistant.hs @@ -22,7 +22,7 @@ import System.Environment cmd :: [Command] cmd = [noRepo checkAutoStart $ dontCheck repoExists $ withOptions options $ notBareRepo $ command "assistant" paramNothing seek SectionCommon - "automatically handle changes"] + "automatically sync changes"] options :: [Option] options = diff --git a/Command/DiffDriver.hs b/Command/DiffDriver.hs index fa4f49366..f6ef77ecd 100644 --- a/Command/DiffDriver.hs +++ b/Command/DiffDriver.hs @@ -15,7 +15,7 @@ import Git.Types cmd :: [Command] cmd = [dontCheck repoExists $ - command "diffdriver" ("[-- cmd --opts]") seek + command "diffdriver" ("[-- cmd --]") seek SectionPlumbing "external git diff driver shim"] seek :: CommandSeek diff --git a/Command/Help.hs b/Command/Help.hs index 72913d7c4..2af39ac9a 100644 --- a/Command/Help.hs +++ b/Command/Help.hs @@ -23,7 +23,7 @@ import System.Console.GetOpt cmd :: [Command] cmd = [noCommit $ noRepo startNoRepo $ dontCheck repoExists $ - command "help" paramNothing seek SectionQuery "display help"] + command "help" (paramOptional "COMMAND") seek SectionCommon "display help"] seek :: CommandSeek seek = withWords start @@ -38,6 +38,7 @@ startNoRepo = start' start' :: [String] -> IO () start' ["options"] = showCommonOptions +start' [c] = showGitHelp c start' _ = showGeneralHelp showCommonOptions :: IO () @@ -58,8 +59,17 @@ showGeneralHelp = putStrLn $ unlines , Command.Fsck.cmd ] , "Run 'git-annex' for a complete command list." - , "Run 'git-annex command --help' for help on a specific command." + , "Run 'git-annex help command' for help on a specific command." , "Run `git annex help options' for a list of common options." ] where cmdline c = "\t" ++ cmdname c ++ "\t" ++ cmddesc c + +showGitHelp :: String -> IO () +showGitHelp c = + unlessM (githelp) $ + putStrLn $ "View online help at " ++ url + where + githelp = boolSystem "git" [Param "help", Param fullc] + fullc = "git-annex-" ++ c + url = "https://git-annex.branchable.com/" ++ fullc ++ "/" diff --git a/Command/MetaData.hs b/Command/MetaData.hs index f1de6b6de..08f205359 100644 --- a/Command/MetaData.hs +++ b/Command/MetaData.hs @@ -19,7 +19,7 @@ import Data.Time.Clock.POSIX cmd :: [Command] cmd = [withOptions metaDataOptions $ command "metadata" paramPaths seek - SectionMetaData "sets metadata of a file"] + SectionMetaData "sets or gets metadata of a file"] metaDataOptions :: [Option] metaDataOptions = diff --git a/Command/Reinit.hs b/Command/Reinit.hs index b1264effa..f201c66bb 100644 --- a/Command/Reinit.hs +++ b/Command/Reinit.hs @@ -16,7 +16,7 @@ import qualified Remote cmd :: [Command] cmd = [dontCheck repoExists $ - command "reinit" (paramUUID ++ " or " ++ paramDesc) seek SectionUtility ""] + command "reinit" (paramUUID ++ "|" ++ paramDesc) seek SectionUtility "initialize repository, reusing old UUID"] seek :: CommandSeek seek = withWords start diff --git a/Command/VCycle.hs b/Command/VCycle.hs index f9a21892b..bf253adc1 100644 --- a/Command/VCycle.hs +++ b/Command/VCycle.hs @@ -16,7 +16,7 @@ import Command.View (checkoutViewBranch) cmd :: [Command] cmd = [notBareRepo $ notDirect $ - command "vcycle" paramNothing seek SectionUtility + command "vcycle" paramNothing seek SectionMetaData "switch view to next layout"] seek :: CommandSeek diff --git a/Command/Watch.hs b/Command/Watch.hs index 2f82a7b7f..cf86a5832 100644 --- a/Command/Watch.hs +++ b/Command/Watch.hs @@ -14,7 +14,7 @@ import Utility.HumanTime cmd :: [Command] cmd = [notBareRepo $ withOptions [foregroundOption, stopOption] $ - command "watch" paramNothing seek SectionCommon "watch for changes"] + command "watch" paramNothing seek SectionCommon "watch for changes and autocommit"] seek :: CommandSeek seek ps = do @@ -1,4 +1,4 @@ -mans=git-annex.1 git-annex-shell.1 +mans=$(shell find doc -maxdepth 1 -name git-annex*.mdwn | sed -e 's/^doc/man/' -e 's/\.mdwn/\.1/') all=git-annex $(mans) docs CABAL?=cabal # set to "./Setup" if you lack a cabal program @@ -24,10 +24,8 @@ git-annex: Build/SysConfig.hs $(CABAL) build ln -sf dist/build/git-annex/git-annex git-annex -git-annex.1: doc/git-annex.mdwn - ./Build/mdwn2man git-annex 1 doc/git-annex.mdwn > git-annex.1 -git-annex-shell.1: doc/git-annex-shell.mdwn - ./Build/mdwn2man git-annex-shell 1 doc/git-annex-shell.mdwn > git-annex-shell.1 +man/%.1: doc/%.mdwn + ./Build/mdwn2man $@ 1 $< > $@ # These are not built normally. git-union-merge.1: doc/git-union-merge.mdwn @@ -69,7 +67,12 @@ else IKIWIKI=ikiwiki endif -docs: $(mans) +mans: man $(mans) + +man: + mkdir -p man + +docs: mans $(IKIWIKI) doc html -v --wikiname git-annex --plugin=goodstuff \ --no-usedirs --disable-plugin=openid --plugin=sidebar \ --underlaydir=/dev/null --disable-plugin=shortcut \ diff --git a/debian/changelog b/debian/changelog index fe164a81a..18d7b22b6 100644 --- a/debian/changelog +++ b/debian/changelog @@ -7,6 +7,8 @@ git-annex (5.20150318) UNRELEASED; urgency=medium is updated. Needed for git update-server-info. * migrate: --force will force migration of keys already using the destination backend. Useful in rare cases. + * Man pages for individual commands now available, and can be + opened using "git annex help <command>" -- Joey Hess <id@joeyh.name> Thu, 19 Mar 2015 17:05:32 -0400 diff --git a/doc/devblog/day_266-267__man_page_split.mdwn b/doc/devblog/day_266-267__man_page_split.mdwn new file mode 100644 index 000000000..6239e7dfd --- /dev/null +++ b/doc/devblog/day_266-267__man_page_split.mdwn @@ -0,0 +1,16 @@ +While traveling for several days, I filled dead time with a rather massive +reorganization of the git-annex man page, and I finished that up this +morning. + +That man page had gotten rather massive, at around 3 thousand lines. I +split out 87 man pages, one for each git-annex command. Many of these were +expanded with additional details, and have become a lot better thanks +to the added focus and space. See for example, [[git-annex-find]], +or any of the links on the new [[git-annex]] man page. (Which is still over +1 thousand lines long..) + +Also, `git annex help <command>` can be used to pull up a command's man +page now! + +I'm taking the rest of the day off to R&R from the big trip north, and +expect to get back into the backlog of 143 messages starting tomorrow. diff --git a/doc/git-annex-add.mdwn b/doc/git-annex-add.mdwn new file mode 100644 index 000000000..4ae0d1ce1 --- /dev/null +++ b/doc/git-annex-add.mdwn @@ -0,0 +1,47 @@ +# NAME + +git-annex add - adds files to the git annex + +# SYNOPSIS + +git annex add `[path ...]` + +# DESCRIPTION + +Adds files in the path to the annex. If no path is specified, adds +files from the current directory and below. + +Normally, files that are already checked into git, or that git has been +configured to ignore will be silently skipped. + +# OPTIONS + +* `--include-dotfiles` + + Dotfiles are skipped unless explicitly listed, or unless this option is + used. + +* `--force` + + Add gitignored files. + +* `--backend` + + Specifies which key-value backend to use. + +* file matching options + + Many of the [[git-annex-matching-options]](1) + can be used to specify files to add. + + For example: `--largerthan=1GB` + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-addunused.mdwn b/doc/git-annex-addunused.mdwn new file mode 100644 index 000000000..2eb308e0e --- /dev/null +++ b/doc/git-annex-addunused.mdwn @@ -0,0 +1,24 @@ +# NAME + +git-annex addunused - add back unused files + +# SYNOPSIS + +git annex addunused `[number|range ...]` + +# DESCRIPTION + +Adds back files for the content corresponding to the numbers or ranges, +as listed by the last `git annex unused`. + +The files will have names starting with "unused." + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-addurl.mdwn b/doc/git-annex-addurl.mdwn new file mode 100644 index 000000000..5e26035ec --- /dev/null +++ b/doc/git-annex-addurl.mdwn @@ -0,0 +1,66 @@ +# NAME + +git-annex addurl - add urls to annex + +# SYNOPSIS + +git annex addurl `[url ...]` + +# DESCRIPTION + +Downloads each url to its own file, which is added to the annex. + +When `quvi` is installed, urls are automatically tested to see if they +point to a video hosting site, and the video is downloaded instead. + +Urls to torrent files (including magnet links) will cause the content of +the torrent to be downloaded, using `aria2c`. + +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. + +# OPTIONS + +* `--fast` + + Avoid immediately downloading the url. + +* `--relaxed` + + Avoid storing the size of the url's content, and accept whatever + content is there at a future point. (Implies `--fast`.) + +* `--raw` + + Prevent special handling of urls by quvi, bittorrent, and other + special remotes. This will for example, make addurl + download the .torrent file and not the contents it points to. + +* `--file=name` + + 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. + + If the file already exists, addurl will record that it can be downloaded + from the specified url(s). + +* `--pathdepth=N` + + This causes a shorter filename to be used. For example, + `--pathdepth=1` will use "dir/subdir/bigfile", + while `--pathdepth=3` will use "bigfile". + + It can also be negative; `--pathdepth=-2` will use the last + two parts of the url. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-assistant.mdwn b/doc/git-annex-assistant.mdwn new file mode 100644 index 000000000..c6a35f03d --- /dev/null +++ b/doc/git-annex-assistant.mdwn @@ -0,0 +1,47 @@ +# NAME + +git-annex assistant - automatically sync changes + +# SYNOPSIS + +git annex assistant + +# DESCRIPTION + +Watches for changes to files in the current directory and its subdirectories, +and automatically syncs them to other remotes. + +For more details about the git-annex assistant, see +<https://git-annex.branchable.com/assistant/> + +# OPTIONS + +* `--autostart` + + Automatically starts the assistant running in each repository listed + in the file `~/.config/git-annex/autostart` + + This is typically started at boot, or when you log in. + +* `--startdelay=N` + + Wait N seconds before running the startup scan. This process can + be expensive and you may not want to run it immediatly upon login. + +* `--foreground` + + Avoid forking to the background. + +* `--stop` + + Stop a running daemon. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-checkpresentkey.mdwn b/doc/git-annex-checkpresentkey.mdwn new file mode 100644 index 000000000..75e5caf3e --- /dev/null +++ b/doc/git-annex-checkpresentkey.mdwn @@ -0,0 +1,26 @@ +# NAME + +git-annex checkpresentkey - check if key is present in remote + +# SYNOPSIS + +git annex `key remote` + +# DESCRIPTION + +This plumbing-level command verifies if the specified key's content +is present in the specified remote. + +Exits 0 if the content is verified present, or 1 if it is verified to not +be present. If there is a problem checking the remote, the special +exit code 100 is used, and an error message is output to stderr. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-copy.mdwn b/doc/git-annex-copy.mdwn new file mode 100644 index 000000000..7de0fbc25 --- /dev/null +++ b/doc/git-annex-copy.mdwn @@ -0,0 +1,62 @@ +# NAME + +git-annex copy - copy content of files to/from another repository + +# SYNOPSIS + +git annex copy `[path ...] [--from=remote|--to=remote]` + +# DESCRIPTION + +Copies the content of files from or to another remote. + +# OPTIONS + +* `--from=remote` + + Use this option to copy the content of files from the specified + remote to the local repository. + +* `--to=remote` + + Use this option to copy the content of files from the local repository + to the specified remote. + +* `--fast` + + Avoid contacting the remote to check if it has every file when copying + --to it. + +* `--force` + + Force checking the remote for every file when copying --from it. + +* `--all` + + Rather than specifying a filename or path to copy, this option can be + used to copy all available versions of all files. + + This is the default behavior when running git-annex in a bare repository. + +* `--unused` + + Operate on files found by last run of git-annex unused. + +* `--key=keyname` + + Use this option to move a specified key. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to copy. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-dead.mdwn b/doc/git-annex-dead.mdwn new file mode 100644 index 000000000..597d23fe5 --- /dev/null +++ b/doc/git-annex-dead.mdwn @@ -0,0 +1,25 @@ +# NAME + +git-annex trust - hide a lost repository + +# SYNOPSIS + +git annex dead `[repository ...]` + +# DESCRIPTION + +Indicates that the repository has been irretrievably lost. +(To undo, use semitrust.) + +Repositories can be specified using their remote name, their +description, or their UUID. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-describe.mdwn b/doc/git-annex-describe.mdwn new file mode 100644 index 000000000..5890801a2 --- /dev/null +++ b/doc/git-annex-describe.mdwn @@ -0,0 +1,29 @@ +# NAME + +git-annex describe - change description of a repository + +# SYNOPSIS + +git annex describe repository description + +# DESCRIPTION + +Changes the description of a repository. + +The repository to describe can be specified by git remote name or +by uuid. To change the description of the current repository, use +"here". + +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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-diffdriver.mdwn b/doc/git-annex-diffdriver.mdwn new file mode 100644 index 000000000..72e0faca3 --- /dev/null +++ b/doc/git-annex-diffdriver.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex diffdriver - external git diff driver shim + +# SYNOPSIS + +git annex diffdriver `-- cmd --opts --` + +# DESCRIPTION + +This is an external git diff driver shim. Normally, when using `git diff` +with an external git driver, the symlinks to annexed files are not set up +right, so the external git driver cannot read them in order to perform +smart diffing of their contents. This command works around the problem, +by passing the fixed up files to the real external diff driver. + +To use, just configure git to use "git-annex diffdriver -- cmd params --" +as the external diff command, where cmd is the real external diff +command you want to use, and params are any extra parameters to pass +to it. Note the trailing "--", which is required. + +For example, set `GIT_EXTERNAL_DIFF=git-annex diffdriver -- j-c-diff --` + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-direct.mdwn b/doc/git-annex-direct.mdwn new file mode 100644 index 000000000..9a9d66d9e --- /dev/null +++ b/doc/git-annex-direct.mdwn @@ -0,0 +1,28 @@ +# NAME + +git-annex direct - switch repository to direct mode + +# SYNOPSIS + +git annex direct + +# DESCRIPTION + +Switches a repository to use direct mode, where rather than symlinks to +files, the files are directly present in the repository. + +As part of the switch to direct mode, any changed files will be committed. + +Note that git commands that operate on the work tree will refuse to +run in direct mode repositories. Use `git annex proxy` to safely run such +commands. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-drop.mdwn b/doc/git-annex-drop.mdwn new file mode 100644 index 000000000..41daf3858 --- /dev/null +++ b/doc/git-annex-drop.mdwn @@ -0,0 +1,45 @@ +# NAME + +git-annex drop - indicate content of files not currently wanted + +# SYNOPSIS + +git annex drop `[path ...]` + +# DESCRIPTION + +Drops the content of annexed files from this repository, when +possible. + +git-annex will refuse to drop content if it cannot verify it is +safe to do so. + +# OPTIONS + +* `--from=remote` + + Rather than dropping the content of files in the local repository, + this option can specifiy a remote from which the files' + contents should be removed. + +* `--force` + + 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. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to drop. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-dropkey.mdwn b/doc/git-annex-dropkey.mdwn new file mode 100644 index 000000000..7a25e23b2 --- /dev/null +++ b/doc/git-annex-dropkey.mdwn @@ -0,0 +1,28 @@ +# NAME + +git-annex dropkey - drops annexed content for specified keys + +# SYNOPSIS + +git annex dropkey `[key ...]` + +# DESCRIPTION + +This plumbing-level command drops the annexed data for the specified +keys from this repository. + +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. + +Warning: This command does not check that enough other copies of the content +exist; using it can easily result in data loss. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-dropunused.mdwn b/doc/git-annex-dropunused.mdwn new file mode 100644 index 000000000..5dedce718 --- /dev/null +++ b/doc/git-annex-dropunused.mdwn @@ -0,0 +1,39 @@ +# NAME + +git-annex dropunused - drop unused file content + +# SYNOPSIS + +git annex dropunused `[number|range ...]` + +# DESCRIPTION + +Drops the data corresponding to the numbers, as listed by the last +git annex unused` + +You can also specify ranges of numbers, such as "1-1000". +Or, specify "all" to drop all unused data. + +# OPTIONS + +* `--from=remote` + + Rather than dropping the unused files from the local repository, + drop them from the remote repository. + +* `--force` + + 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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-edit.mdwn b/doc/git-annex-edit.mdwn new file mode 100644 index 000000000..ef8502cfa --- /dev/null +++ b/doc/git-annex-edit.mdwn @@ -0,0 +1,18 @@ +# NAME + +git-annex unlock - unlock files for modification + +# SYNOPSIS + +git annex edit `[path ...]` + +# DESCRIPTION + +This is an alias for the `unlock` command; see [[git-annex-unlock]](1) +for details. + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-enableremote.mdwn b/doc/git-annex-enableremote.mdwn new file mode 100644 index 000000000..cb4002a08 --- /dev/null +++ b/doc/git-annex-enableremote.mdwn @@ -0,0 +1,56 @@ +# NAME + +git-annex enableremote - enables use of an existing special remote + +# SYNOPSIS + +git annex enableremote `name [param=value ...]` + +# DESCRIPTION + +Enables use of an existing special remote in the current repository, +which may be a different repository than the one in which it was +originally created with the initremote command. + +The name of the remote is the same name used when originally +creating that remote with `git annex initremote`. Run +`git annex enableremote` without any name to get a list of +special remote names. + +Some special remotes may need parameters to be specified every time they are +enabled. For example, the directory special remote requires a directory= +parameter. + +This command can also be used to modify the configuration of an existing +special remote, by specifying new values for parameters that were +originally set when using initremote. (However, some settings such as +the as the encryption scheme cannot be changed once a special remote +has been created.) + +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). + +One use-case of keyid-= is to replace a revoked key with +a new key: + + git annex enableremote mys3 keyid-=revokedkey keyid+=newkey + +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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-examinekey.mdwn b/doc/git-annex-examinekey.mdwn new file mode 100644 index 000000000..3a8159f66 --- /dev/null +++ b/doc/git-annex-examinekey.mdwn @@ -0,0 +1,51 @@ +# NAME + +git-annex examinekey - prints information from a key + +# SYNOPSIS + +git annex examinekey `[key ...]` + +# DESCRIPTION + +This plumbing-level command is given a key, and prints information +that can be determined purely by looking at the key. + +# OPTIONS + +* `--format=value` + + Use custom output formatting. + + 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 in a variable, use '${escaped_var}' + + These variables are available for use in formats: key, backend, + bytesize, humansize, keyname, hashdirlower, hashdirmixed, mtime (for + the mtime field of a WORM key). + + Also, '\\n' is a newline, '\\000' is a NULL, etc. + +* `--json` + + Enable JSON output. This is intended to be parsed by programs that use + git-annex. Each line of output is a JSON object. + +# EXAMPLES + +The location a key's value is stored (in indirect mode) +can be looked up by running: + + git annex examinekey $KEY --format='.git/annex/objects/${hashdirmixed}${key}/${key}' + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-find.mdwn b/doc/git-annex-find.mdwn new file mode 100644 index 000000000..ce9c6326f --- /dev/null +++ b/doc/git-annex-find.mdwn @@ -0,0 +1,65 @@ +# NAME + +git-annex find - lists available files + +# SYNOPSIS + +git annex find `[path ...]` + +# DESCRIPTION + +Outputs a list of annexed files in the specified path. With no path, +finds files in the current directory and its subdirectories. + +# OPTIONS + +* `--print0` + + Output filenames terminated with nulls, for use with `xargs -0` + +* `--format=value` + + Use custom output formatting. + + 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 in a variable, use '${escaped_var}' + + 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). + + Also, '\\n' is a newline, '\\000' is a NULL, etc. + + The default output format is the same as `--format='${file}\\n'` + +* `--json` + + Output the list of files in JSON format. + + This is intended to be parsed by programs that use + git-annex. Each line of output is a JSON object. + +* matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to list. + + 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. + + To list all annexed files, present or not, specify `--include "*"`. + + To list annexed files whose content is not present, specify `--not --in=here` + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-findref.mdwn b/doc/git-annex-findref.mdwn new file mode 100644 index 000000000..ce07e0ee4 --- /dev/null +++ b/doc/git-annex-findref.mdwn @@ -0,0 +1,27 @@ +# NAME + +git-annex findref - lists files in a git ref + +# SYNOPSIS + +git annex findref `[ref]` + +# DESCRIPTION + +This is very similar to the `git-annex find` command, but instead of +finding files in the current work tree, it finds files in the +specified git ref. + +# OPTIONS + +Same as [[git-annex-find]](1) + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fix.mdwn b/doc/git-annex-fix.mdwn new file mode 100644 index 000000000..8a7232ea3 --- /dev/null +++ b/doc/git-annex-fix.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex fix - fix up symlinks to point to annexed content + +# SYNOPSIS + +git annex fix `[path ...]` + +# DESCRIPTION + +Fixes up symlinks that have become broken to again point to annexed +content. + +This is useful to run if you have been moving the symlinks around, +but is done automatically when committing a change with git too. + +# OPTIONS + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to fix. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-forget.mdwn b/doc/git-annex-forget.mdwn new file mode 100644 index 000000000..b5d428cfb --- /dev/null +++ b/doc/git-annex-forget.mdwn @@ -0,0 +1,37 @@ +# NAME + +git-annex forget - prune git-annex branch history + +# SYNOPSIS + +git annex forget + +# 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 `git annex log` will not be able to show where +files used to be located. + +When this rewritten branch is merged into other clones of +the repository, `git-annex` will automatically perform the same rewriting +to their local `git-annex` 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.) + +# OPTIONS + +* `--drop-dead` + + Also prune references to repositories that have been marked as dead. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fromkey.mdwn b/doc/git-annex-fromkey.mdwn new file mode 100644 index 000000000..b4adc9cea --- /dev/null +++ b/doc/git-annex-fromkey.mdwn @@ -0,0 +1,33 @@ +# NAME + +git-annex fromkey - adds a file using a specific key + +# SYNOPSIS + +git annex fromkey `[key file]` + +# DESCRIPTION + +This plumbing-level command can be used to manually set up a file +in the git repository to link to a specified key. + +If the key and file are not specified on the command line, they are +instead read from stdin. Any number of lines can be provided in this +mode, each containing a key and filename, sepearated by whitespace. + +# OPTIONS + +* `--force` + + 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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fsck.mdwn b/doc/git-annex-fsck.mdwn new file mode 100644 index 000000000..cb27fe452 --- /dev/null +++ b/doc/git-annex-fsck.mdwn @@ -0,0 +1,93 @@ +# NAME + +git-annex fsck - check for problems + +# SYNOPSIS + +git annex fsck `[path ...]` + +# DESCRIPTION + +With no parameters, this command checks the whole annex for consistency, +and warns about or fixes any problems found. This is a good complement to +`git fsck`. + +With parameters, only the specified files are checked. + +# OPTIONS + +* `--from=remote` + + Check a remote, rather than the local repository. + + 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 `--fast` option. + +* `--fast` + + Avoids expensive checksum calculations (and expensive transfers when + fscking a remote). + +* `--incremental` + + Start a new incremental fsck pass. An incremental fsck can be interrupted + at any time, with eg ctrl-c. + +* `--more` + + Continue the last incremental fsck pass, where it left off. + +* `--incremental-schedule=time` + + This makes a new incremental fsck be started only a specified + time period after the last incremental fsck was started. + + The time is in the form "10d" or "300h". + + 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: + + git annex fsck --incremental-schedule 30d --time-limit 5h + +* `--numcopies=N` + + Override the normally configured number of copies. + + To verify data integrity only while disregarding required number of copies, + use `--numcopies=1`. + +* `--all` + + Normally only the files in the currently checked out branch + are fscked. This option causes all versions of all files to be fscked. + + This is the default behavior when running git-annex in a bare repository. + +* `--unused` + + Operate on files found by last run of git-annex unused. + +* `--key=keyname` + + Use this option to fsck a specified key. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to fsck. + +# OPTIONS + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-fuzztest.mdwn b/doc/git-annex-fuzztest.mdwn new file mode 100644 index 000000000..7045be0ee --- /dev/null +++ b/doc/git-annex-fuzztest.mdwn @@ -0,0 +1,23 @@ +# NAME + +git-annex fuzztest - generates fuzz test files + +# SYNOPSIS + +git annex fuzztest + +# 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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-get.mdwn b/doc/git-annex-get.mdwn new file mode 100644 index 000000000..cb5b73956 --- /dev/null +++ b/doc/git-annex-get.mdwn @@ -0,0 +1,52 @@ +# NAME + +git-annex get - make content of annexed files available + +# SYNOPSIS + +git annex get `[path ...]` + +# 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. + +# OPTIONS + +* `--from=remote` + + Normally git-annex will choose which remotes to get the content + from. Use this option to specify which remote to use. + +* `--all` + + Rather than specifying a filename or path to get, this option can be + used to get all available versions of all files. + + This is the default behavior when running git-annex in a bare repository. + +* `--unused` + + Operate on files found by last run of git-annex unused. + +* `--key=keyname` + + Use this option to get a specified key. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to get. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-drop]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-group.mdwn b/doc/git-annex-group.mdwn new file mode 100644 index 000000000..e219cd207 --- /dev/null +++ b/doc/git-annex-group.mdwn @@ -0,0 +1,29 @@ +# NAME + +git-annex group - add a repository to a group + +# SYNOPSIS + +git annex group `repository groupname` + +# DESCRIPTION + +Adds a repository to a group, such as "archival", "enduser", or "transfer". +The groupname must be a single word. + +Omit the groupname to show the current groups that a repository is in. + +There are some standard groups that have different default preferred content +settings. See <https://git-annex.branchable.com/preferred_content/standard_groups/> + +A repository can be in multiple groups at the same time. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-groupwanted.mdwn b/doc/git-annex-groupwanted.mdwn new file mode 100644 index 000000000..ef20ccd3e --- /dev/null +++ b/doc/git-annex-groupwanted.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex groupwanted - get or set groupwanted expression + +# SYNOPSIS + +git annex groupwanted `groupname [expression]` + +# 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". + +For example, to configure a group named redundantarchive, and +make repositories in the group want to contain 3 copies of every file: + + 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 + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-import.mdwn b/doc/git-annex-import.mdwn new file mode 100644 index 000000000..4d2c05547 --- /dev/null +++ b/doc/git-annex-import.mdwn @@ -0,0 +1,69 @@ +# NAME + +git-annex import - move and add files from outside git working copy + +# SYNOPSIS + +git annex import `[path ...]` + +# DESCRIPTION + +Moves files from somewhere outside the git working copy, and adds them to +the annex. Individual files to import can be specified. +If a directory is specified, the entire directory is imported. + + git annex import /media/camera/DCIM/* + +By default, importing two files with the same contents from two different +locations will result in both files being added to the repository. +(With all checksumming backends, including the default SHA256E, +only one copy of the data will be stored.) + +# OPTIONS + +* `--duplicate` + + Do not delete files from the import location. + + This could allow importing the same files repeatedly + to different locations in a repository. More likely, it could be used to + import the same files to a number of different branches or separate git + repositories. + +* `--deduplicate` + + Only import files whose content has not been seen before by git-annex. + + Duplicate files will be deleted from the import location. + +* `--skip-duplicates` + + Only import files whose content has not been seen before by git-annex, + but avoid deleting duplicate files. + +* `--clean-duplicates` + + Does not import any files, but any files found in the import location + that are duplicates of content in the annex are deleted. + +* file matching options + + Many of the [[git-annex-matching-options]](1) + can be used to specify files to import. + + git annex import /dir --include='*.png' + +# CAVEATS + +Note that using `--deduplicate` or `--clean-duplicates` with the WORM +backend does not look at file content, but filename and mtime. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-importfeed.mdwn b/doc/git-annex-importfeed.mdwn new file mode 100644 index 000000000..69c841667 --- /dev/null +++ b/doc/git-annex-importfeed.mdwn @@ -0,0 +1,46 @@ +# NAME + +git-annex importfeed - import files from podcast feeds + +# SYNOPSIS + +git annex importfeed `[url ...]` + +# DESCRIPTION + +Imports the contents of podcast feeds. Only downloads files whose +urls have not already been added to the repository before, so you can +delete, rename, etc the resulting files and repeated runs won't duplicate +them. + +When quvi is installed, links in the feed are tested to see if they +are on a video hosting site, and the video is downloaded. This allows +importing e.g., youtube playlists. + +# OPTIONS + +* `--force` + + Force downoading urls it's seen before. + +* `--template` + + Controls where the files are stored. + + The default template is '${feedtitle}/${itemtitle}${extension}' + + Other available variables for templates: feedauthor, itemauthor, itemsummary, itemdescription, itemrights, itemid, itempubdate, title, author + +* `--relaxed`, `--fast`, `--raw`, `--template` + + These options behave the same as when using [[git-annex-addurl]](1). + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-indirect.mdwn b/doc/git-annex-indirect.mdwn new file mode 100644 index 000000000..42dc0a045 --- /dev/null +++ b/doc/git-annex-indirect.mdwn @@ -0,0 +1,26 @@ +# NAME + +git-annex indirect - switch repository to indirect mode + +# SYNOPSIS + +git annex indirect + +# DESCRIPTION + +Switches a repository back from direct mode to the default, indirect +mode. + +Some systems cannot support git-annex in indirect mode, because they +do not support symbolic links. Repositories on such systems instead +default to using direct mode. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-info.mdwn b/doc/git-annex-info.mdwn new file mode 100644 index 000000000..52b145c51 --- /dev/null +++ b/doc/git-annex-info.mdwn @@ -0,0 +1,51 @@ +# NAME + +git-annex info - shows information about the specified item or the repository as a whole + +# SYNOPSIS + +git annex info `[directory|file|remote|uuid ...]` + +# DESCRIPTION + +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. + +When no item is specified, displays statistics and information +for the repository as a whole. + +# OPTIONS + +* `--fast` + + Only show the data that can be gathered quickly. + +* `--json` + + Enable JSON output. This is intended to be parsed by programs that use + git-annex. Each line of output is a JSON object. + +* file matching options + + When a directory is specified, the [[git-annex-matching-options]](1) + can be used to select the files in the directory that are included + in the statistics. + +# EXAMPLES + +Suppose you want to run "git annex get .", but +would first like to see how much disk space that will use. +Then run: + + git annex info --fast . --not --in here + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-init.mdwn b/doc/git-annex-init.mdwn new file mode 100644 index 000000000..1398923bf --- /dev/null +++ b/doc/git-annex-init.mdwn @@ -0,0 +1,27 @@ +# NAME + +git-annex init - initialize git-annex + +# SYNOPSIS + +git annex init `[description]` + +# 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. + +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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-initremote.mdwn b/doc/git-annex-initremote.mdwn new file mode 100644 index 000000000..28ea97378 --- /dev/null +++ b/doc/git-annex-initremote.mdwn @@ -0,0 +1,57 @@ +# NAME + +git-annex initremote - creates a special (non-git) remote + +# SYNOPSIS + +git annex initremote `name type=value [param=value ...]` + +# DESCRIPTION + +Creates a new special remote, and adds it to `.git/config`. + +Example Amazon S3 remote: + + git annex initremote mys3 type=S3 encryption=hybrid keyid=me@example.com datacenter=EU + +Many different types of special remotes are supported by git-annex. +For a list and details, see <https://git-annex.branchable.com/special_remotes/> + +The remote's configuration is specified by the parameters passed +to this command. Different types of special remotes need different +configuration values. The command will prompt for parameters as needed. + +All special remotes support encryption. You can either specify +`encryption=none` to disable encryption, or specify +`encryption=hybrid keyid=$keyid ...` to specify a GPG key id (or an email +address associated with a key). + +There are actually three schemes that can be used for management of the +encryption keys. When using the encryption=hybrid scheme, additional +GPG keys can be given access to the encrypted special remote easily +(without re-encrypting everything). When using encryption=shared, +a shared key is generated and stored in the git repository, allowing +anyone who can clone the git repository to access it. Finally, when using +encryption=pubkey, content in the special remote is directly encrypted +to the specified GPG keys, and additional ones cannot easily be given +access. + +# OPTIONS + +* `--fast` + + 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 `--fast`, which causes it to use a lower-quality source of + randomness. (Ie, /dev/urandom instead of /dev/random) + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-list.mdwn b/doc/git-annex-list.mdwn new file mode 100644 index 000000000..2997ca762 --- /dev/null +++ b/doc/git-annex-list.mdwn @@ -0,0 +1,34 @@ +# NAME + +git-annex list - show which remotes contain files + +# SYNOPSIS + +git annex list `[path ...]` + +# DESCRIPTION + +Displays a table of remotes that contain the contents of the specified +files. This is similar to `git annex whereis` but a more compact display. + +# OPTIONS + +* `--allrepos` + + Only configured remotes are shown by default; this option + adds all known repositories to the list. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to list. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-lock.mdwn b/doc/git-annex-lock.mdwn new file mode 100644 index 000000000..aa03d4ce7 --- /dev/null +++ b/doc/git-annex-lock.mdwn @@ -0,0 +1,29 @@ +# NAME + +git-annex lock - unco unlock command + +# SYNOPSIS + +git annex lock `[path ...]` + +# DESCRIPTION + +Use this to undo an unlock command if you don't want to modify +the files, or have made modifications you want to discard. + +# OPTIONS + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to lock. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-log.mdwn b/doc/git-annex-log.mdwn new file mode 100644 index 000000000..77558890e --- /dev/null +++ b/doc/git-annex-log.mdwn @@ -0,0 +1,42 @@ +# NAME + +git-annex log - shows location log + +# SYNOPSIS + +git annex log `[path ...]` + +# DESCRIPTION + +Displays the location log for the specified file or files, +showing each repository they were added to ("+") and removed from ("-"). + +# OPTIONS + +* `--since=date`, `--after=date`, `--until=date`, `--before=date`, `--max-count=N` + + These options are passed through to `git log`, and can be used to limit + how far back to search for location log changes. + + For example: `--since "1 month ago"` + +* `--gource` + + Generates output suitable for the `gource` visualization program. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to act on. + +# OPTIONS + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-lookupkey.mdwn b/doc/git-annex-lookupkey.mdwn new file mode 100644 index 000000000..568bbdc05 --- /dev/null +++ b/doc/git-annex-lookupkey.mdwn @@ -0,0 +1,24 @@ +# NAME + +git-annex lookupkey - looks up key used for file + +# SYNOPSIS + +git annex lookupkey `[file ...]` + +# 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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-map.mdwn b/doc/git-annex-map.mdwn new file mode 100644 index 000000000..6e5ced2b4 --- /dev/null +++ b/doc/git-annex-map.mdwn @@ -0,0 +1,40 @@ +# NAME + +git-annex map - generate map of repositories + +# SYNOPSIS + +git annex map + +# 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 `dot` command is available, it is +used to display the file to your screen (using x11 backend). + +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 + +Also, if connecting to a host requires a password, you might have to enter +it several times as the map is being built. + +Note that this subcommand can be used to graph any git repository; it +is not limited to git-annex repositories. + +# OPTIONS + +* `--fast` + + Disable using `dot` to display the generated Graphviz file. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-matching-options.mdwn b/doc/git-annex-matching-options.mdwn new file mode 100644 index 000000000..34cc05c6a --- /dev/null +++ b/doc/git-annex-matching-options.mdwn @@ -0,0 +1,164 @@ +# NAME + +git-annex-matching-options - specifying files to act on + +# DESCRIPTION + +Many git-annex commands support using these options to specify which +files they act on. + +Arbitrarily complicated expressions can be built using these options. +For example: + + --exclude '*.mp3' --and --not -( --in=usbdrive --or --in=archive -) + +The above example prevents git-annex from working on mp3 files whose +file contents are present at either of two repositories. + +# OPTIONS + +* `--exclude=glob` + + Skips files matching the glob pattern. The glob is matched relative to + the current directory. For example: + + --exclude='*.mp3' --exclude='subdir/*' + + Note that this will not match anything when using --all or --unused. + +* `--include=glob` + + Skips files not matching the glob pattern. (Same as `--not --exclude`.) + For example, to include only mp3 and ogg files: + + --include='*.mp3' --or --include='*.ogg' + + Note that this will not skip anything when using --all or --unused. + +* `--in=repository` + + Matches only files that git-annex believes have their contents present + in a repository. Note that it does not check the repository to verify + that it still has the content. + + 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 `--in=here` + +* `--in=repository@{date}` + + Matches files currently in the work tree whose content was present in + the repository on the given date. + + The date is specified in the same syntax documented in + gitrevisions(7). Note that this uses the reflog, so dates far in the + past cannot be queried. + + For example, you might need to run `git annex drop .` to temporarily + free up disk space. The next day, you can get back the files you dropped + using `git annex get . --in=here@{yesterday}` + +* `--copies=number` + + 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. + +* `--copies=trustlevel:number` + + Matches only files that git-annex believes have the specified number of + copies, on remotes with the specified trust level. For example, + `--copies=trusted:2` + + To match any trust level at or higher than a given level, + use 'trustlevel+'. For example, `--copies=semitrusted+:2` + +* `--copies=groupname:number` + + Matches only files that git-annex believes have the specified number of + copies, on remotes in the specified group. For example, + `--copies=archive:2` + +* `--lackingcopies=number` + + 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. + +* `--approxlackingcopies=number` + + Like lackingcopies, but does not look at .gitattributes annex.numcopies + settings. This makes it significantly faster. + +* `--inbackend=name` + + Matches only files whose content is stored using the specified key-value + backend. + +* `--inallgroup=groupname` + + Matches only files that git-annex believes are present in all repositories + in the specified group. + +* `--smallerthan=size` +* `--largerthan=size` + + Matches only files whose content is smaller than, or larger than the + specified size. + + The size can be specified with any commonly used units, for example, + "0.5 gb" or "100 KiloBytes" + +* `--metadata field=glob` + + Matches only files that have a metadata field attached with a value that + matches the glob. The values of metadata fields are matched case + insensitively. + +* `--want-get` + + Matches files that the preferred content settings for the repository + make it want to get. Note that this will match even files that are + already present, unless limited with e.g., `--not --in .` + + Note that this will not match anything when using --all or --unused. + +* `--want-drop` + + Matches files that the preferred content settings for the repository + make it want to drop. Note that this will match even files that have + already been dropped, unless limited with e.g., `--in .` + + Note that this will not match anything when using --all or --unused. + +* `--not` + + Inverts the next matching option. For example, to only act on + files with less than 3 copies, use `--not --copies=3` + +* `--and` + + Requires that both the previous and the next matching option matches. + The default. + +* `--or` + + Requires that either the previous, or the next matching option matches. + +* `-(` + + Opens a group of matching options. + +* `-)` + + Closes a group of matching options. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-merge.mdwn b/doc/git-annex-merge.mdwn new file mode 100644 index 000000000..346a94790 --- /dev/null +++ b/doc/git-annex-merge.mdwn @@ -0,0 +1,27 @@ +# NAME + +git-annex merge - automatically merge changes from remotes + +# SYNOPSIS + +git annex merge + +# DESCRIPTION + +This performs the same merging (and merge conflict resolution) +that is done by the sync command, but without pushing or pulling any +data. + +One way to use this is to put `git annex merge` into a repository's +post-receive hook. Then any syncs to the repository will update its +working copy automatically. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn new file mode 100644 index 000000000..7d613456b --- /dev/null +++ b/doc/git-annex-metadata.mdwn @@ -0,0 +1,83 @@ +# NAME + +git-annex metadata - sets or gets metadata of a file + +# SYNOPSIS + +git annex metadata `[path ...]` + +# 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. + +This command can be used to set metadata, or show the currently set +metadata. + +When run without any -s or -t parameters, displays the current metadata. + +# OPTIONS + +* `-g field` + + Get the value(s) of a single field. + + The values will be output one per line, with no other output, so + this is suitable for use in a script. + +* `-s field=value` + + Set a field's value, removing any old values. + +* `-s field+=value` + + Add an additional value, preserving any old values. + +* `-s field-=value` + + Remove a value. + +* `-s field?=value` + + Set a value, but only if the field does not already have a value set. + +* `-t tag` + + Set a tag. Note that a tag is just a value of the "tag" field. + +* `-u tag` + + Unset a tag. + +* `--force` + + By default, `git annex metadata` refuses to recursively set metadata + throughout the files in a directory. This option enables such recursive + setting. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to act on. + +* `--json` + + Enable JSON output. This is intended to be parsed by programs that use + git-annex. Each line of output is a JSON object. + +# EXAMPLES + +To set some tags on a file and also its author: + + git annex metadata annexscreencast.ogv -t video -t screencast -s author+=Alice + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-migrate.mdwn b/doc/git-annex-migrate.mdwn new file mode 100644 index 000000000..b6e5f9f77 --- /dev/null +++ b/doc/git-annex-migrate.mdwn @@ -0,0 +1,48 @@ +# NAME + +git-annex migrate - switch data to different backend + +# SYNOPSIS + +git annex migrate `[path ...]` + +# DESCRIPTION + +Changes the specified annexed files to use the default key-value backend +(or the one specified with `--backend`). Only files whose content +is currently available are migrated. + +Note that the content is also still available using the old key after +migration. Use `git annex unused` to find and remove the old key. + +Normally, nothing will be done to files 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. + +When you have multiple repositories that each contain a copy of a file, +it's best to run migrate in all of them. + +# OPTIONS + +* `--backend` + + Specify the new key-value backend to use for migrated data. + +* `--force` + + Force migration of keys that are already using the new backend. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to migrate. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-mirror.mdwn b/doc/git-annex-mirror.mdwn new file mode 100644 index 000000000..43e3971eb --- /dev/null +++ b/doc/git-annex-mirror.mdwn @@ -0,0 +1,57 @@ +# NAME + +git-annex mirror - mirror content of files to/from another repository + +# SYNOPSIS + +git annex mirror `[path ...] [--to=remote|--from=remote]` + +# DESCRIPTION + +This causes a destination repository to mirror a source repository. + +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. + +Note that mirror does not sync the git repository, but only the file +contents. + +# OPTIONS + +* `--to=remote` + + Use the local repository as the source repository, and mirror its contents + to the remote. + +* `--from=remote` + + Use the remote as the source repository, and mirror its contents to the local + repository. + +* `--all` + + Mirror all objects stored in the git annex, not only objects used by + currently existing files. + + However, this bypasses checking the .gitattributes annex.numcopies + setting when dropping files. + + This is the default behavior when running git-annex in a bare repository. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to mirror. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-move.mdwn b/doc/git-annex-move.mdwn new file mode 100644 index 000000000..83e968c86 --- /dev/null +++ b/doc/git-annex-move.mdwn @@ -0,0 +1,53 @@ +# NAME + +git-annex move - move content of files to/from another repository + +# SYNOPSIS + +git annex move `[path ...] [--from=remote|--to=remote]` + +# DESCRIPTION + +Moves the content of files from or to another remote. + +# OPTIONS + +* `--from=remote` + + Use this option to move the content of files from the specified + remote to the local repository. + +* `--to=remote` + + Use this option to move the content of files from the local repository + to the specified remote. + +* `--all` + + Rather than specifying a filename or path to move, this option can be + used to move all available versions of all files. + + This is the default behavior when running git-annex in a bare repository. + +* `--unused` + + Operate on files found by last run of git-annex unused. + +* `--key=keyname` + + Use this option to move a specified key. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to move. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-numcopies.mdwn b/doc/git-annex-numcopies.mdwn new file mode 100644 index 000000000..b29cbb8bf --- /dev/null +++ b/doc/git-annex-numcopies.mdwn @@ -0,0 +1,31 @@ +# NAME + +git-annex numcopies - configure desired number of copies + +# SYNOPSIS + +git annex numcopies `N` + +# DESCRIPTION + +Tells git-annex how many copies it should preserve of files, over all +repositories. The default is 1. + +Run without a number to get the current value. + +When git-annex is asked to drop a file, it first verifies that the +required number of copies can be satisfied among all the other +repositories that have a copy of the file. + +This can be overridden on a per-file basis by the annex.numcopies setting +in .gitattributes files. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-pre-commit.mdwn b/doc/git-annex-pre-commit.mdwn new file mode 100644 index 000000000..e0f6fdb2a --- /dev/null +++ b/doc/git-annex-pre-commit.mdwn @@ -0,0 +1,27 @@ +# NAME + +git-annex pre-commit - run by git pre-commit hook + +# SYNOPSIS + +git annex `[path ...]` + +# DESCRIPTION + +This is meant to be called from git's pre-commit hook. `git annex init` +automatically creates a pre-commit hook using this. + +Fixes up symlinks that are staged as part of a commit, to ensure they +point to annexed content. Also handles injecting changes to unlocked +files into the annex. When in a view, updates metadata to reflect changes +made to files in the view. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-preferred-content.mdwn b/doc/git-annex-preferred-content.mdwn new file mode 100644 index 000000000..6d5321ca2 --- /dev/null +++ b/doc/git-annex-preferred-content.mdwn @@ -0,0 +1,45 @@ +# NAME + +git-annex-preferred-content - + +# DESCRIPTION + +Each repository has a preferred content setting, which specifies content +that the repository wants to have present. These settings can be configured +using `git annex vicfg` or `git annex wanted`. +They are used by the `--auto` option, by `git annex sync --content`, +and by the git-annex assistant. + +Preferred content expressions are similar, but not identical to +the [[git-annex-matching-options]](1), just without the dashes. +For example: + + exclude=archive/* and (include=*.mp3 or smallerthan=1mb) + +The main differences are that `exclude=` and `include=` always +match relative to the top of the git repository, and that there is +no equivilant to `--in`. + +For more details about preferred content expressions, see +See <https://git-annex.branchable.com/preferred_content/> + +When a repository is in one of the standard predefined groups, like "backup" +and "client", setting its preferred content to "standard" will use a +built-in preferred content expression developed for that group. +See <https://git-annex.branchable.com/preferred_content/standard_groups/> + +If you have set a groupwanted expression for a group, it will be used +when a repository in the group has its preferred content set to +"groupwanted". + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +<http://git-annex.branchable.com/> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-proxy.mdwn b/doc/git-annex-proxy.mdwn new file mode 100644 index 000000000..23621ea06 --- /dev/null +++ b/doc/git-annex-proxy.mdwn @@ -0,0 +1,38 @@ +# NAME + +git-annex proxy - safely bypass direct mode guard + +# SYNOPSIS + +git annex proxy `-- git cmd [options]` + +# DESCRIPTION + +Only useful in a direct mode repository, this runs the specified git +command with a temporary work tree, and updates the working tree to +reflect any changes staged or committed by the git command. + +For example, to revert the most recent change that was committed +to the repository: + + git annex proxy -- git revert HEAD + +To check out a past version of the repository: + + git annex proxy -- git checkout HEAD^^ + +To rename a directory: + + git annex proxy -- git mv mydir newname + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-direct]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-readpresentkey.mdwn b/doc/git-annex-readpresentkey.mdwn new file mode 100644 index 000000000..3e552e05d --- /dev/null +++ b/doc/git-annex-readpresentkey.mdwn @@ -0,0 +1,28 @@ +# NAME + +git-annex readpresentkey - read records of where key is present + +# SYNOPSIS + +git annex readpresentkey `key uuid` + +# DESCRIPTION + +This plumbing-level command reads git-annex's records about whether +the specified key's content is present in the remote with the speficied +uuid. + +It exits 0 if the key is recorded to be present and 1 if not. + +Note that this does not do an active check to verify if the key +is present. To do such a check, use [[checkpresentkey]](1) + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-registerurl.mdwn b/doc/git-annex-registerurl.mdwn new file mode 100644 index 000000000..7295498f4 --- /dev/null +++ b/doc/git-annex-registerurl.mdwn @@ -0,0 +1,28 @@ +# NAME + +git-annex registerurl - registers an url for a key + +# SYNOPSIS + +git annex registerurl `[key url]` + +# DESCRIPTION + +This plumbing-level command can be used to register urls where a +key can be downloaded from. + +No verification is performed of the url's contents. + +If the key and url are not specified on the command line, they are +instead read from stdin. Any number of lines can be provided in this +mode, each containing a key and url, sepearated by whitespace. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-reinit.mdwn b/doc/git-annex-reinit.mdwn new file mode 100644 index 000000000..5d1b42aae --- /dev/null +++ b/doc/git-annex-reinit.mdwn @@ -0,0 +1,28 @@ +# NAME + +git-annex reinit - initialize repository, reusing old UUID + +# SYNOPSIS + +git annex reinit `uuid|description` + +# 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. + +Use this with caution; it can be confusing to have two existing +repositories with the same UUID. Also, you will probably want to run +a fsck. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-reinject.mdwn b/doc/git-annex-reinject.mdwn new file mode 100644 index 000000000..bc4b32d91 --- /dev/null +++ b/doc/git-annex-reinject.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex reinject - sets content of annexed file + +# SYNOPSIS + +git annex reinject `src dest` + +# DESCRIPTION + +Moves the src file into the annex as the content of the dest file, +which should be an already annexed file whose content is not present. + +This can be useful if you have obtained the content of a file from +elsewhere and want to put it in the local annex. + +Automatically runs fsck on dest to check that the expected content was +provided. + +Example: + + git annex reinject /tmp/foo.iso foo.iso + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-rekey.mdwn b/doc/git-annex-rekey.mdwn new file mode 100644 index 000000000..7dbe6ae96 --- /dev/null +++ b/doc/git-annex-rekey.mdwn @@ -0,0 +1,33 @@ +# NAME + +git-annex rekey - change keys used for files + +# SYNOPSIS + +git annex rekey `[file key ...]` + +# DESCRIPTION + +This plumbing-level command is similar to migrate, but you specify +both the file, and the new key to use for it. + +Multiple pairs of file and key can be given in a single command line. + +# OPTIONS + +* `--force` + + Allow rekeying of even files whose content is not currently available. + Use with caution. + +# OPTIONS + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-remotedaemon.mdwn b/doc/git-annex-remotedaemon.mdwn new file mode 100644 index 000000000..69b516283 --- /dev/null +++ b/doc/git-annex-remotedaemon.mdwn @@ -0,0 +1,34 @@ +# NAME + +git-annex remotedaemon - detects when remotes have changed, and fetches from them + +# SYNOPSIS + +git annex remotedaemon + +# DESCRIPTION + +This plumbing-level command is used by the assistant to detect +when remotes have received git pushes, so the changes can be promptly +fetched and the local repository updated. + +This is a better alternative to the [[git-annex-xmppgit]](1) +hack. + +For the remotedaemon 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. + +It's normal for this process to be running when the assistant is running. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-assistant]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-repair.mdwn b/doc/git-annex-repair.mdwn new file mode 100644 index 000000000..517dcf454 --- /dev/null +++ b/doc/git-annex-repair.mdwn @@ -0,0 +1,55 @@ +# NAME + +git-annex repair - recover broken git repository + +# SYNOPSIS + +git annex repair + +# DESCRIPTION + +This can repair many of the problems with git repositories that `git fsck` +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. + +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. + +It works by deleting any corrupt objects from the git repository, and +retrieving all missing objects it can from the remotes of the repository. + +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 +`--force` option, since that rewrites history and throws out missing data. +Note that the `--force` option never touches tags, even if they are no +longer usable due to missing data. + +After running this command, you will probably want to run `git fsck` 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. + +It is also a good idea to run `git annex fsck --fast` after this command, +to make sure that the git-annex branch reflects reality. + +# OPTIONS + +* `--force` + + Enable repair actions that involve deleting data that has been + lost due to git repository corruption. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-resolvemerge.mdwn b/doc/git-annex-resolvemerge.mdwn new file mode 100644 index 000000000..d548331a3 --- /dev/null +++ b/doc/git-annex-resolvemerge.mdwn @@ -0,0 +1,27 @@ +# NAME + +git-annex resolvemerge - resolve merge conflicts + +# SYNOPSIS + +git annex resolvemerge + +# DESCRIPTION + +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 `git annex sync` or `git annex merge`. + +Note that only merge conflicts that involve an annexed file are resolved. +Merge conflicts between two files that are not annexed will not be +automatically resolved. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-rmurl.mdwn b/doc/git-annex-rmurl.mdwn new file mode 100644 index 000000000..5e4d59f80 --- /dev/null +++ b/doc/git-annex-rmurl.mdwn @@ -0,0 +1,21 @@ +# NAME + +git-annex rmurl - record file is not available at url + +# SYNOPSIS + +git annex rmurl `file url` + +# DESCRIPTION + +Record that the file is no longer available at the url. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-schedule.mdwn b/doc/git-annex-schedule.mdwn new file mode 100644 index 000000000..78ca7a580 --- /dev/null +++ b/doc/git-annex-schedule.mdwn @@ -0,0 +1,47 @@ +# NAME + +git-annex schedule - get or set scheduled jobs + +# SYNOPSIS + +git annex schedule `repository [expression]` + +# 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. + +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. + +When run without an expression, outputs the current scheduled jobs for +the repository. + +# 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. + +To schedule multiple jobs, separate them with "; ". + + Some examples: + + 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 + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-semitrust.mdwn b/doc/git-annex-semitrust.mdwn new file mode 100644 index 000000000..e164f965d --- /dev/null +++ b/doc/git-annex-semitrust.mdwn @@ -0,0 +1,24 @@ +# NAME + +git-annex semitrust - return repository to default trust level + +# SYNOPSIS + +git annex semitrust `[repository ...]` + +# DESCRIPTION + +Returns a repository to the default semi trusted state. + +Repositories can be specified using their remote name, their +description, or their UUID. For the current repository, use "here". + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-setpresentkey.mdwn b/doc/git-annex-setpresentkey.mdwn new file mode 100644 index 000000000..9838b819d --- /dev/null +++ b/doc/git-annex-setpresentkey.mdwn @@ -0,0 +1,25 @@ +# NAME + +git-annex setpresentkey - change records of where key is present + +# SYNOPSIS + +git annex setpresentkey `key uuid [1|0]` + +# 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. + +Use 1 to indicate the key is present, or 0 to indicate the key is +not present. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-status.mdwn b/doc/git-annex-status.mdwn new file mode 100644 index 000000000..9a8929029 --- /dev/null +++ b/doc/git-annex-status.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex status - show the working tree status + +# SYNOPSIS + +git annex status `[path ...]` + +# DESCRIPTION + +Similar to `git status --short`, this command displays the status of the files +in the working tree. Shows files that are not checked into git, files that have +been deleted, and files that have been modified. + +Particularly useful in direct mode. + +# OPTIONS + +* `--json` + + Enable JSON output. This is intended to be parsed by programs that use + git-annex. Each line of output is a JSON object. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-sync.mdwn b/doc/git-annex-sync.mdwn new file mode 100644 index 000000000..fa539d8bc --- /dev/null +++ b/doc/git-annex-sync.mdwn @@ -0,0 +1,64 @@ +# NAME + +git-annex sync - synchronize local repository with remotes + +# SYNOPSIS + +git annex sync `[remote ...]` + +# DESCRIPTION + +Use this command when you want to synchronize the local repository with +one or more of its remotes. You can specify the remotes (or remote +groups) to sync with by name; the default if none are specified is to +sync with all remotes. + +The sync process involves first committing any local changes to files +that have previously been added to the repository, +then fetching and merging the `synced/master` and the `git-annex` branch +from the remote repositories, and finally pushing the changes back to +those branches on the remote repositories. You can use standard git +commands to do each of those steps by hand, or if you don't want to +worry about the details, you can use sync. + +Merge conflicts are automatically handled by sync. 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.somekey" and "foo.otherkey". + +Note that syncing with a remote will not update the remote's working +tree with changes made to the local repository. However, those changes +are pushed to the remote, so they can be merged into its working tree +by running "git annex sync" on the remote. + + +# OPTIONS + +* `--fast` + + Only sync with the remotes with the lowest annex-cost value configured. + +* `--content` + + Normally, syncing does not transfer the contents of annexed files. + This option causes the file contents to also be uploaded and downloaded + as necessary. + + By default, this tries to get each annexed file that the local repository + does not yet have, and then copies each file to every remote that it is + syncing with. This behavior can be overridden by configuring the preferred + content of a repository. See [git-annex-preferred-content](1) + +* `--message=msg` + + Use this option to specify a commit message. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-test.mdwn b/doc/git-annex-test.mdwn new file mode 100644 index 000000000..b38084028 --- /dev/null +++ b/doc/git-annex-test.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex test - run built-in test suite + +# SYNOPSIS + +git annex test + +# DESCRIPTION + +This runs git-annex's built-in test suite. + +The test suite runs in the `.t` subdirectory of the current directory +(it refuses to run if `.t` already exists). + +It can be useful to run the test suite on different filesystems, +or to verify your local installation of git-annex. + +# OPTIONS + +There are several options, provided by Haskell's tasty test +framework. Pass --help for details. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-testremote.mdwn b/doc/git-annex-testremote.mdwn new file mode 100644 index 000000000..fff08fdcc --- /dev/null +++ b/doc/git-annex-testremote.mdwn @@ -0,0 +1,39 @@ +# NAME + +git-annex testremote - test transfers to/from a remote + +# SYNOPSIS + +git annex testremote `remote` + +# DESCRIPTION + +This tests a remote by generating some random objects and sending them to +the remote, then redownloading them, removing them from the remote, etc. + +It's safe to run in an existing repository (the repository contents are +not altered), although it may perform expensive data transfers. + +Testing a single remote will use the remote's configuration, +automatically varying the chunk sizes, and with simple shared encryption +enabled and disabled. + +# OPTIONS + +* `--fast` + + Perform a smaller set of tests. + +* `--size=NUnits` + + Tune the base size of the generated objects. The default is 1MiB. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-transferkey.mdwn b/doc/git-annex-transferkey.mdwn new file mode 100644 index 000000000..ab2a7102d --- /dev/null +++ b/doc/git-annex-transferkey.mdwn @@ -0,0 +1,37 @@ +# NAME + +git-annex transferkey - transfers a key from or to a remote + +# SYNOPSIS + +git annex transferkey `key [--from=remote|--to=remote]` + +# DESCRIPTION + +This plumbing-level command is used to request a single key be +transferred. + +# OPTIONS + +* `--from=remote` + + Download the content of the key from the remote. + +* `--to=remote` + + Upload the content of the key to the remote. + +* `--file=name` + + Provides a hint about the name of the file associated with the key. + (This name is only used in progress displays.) + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-transferkeys.mdwn b/doc/git-annex-transferkeys.mdwn new file mode 100644 index 000000000..f726b9262 --- /dev/null +++ b/doc/git-annex-transferkeys.mdwn @@ -0,0 +1,29 @@ +# NAME + +git-annex transferkeys - transfers keys + +# SYNOPSIS + +git annex transferkeys + +# DESCRIPTION + +This plumbing-level command is used by the assistant to transfer data. +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). + +It's normal to have a transferkeys process running when the assistant is +running. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-assistant]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-trust.mdwn b/doc/git-annex-trust.mdwn new file mode 100644 index 000000000..fcb4a06db --- /dev/null +++ b/doc/git-annex-trust.mdwn @@ -0,0 +1,25 @@ +# NAME + +git-annex trust - trust a repository + +# SYNOPSIS + +git annex trust `[repository ...]` + +# DESCRIPTION + +Records that a repository is trusted to not unexpectedly lose +content. Use with care. + +Repositories can be specified using their remote name, their +description, or their UUID. To trust the current repository, use "here". + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-unannex.mdwn b/doc/git-annex-unannex.mdwn new file mode 100644 index 000000000..3fa0cb2f6 --- /dev/null +++ b/doc/git-annex-unannex.mdwn @@ -0,0 +1,43 @@ +# NAME + +git-annex unannex - undo accidential add command + +# SYNOPSIS + +git annex unannex `[path ...]` + +# DESCRIPTION + +Use this to undo an accidental `git annex add` command. It puts the +file back how it was before the add. + +Note that for safety, the content of the file remains in the annex, +until you use `git annex unused` and `git annex dropunused`. + +This is not the command you should use if you intentionally annexed a +file and don't want its contents any more. In that case you should use +`git annex drop` instead, and you can also `git rm` the file. + +# OPTIONS + +* `--fast` + + Normally this does a slow copy of the file. In `--fast` 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. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to unannex. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-undo.mdwn b/doc/git-annex-undo.mdwn new file mode 100644 index 000000000..391b373bf --- /dev/null +++ b/doc/git-annex-undo.mdwn @@ -0,0 +1,33 @@ +# NAME + +git-annex undo - undo last change to a file or directory + +# SYNOPSIS + +git annex `[filename|directory] ...` + +# DESCRIPTION + +When passed a filename, undoes the last change that was made to that +file. + +When passed a directory, undoes the last change that was made to the +contents of that directory. + +Running undo a second time will undo the undo, returning the working +tree to the same state it had before. In order for undoing an undo of +staged changes, any staged changes are first committed by the +undo command. + +Note that this does not undo get/drop of a file's content; it only +operates on the file tree committed to git. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-ungroup.mdwn b/doc/git-annex-ungroup.mdwn new file mode 100644 index 000000000..4d105c0fa --- /dev/null +++ b/doc/git-annex-ungroup.mdwn @@ -0,0 +1,21 @@ +# NAME + +git-annex ungroup - remove a repository from a group + +# SYNOPSIS + +git annex ungroup `repository groupname` + +# DESCRIPTION + +Removes a repository from a group. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-uninit.mdwn b/doc/git-annex-uninit.mdwn new file mode 100644 index 000000000..89678e13d --- /dev/null +++ b/doc/git-annex-uninit.mdwn @@ -0,0 +1,25 @@ +# NAME + +git-annex uninit - de-initialize git-annex and clean out repository + +# SYNOPSIS + +git annex uninit + +# 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. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-unannex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-unlock.mdwn b/doc/git-annex-unlock.mdwn new file mode 100644 index 000000000..ffcfe4523 --- /dev/null +++ b/doc/git-annex-unlock.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex unlock - unlock files for modification + +# SYNOPSIS + +git annex unlock `[path ...]` + +# DESCRIPTION + +Normally, the content of annexed files is protected from being changed. +Unlocking an annexed file allows it to be modified. This replaces the +symlink for each specified file with a copy of the file's content. +You can then modify it and `git annex add` (or `git commit`) to inject +it back into the annex. + +# OPTIONS + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to unlock. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-untrust.mdwn b/doc/git-annex-untrust.mdwn new file mode 100644 index 000000000..c0224a1dd --- /dev/null +++ b/doc/git-annex-untrust.mdwn @@ -0,0 +1,25 @@ +# NAME + +git-annex untrust - do not trust a repository + +# SYNOPSIS + +git annex untrust `[repository ...]` + +# DESCRIPTION + +Records that a repository is not trusted and could lose content +at any time. + +Repositories can be specified using their remote name, their +description, or their UUID. To untrust the current repository, use "here". + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-unused.mdwn b/doc/git-annex-unused.mdwn new file mode 100644 index 000000000..d59ef2abc --- /dev/null +++ b/doc/git-annex-unused.mdwn @@ -0,0 +1,39 @@ +# NAME + +git-annex unused - look for unused file content + +# SYNOPSIS + +git annex unused + +# DESCRIPTION + +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. + +After running this command, you can use the `--unused` option with many +other git-annex commands to operate on all the unused data that was found. + +For example, to move all unused data to origin: + + git annex unused; git annex move --unused --to origin + +# OPTIONS + +* `--fast` + + Only show unused temp and bad files. + +* `--from=remote` + + Check for unused data on a remote. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-upgrade.mdwn b/doc/git-annex-upgrade.mdwn new file mode 100644 index 000000000..0922ad87f --- /dev/null +++ b/doc/git-annex-upgrade.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex upgrade - upgrade repository layout + +# SYNOPSIS + +git annex upgrade + +# DESCRIPTION + +Upgrades the repository to current layout. + +Each git-annex repository has an annex.version in its git configuration, +that indicates the repository version. If git-annex changes to a new +layout, you must upgrade the repository before git-annex can be used in it. + +To see version information, run `git annex version`. + +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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vadd.mdwn b/doc/git-annex-vadd.mdwn new file mode 100644 index 000000000..3aaf08143 --- /dev/null +++ b/doc/git-annex-vadd.mdwn @@ -0,0 +1,36 @@ +# NAME + +git-annex vadd - add subdirs to current view + +# SYNOPSIS + +git annex vadd `[field=glob ...] [field=value ...] [tag ...]` + +# DESCRIPTION + +Changes the current view, adding an additional level of directories +to categorize the files. + +For example, when the view is by author/tag, `vadd year=*` will +change it to year/author/tag. + +So will `vadd year=2014 year=2013`, but limiting the years in view +to only those two. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-view]](1) + +[[git-annex-vpop]](1) + +[[git-annex-vfilter]](1) + +[[git-annex-vcycle]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vcycle.mdwn b/doc/git-annex-vcycle.mdwn new file mode 100644 index 000000000..b8f4f97ed --- /dev/null +++ b/doc/git-annex-vcycle.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex vcycle - switch view to next layout + +# SYNOPSIS + +git annex vcycle + +# DESCRIPTION + +When a view involves nested subdirectories, this cycles the order. + +For example, when the view is by year/author/tag, `vcycle` will switch +it to author/tag/year. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-view]](1) + +[[git-annex-vpop]](1) + +[[git-annex-vadd]](1) + +[[git-annex-vfilter]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-version.mdwn b/doc/git-annex-version.mdwn new file mode 100644 index 000000000..14b10163d --- /dev/null +++ b/doc/git-annex-version.mdwn @@ -0,0 +1,30 @@ +# NAME + +git-annex version - show version info + +# SYNOPSIS + +git annex version + +# DESCRIPTION + +Shows the version of git-annex, as well as repository version information. + +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. + +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. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vfilter.mdwn b/doc/git-annex-vfilter.mdwn new file mode 100644 index 000000000..81c4cf224 --- /dev/null +++ b/doc/git-annex-vfilter.mdwn @@ -0,0 +1,30 @@ +# NAME + +git-annex vfilter - filter current view + +# SYNOPSIS + +git annex vfilter `[tag ...] [field=value ...] [!tag ...] [field!=value ...]` + +# DESCRIPTION + +Filters the current view to only the files that have the +specified field values and tags. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-view]](1) + +[[git-annex-vpop]](1) + +[[git-annex-vadd]](1) + +[[git-annex-vcycle]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vicfg.mdwn b/doc/git-annex-vicfg.mdwn new file mode 100644 index 000000000..171a4acef --- /dev/null +++ b/doc/git-annex-vicfg.mdwn @@ -0,0 +1,23 @@ +# NAME + +git-annex vicfg - edit git-annex's configuration + +# SYNOPSIS + +git annex vicfg + +# DESCRIPTION + +Opens EDITOR on a temp file containing all of git-annex's global +configuration settings, and when it exits, stores any +changes made back to the git-annex branch. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-view.mdwn b/doc/git-annex-view.mdwn new file mode 100644 index 000000000..73b4d3438 --- /dev/null +++ b/doc/git-annex-view.mdwn @@ -0,0 +1,51 @@ +# NAME + +git-annex view - enter a view branch + +# SYNOPSIS + +git annex view `[tag ...] [field=value ...] [field=glob ...] [!tag ...] [field!=value ...]` + +# 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. + +Multiple values for a metadata field can be specified, either by using +a glob (`field="*"`) or by listing each wanted value. The resulting view +will put files in subdirectories according to the value of their fields. + +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. + +There are fields 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. + +For example, `/=podcasts` will only include files from the podcasts +directory in the view, while `podcasts/=*` will preserve the +subdirectories of the podcasts directory in the view. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-metadata]](1) + +[[git-annex-vpop]](1) + +[[git-annex-vfilter]](1) + +[[git-annex-vadd]](1) + +[[git-annex-vcycle]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-vpop.mdwn b/doc/git-annex-vpop.mdwn new file mode 100644 index 000000000..8d0e748b4 --- /dev/null +++ b/doc/git-annex-vpop.mdwn @@ -0,0 +1,32 @@ +# NAME + +git-annex vpop - switch back to previous view + +# SYNOPSIS + +git annex vpop `[N]` + +# DESCRIPTION + +Switches from the currently active view back to the previous view. +Or, from the first view back to original branch. + +The optional number tells how many views to pop. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-view]](1) + +[[git-annex-vfilter]](1) + +[[git-annex-vadd]](1) + +[[git-annex-vcycle]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-wanted.mdwn b/doc/git-annex-wanted.mdwn new file mode 100644 index 000000000..131cbe798 --- /dev/null +++ b/doc/git-annex-wanted.mdwn @@ -0,0 +1,29 @@ +# NAME + +git-annex wanted - get or set preferred content expression + +# SYNOPSIS + +git annex wanted `repository [expression]` + +# DESCRIPTION + +When run with an expression, configures the content that is preferred +to be held in the archive. See [[git-annex-preferred-content]](1) + +For example: + + git annex wanted . "include=*.mp3 or include=*.ogg" + +Without an expression, displays the current preferred content setting +of the repository. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-watch.mdwn b/doc/git-annex-watch.mdwn new file mode 100644 index 000000000..1e844d714 --- /dev/null +++ b/doc/git-annex-watch.mdwn @@ -0,0 +1,43 @@ +# NAME + +git-annex watch - watch for changes + +# SYNOPSIS + +git annex watch + +# 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. + +By default, all files in the directory will be added to the repository. +(Including dotfiles.) To block some files from being added, use +`.gitignore` files. + +By default, all files that are added are added to the annex, the same +as when you run `git annex add`. If you configure annex.largefiles, +files that it does not match will instead be added with `git add`. + +# OPTIONS + +* `--foreground` + + Avoid forking to the background. + +* `--stop` + + Stop a running daemon. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-webapp.mdwn b/doc/git-annex-webapp.mdwn new file mode 100644 index 000000000..d9e34a2e3 --- /dev/null +++ b/doc/git-annex-webapp.mdwn @@ -0,0 +1,49 @@ +# NAME + +git-annex webapp - launch webapp + +# SYNOPSIS + +git annex webapp + +# 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. + +By default, the webapp can only be accessed from localhost, and running +it opens a browser window. + +# OPTIONS + +* `--listen=address` + + Useful for using the webapp on a remote computer. This makes the webapp + listen on the specified address. + + This disables running a local web browser, and outputs the url you + can use to open the webapp. + + Set annex.listen in the git config to make the webapp always + listen on an address. + +# 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: + + openssl genrsa -out .git/annex/privkey.pem 4096 + openssl req -new -x509 -key .git/annex/privkey.pem > .git/annex/certificate.pem + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-whereis.mdwn b/doc/git-annex-whereis.mdwn new file mode 100644 index 000000000..1e1092ba3 --- /dev/null +++ b/doc/git-annex-whereis.mdwn @@ -0,0 +1,43 @@ +# NAME + +git-annex whereis - lists repositories that have file content + +# SYNOPSIS + +git annex whereis `[path ...]` + +# DESCRIPTION + +Displays information about where the contents of files are located. + +For example: + + # 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 + +# OPTIONS + +* `--json` + + Enable JSON output. This is intended to be parsed by programs that use + git-annex. Each line of output is a JSON object. + +* file matching options + + The [[git-annex-matching-options]](1) + can be used to specify files to act on. + +# SEE ALSO + +[[git-annex]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex-xmppgit.mdwn b/doc/git-annex-xmppgit.mdwn new file mode 100644 index 000000000..76ae81cb4 --- /dev/null +++ b/doc/git-annex-xmppgit.mdwn @@ -0,0 +1,23 @@ +# NAME + +git-annex xmppgit - git to XMPP relay + +# SYNOPSIS + +git annex xmppgit + +# DESCRIPTION + +This command is used internally by the assistant to perform git pulls over XMPP. + +# SEE ALSO + +[[git-annex]](1) + +[[git-annex-assistant]](1) + +# AUTHOR + +Joey Hess <id@joeyh.name> + +Warning: Automatically converted into a man page by mdwn2man. Edit with care. diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn index 6ced5c40b..a7d6c341b 100644 --- a/doc/git-annex.mdwn +++ b/doc/git-annex.mdwn @@ -60,75 +60,55 @@ files in the directory. When no path is specified, most git-annex commands default to acting on all relevant files in the current directory (and subdirectories). -* `add [path ...]` +* `help` - Adds files in the path to the annex. If no path is specified, adds - files from the current directory and below. + Display built-in help. - Files that are already checked into git, or that git has been configured - to ignore will be silently skipped. (Use `--force` to add ignored files.) + For help on a specific command, use `git annex help command` - Dotfiles are skipped unless explicitly listed, or the --include-dotfiles - option is used. +* `add [path ...]` -* `get [path ...]` + Adds files in the path to the annex. If no path is specified, adds + files from the current directory and below. + + See [[git-annex-add]](1) for details. - Makes the content of annexed files available in this repository. This - will involve copying them from another repository, or downloading them, - or transferring them from some kind of key-value store. +* `get [path ...]` - Normally git-annex will choose which repository to copy the content from, - but you can override this using the `--from` option. - - Rather than specifying a filename, the `--all` option can be used to - get all available versions of all files, or the --key=KEY` - option can be used to get a specified key. + Makes the content of annexed files available in this repository. + + See [[git-annex-get]](1) for details. * `drop [path ...]` Drops the content of annexed files from this repository. + + See [[git-annex-drop]](1) for details. - git-annex will refuse to drop content if it cannot verify it is - safe to do so. This can be overridden with the `--force` switch. - - To drop content from a remote, specify `--from`. - -* `move [path ...]` - - When used with the `--from` option, moves the content of annexed files - from the specified repository to the current one. - - When used with the `--to` option, moves the content of annexed files from - the current repository to the specified one. +* `move [path ...] [--from=remote|--to=remote]` -* `copy [path ...]` + Moves the content of files from or to another remote. - When used with the `--from` option, copies the content of annexed files - from the specified repository to the current one. + See [[git-annex-move]](1) for details. - When used with the `--to` option, copies the content of annexed files from - the current repository to the specified one. +* `copy [path ...] [--from=remote|--to=remote]` - To avoid contacting the remote to check if it has every file - when copying --to the repository, specify `--fast` + Copies the content of files from or to another remote. - To force checking the remote for every file when copying --from the - repository, specify `--force`. + See [[git-annex-copy]](1) for details. * `status [path ...]` Similar to `git status --short`, displays the status of the files in the - working tree. Shows files that are not checked into git, files that - have been deleted, and files that have been modified. - Particularly useful in direct mode. + working tree. Particularly useful in direct mode. + + See [[git-annex-status]](1) for details. * `unlock [path ...]` - Normally, the content of annexed files is protected from being changed. - Unlocking an annexed file allows it to be modified. This replaces the - symlink for each specified file with a copy of the file's content. - You can then modify it and `git annex add` (or `git commit`) to inject - it back into the annex. + Unlock annexed files for modification. + + See [[git-annex-unlock]](1) for details. * `edit [path ...]` @@ -139,209 +119,62 @@ subdirectories). Use this to undo an unlock command if you don't want to modify the files, or have made modifications you want to discard. + + See [[git-annex-lock]](1) for details. * `sync [remote ...]` - Use this command when you want to synchronize the local repository with - one or more of its remotes. You can specify the remotes (or remote - groups) to sync with by name; the default if none are specified is to - sync with all remotes. - Or specify `--fast` to sync with the remotes with the - lowest annex-cost value. - - The sync process involves first committing any local changes to files - that have previously been added to the repository, - then fetching and merging the `synced/master` and the `git-annex` branch - from the remote repositories, and finally pushing the changes back to - those branches on the remote repositories. You can use standard git - commands to do each of those steps by hand, or if you don't want to - worry about the details, you can use sync. - - Merge conflicts are automatically handled by sync. 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.somekey" and "foo.otherkey". - - Note that syncing with a remote will not update the remote's working - tree with changes made to the local repository. However, those changes - are pushed to the remote, so they can be merged into its working tree - by running "git annex sync" on the remote. - - With the `--content` option, the contents of annexed files in the work - tree will also be uploaded and downloaded from remotes. By default, - this tries to get each annexed file that the local repository does not - yet have, and then copies each file to every remote that it is syncing with. - This behavior can be overridden by configuring the preferred content of - a repository. See see PREFERRED CONTENT below. - - The `--message` or `-m` option can be used to specify a commit message. - -* `merge` - - This performs the same merging (and merge conflict resolution) - that is done by the sync command, but without pushing or pulling any data. - - One way to use this is to put `git annex merge` into a repository's - post-receive hook. Then any syncs to the repository will update its working - copy automatically. - -* `mirror [path ...]` - - This causes a destination repository to mirror a source repository. - - To use the local repository as the source repository, - specify mirror `--to` remote. - - To use a remote as the source repository, specify mirror `--from` remote. - - 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. + Synchronize local repository with remotes. + + See [[git-annex-sync]](1) for details. - Note that mirror does not sync the git repository, but only the file - contents. +* `mirror [path ...] [--to=remote|--from=remote]` - Also, --all may be specified to mirror all objects stored in the git - annex, not only objects used by currently existing files. However, this - bypasses checking the .gitattributes annex.numcopies setting when - dropping files. + Mirror content of files to/from another repository. + + See [[git-annex-mirror]](1) for details. * `addurl [url ...]` Downloads each url to its own file, which is added to the annex. - - To avoid immediately downloading the url, specify `--fast`. - - To avoid storing the size of the url's content, and accept whatever - is there at a future point, specify `--relaxed`. (Implies `--fast`.) - - 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. Or, for a - shorter filename, specify `--pathdepth=N`. For example, - `--pathdepth=1` will use "dir/subdir/bigfile", - while `--pathdepth=3` will use "bigfile". It can also be negative; - `--pathdepth=-2` will use the last two parts of the url. - - Or, to directly specify what file the url is added to, specify `--file`. - This changes the behavior; now all the specified urls are recorded as - alternate locations from which the file can be downloaded. In this mode, - addurl can be used both to add new files, or to add urls to existing files. - - When `quvi` is installed, urls are automatically tested to see if they - point to a video hosting site, and the video is downloaded instead. - - Urls to torrent files (including magnet links) will cause the content of - the torrent to be downloaded, using `aria2c`. - - To prevent special handling of urls by quvi, bittorrent, and other - special remotes, specify `--raw`. This will for example, make addurl - download the .torrent file and not the contents it points to. + + See [[git-annex-addurl]](1) for details. * `rmurl file url` Record that the file is no longer available at the url. + + See [[git-annex-rmurl]](1) for details. * `import [path ...]` - Moves files from somewhere outside the git working copy, and adds them to - the annex. Individual files to import can be specified. - If a directory is specified, the entire directory is imported. - - git annex import /media/camera/DCIM/* - - By default, importing two files with the same contents from two different - locations will result in both files being added to the repository. - (With all checksumming backends, including the default SHA256E, - only one copy of the data will be stored.) - - To not delete files from the import location, use the - `--duplicate` option. This could allow importing the same files repeatedly - to different locations in a repository. More likely, it could be used to - import the same files to a number of different branches or separate git - repositories. - - To only import files whose content has not been seen before by git-annex, - use the `--deduplicate` option. Duplicate files will be deleted from the - import location. - - To only import files whose content has not been seen before by git-annex, - but avoid deleting duplicate files, use the `--skip-duplicates` option. - - The `--clean-duplicates` option does not import any new files, but any files - found in the import location that are duplicates of content in the annex - are deleted. - - (Note that using `--deduplicate` or `--clean-duplicates` with the WORM - backend does not look at file content, but filename and mtime.) + Move and add files from outside git working copy into the annex. - To control which files are imported, many of the MATCHING OPTIONS can - be used. - - git annex import /dir --include='*.png' + See [[git-annex-import]](1) for details. * `importfeed [url ...]` - Imports the contents of podcast feeds. Only downloads files whose - urls have not already been added to the repository before, so you can - delete, rename, etc the resulting files and repeated runs won't duplicate - them. (Use `--force` to force downloading urls it's seen before.) - - Use `--template` to control where the files are stored. - The default template is '${feedtitle}/${itemtitle}${extension}' - (Other available variables: feedauthor, itemauthor, itemsummary, itemdescription, itemrights, itemid, itempubdate, title, author) - - The `--relaxed`, `--fast`, and `--raw` options behave the same as they - do in addurl. - - When quvi is installed, links in the feed are tested to see if they - are on a video hosting site, and the video is downloaded. This allows - importing e.g., youtube playlists. + Imports the contents of podcast feeds into the annex. + + See [[git-annex-importfeed]](1) for details. * `undo [filename|directory] ...` - When passed a filename, undoes the last change that was made to that - file. - - When passed a directory, undoes the last change that was made to the - contents of that directory. - - Running undo a second time will undo the undo, returning the working - tree to the same state it had before. In order for undoing an undo of - staged changes, any staged changes are first committed by the - undo command. - - Note that this does not undo get/drop of a file's content; it only - operates on the file tree committed to git. + Undo last change to a file or directory. + + See [[git-annex-undo]](1) for details. * `watch` - 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. - - By default, all files in the directory will be added to the repository. - (Including dotfiles.) To block some files from being added, use - `.gitignore` files. - - By default, all files that are added are added to the annex, the same - as when you run `git annex add`. If you configure annex.largefiles, - files that it does not match will instead be added with `git add`. - - To not daemonize, run with `--foreground` ; to stop a running daemon, - run with `--stop`. + Watch for changes and autocommit. + + See [[git-annex-watch]](1) for details. * `assistant` - Like watch, but also automatically syncs changes to other remotes. - Typically started at boot, or when you log in. + Atomatically sync folders between devices. - With the `--autostart` option, the assistant is started in any repositories - it has created. These are listed in `~/.config/git-annex/autostart`. + See [[git-annex-assistant]](1) for details. * `webapp` @@ -349,22 +182,7 @@ subdirectories). and control of the git-annex assistant. If the assistant is not already running, it will be started. - By default, the webapp can only be accessed from localhost, and running - it opens a browser window. - - To use the webapp on a remote computer, use the `--listen=address` - option to specify the address the web server should listen on - (or set annex.listen). - This disables running a local web browser, and outputs the url you - can use to open the webapp. - - 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: - - openssl genrsa -out .git/annex/privkey.pem 4096 - openssl req -new -x509 -key .git/annex/privkey.pem > .git/annex/certificate.pem + See [[git-annex-webapp]](1) for details. # REPOSITORY SETUP COMMANDS @@ -373,283 +191,162 @@ subdirectories). 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. - - 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. + + See [[git-annex-init]](1) for details. * `describe repository description` Changes the description of a repository. + + See [[git-annex-describe]](1) for details. - The repository to describe can be specified by git remote name or - by uuid. To change the description of the current repository, use - "here". - -* `initremote name [param=value ...]` +* `initremote name type=value [param=value ...]` Creates a new special remote, and adds it to `.git/config`. - The remote's configuration is specified by the parameters. Different - types of special remotes need different configuration values. The - command will prompt for parameters as needed. - - All special remotes support encryption. You can either specify - `encryption=none` to disable encryption, or specify - `encryption=hybrid keyid=$keyid ...` to specify a GPG key id (or an email - address associated with a key). - - There are actually three schemes that can be used for management of the - encryption keys. When using the encryption=hybrid scheme, additional - GPG keys can be given access to the encrypted special remote easily - (without re-encrypting everything). When using encryption=shared, - a shared key is generated and stored in the git repository, allowing - anyone who can clone the git repository to access it. Finally, when using - encryption=pubkey, content in the special remote is directly encrypted - to the specified GPG keys, and additional ones cannot easily be given - access. - - Note that with encryption enabled, 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 `--fast`, which causes it to use a lower-quality source of - randomness. - - Example Amazon S3 remote: - - git annex initremote mys3 type=S3 encryption=hybrid keyid=me@example.com datacenter=EU - + See [[git-annex-initremote]](1) for details. + * `enableremote name [param=value ...]` - Enables use of an existing special remote in the current repository, - which may be a different repository than the one in which it was - originally created with the initremote command. - - The name of the remote is the same name used when originally - creating that remote with "initremote". Run "git annex enableremote" - without any name to get a list of special remote names. - - Some special remotes may need parameters to be specified every time. - For example, the directory special remote requires a directory= parameter. - - This command can also be used to modify the configuration of an existing - special remote, by specifying new values for parameters that were - originally set when using initremote. (However, some settings such as - the as the encryption scheme cannot be changed once a special remote - has been created.) - - 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). - - One use-case of keyid-= is to replace a revoked key with - a new key: - - git annex enableremote mys3 keyid-=revokedkey keyid+=newkey - - 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. + Enables use of an existing special remote in the current repository. + + See [[git-annex-enableremote]](1) for details. * `numcopies [N]` - Tells git-annex how many copies it should preserve of files, over all - repositories. The default is 1. - - Run without a number to get the current value. - - When git-annex is asked to drop a file, it first verifies that the - required number of copies can be satisfied among all the other - repositories that have a copy of the file. - - This can be overridden on a per-file basis by the annex.numcopies setting - in .gitattributes files. + Configure desired number of copies. + + See [[git-annex-numcopies]](1) for details. * `trust [repository ...]` Records that a repository is trusted to not unexpectedly lose content. Use with care. - - To trust the current repository, use "here". + + See [[git-annex-trust]](1) for details. * `untrust [repository ...]` Records that a repository is not trusted and could lose content at any time. + + See [[git-annex-untrust]](1) for details. * `semitrust [repository ...]` Returns a repository to the default semi trusted state. + + See [[git-annex-semitrust]](1) for details. * `dead [repository ...]` Indicates that the repository has been irretrievably lost. - (To undo, use semitrust.) + + See [[git-annex-dead]](1) for details. * `group repository groupname` - Adds a repository to a group, such as "archival", "enduser", or "transfer". - The groupname must be a single word. - - Omit the groupname to show the current groups that a repository is in. + Add a repository to a group. + + See [[git-annex-group]](1) for details. * `ungroup repository groupname` Removes a repository from a group. + + See [[git-annex-ungroup]](1) for details. * `wanted repository [expression]` + + Get or set preferred content expression. - When run with an expression, configures the content that is preferred - to be held in the archive. See PREFERRED CONTENT below. - - For example: - - git annex wanted . "include=*.mp3 or include=*.ogg" - - Without an expression, displays the current preferred content setting - of the repository. + See [[git-annex-wanted]](1) for details. * `groupwanted groupname [expression]` - 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". - - For example, to configure a group named redundantarchive, and - make repositories in the group want to contain 3 copies of every file: - - 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 + See [[git-annex-groupwanted]](1) for details. * `schedule repository [expression]` - 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. See SCHEDULED JOBS below. + Get or set scheduled jobs. + + See [[git-annex-schedule]](1) for details. * `vicfg` 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. + + See [[git-annex-vicfg]](1) for details. * `direct` Switches a repository to use direct mode, where rather than symlinks to files, the files are directly present in the repository. - - As part of the switch to direct mode, any changed files will be committed. - - Note that git commands that operate on the work tree will refuse to - run in direct mode repositories. Use `git annex proxy` to safely run such - commands. + + See [[git-annex-direct]](1) for details. * `indirect` Switches a repository back from direct mode to the default, indirect mode. - - As part of the switch from direct mode, any changed files will be committed. + + See [[git-annex-indirect]](1) for details. # REPOSITORY MAINTENANCE COMMANDS * `fsck [path ...]` - With no parameters, this command checks the whole annex for consistency, - and warns about or fixes any problems found. This is a good complement to - `git fsck`. - - With parameters, only the specified files are checked. - - To check a remote to fsck, specify `--from`. - - To avoid expensive checksum calculations (and expensive transfers when - fscking a remote), specify `--fast`. + Checks the annex consistency, and warns about or fixes any problems found. + This is a good complement to `git fsck`. - To start a new incremental fsck, use the `--incremental` option. Then - the next time you fsck, you can instead use the `--more` option - to skip over files that have already been checked, and continue - where it left off. - - The `--incremental-schedule` option makes a new incremental fsck be - started a configurable time after the last incremental fsck was started. - Once the current incremental fsck has completely finished, it causes - a new one to start. - - 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: - - git annex fsck --incremental-schedule 30d --time-limit 5h - - To verify data integrity only while disregarding required number of copies, - use `--numcopies=1`. + See [[git-annex-fsck]](1) for details. * `unused` 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. - - To only show unused temp and bad files, specify `--fast`. - - To check for annexed data on a remote, specify `--from`. - - After running this command, you can use the `--unused` option to - operate on all the unused data that was found. For example, to - move all unused data to origin: - - git annex unused; git annex move --unused --to origin + + See [[git-annex-unused]](1) for details. * `dropunused [number|range ...]` Drops the data corresponding to the numbers, as listed by the last `git annex unused` - - You can also specify ranges of numbers, such as "1-1000". - Or, specify "all" to drop all unused data. - - To drop the data from a remote, specify `--from.` + + See [[git-annex-dropunused]](1) for details. * `addunused [number|range ...]` Adds back files for the content corresponding to the numbers or ranges, - as listed by the last `git annex unused`. The files will have names - starting with "unused." + as listed by the last `git annex unused`. + + See [[git-annex-addunused]](1) for details. * `fix [path ...]` Fixes up symlinks that have become broken to again point to annexed content. - This is useful to run if you have been moving the symlinks around, - but is done automatically when committing a change with git too. + + See [[git-annex-fix]](1) for details. + +* `merge` + + Automatically merge changes from remotes. + + See [[git-annex-merge]](1) for details. * `upgrade` Upgrades the repository to current layout. + + See [[git-annex-upgrade]](1) for details. * `forget` 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 `git annex log` will not be able to show where - files used to be located. - - To also prune references to repositories that have been marked as dead, - specify `--drop-dead`. - - When this rewritten branch is merged into other clones of - the repository, `git-annex` will automatically perform the same rewriting - to their local `git-annex` 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.) + data about past locations of files. + + See [[git-annex-forget]](1) for details. * `repair` @@ -657,30 +354,8 @@ subdirectories). 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. - - 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. - - It works by deleting any corrupt objects from the git repository, and - retrieving all missing objects it can from the remotes of the repository. - - 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 - `--force` option, since that rewrites history and throws out missing data. - Note that the `--force` option never touches tags, even if they are no - longer usable due to missing data. - - After running this command, you will probably want to run `git fsck` 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. - - It is also a good idea to run `git annex fsck --fast` after this command, - to make sure that the git-annex branch reflects reality. + + See [[git-annex-repair]](1) for details. # QUERY COMMANDS @@ -689,41 +364,27 @@ subdirectories). Outputs a list of annexed files in the specified path. With no path, finds files in the current directory and its subdirectories. - By default, only lists annexed files whose content is currently present. - This can be changed by specifying matching options. To list all - annexed files, present or not, specify `--include "*"`. To list all - annexed files whose content is not present, specify `--not --in=here` - - To output filenames terminated with nulls, for use with xargs -0, - specify `--print0`. Or, a custom output formatting can be specified using - `--format`. The default output format is the same as `--format='${file}\\n'` - - 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). + See [[git-annex-find]](1) for details. * `whereis [path ...]` Displays information about where the contents of files are located. + + See [[git-annex-whereis]](1) for details. * `list [path ...]` Displays a table of remotes that contain the contents of the specified - files. This is similar to whereis but a more compact display. Only - configured remotes are shown by default; specify --allrepos to list - all repositories. + files. This is similar to whereis but a more compact display. + + See [[git-annex-list]](1) for details. * `log [path ...]` Displays the location log for the specified file or files, showing each repository they were added to ("+") and removed from ("-"). - To limit how far back to search for location log changes, the options - `--since`, `--after`, `--until`, `--before`, and `--max-count` can be specified. - They are passed through to git log. For example, `--since "1 month ago"` - - To generate output suitable for the gource visualization program, - specify `--gource`. + See [[git-annex-log]](1) for details. * `info [directory|file|remote|uuid ...]` @@ -733,72 +394,33 @@ subdirectories). When no item is specified, displays statistics and information for the repository as a whole. - - When a directory is specified, the MATCHING OPTIONS can be used - to select the files in the directory that are included in the statistics. - - To only show the data that can be gathered quickly, use `--fast`. - - For example, suppose you want to run "git annex get .", but - would first like to see how much disk space that will use. - Then run: - - git annex info --fast . --not --in here + + See [[git-annex-info]](1) for details. * `version` Shows the version of git-annex, as well as repository version information. + + See [[git-annex-version]](1) for details. * `map` - 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 `dot` command is available, it is - used to display the file to your screen (using x11 backend). (To disable - this display, specify `--fast`) - - 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. - - Also, if connecting to a host requires a password, you might have to enter - it several times as the map is being built. + Generate map of repositories. - Note that this subcommand can be used to graph any git repository; it - is not limited to git-annex repositories. + See [[git-annex-map]](1) for details. # METADATA COMMANDS -* `metadata [path ...] [-s field=value -s field+=value -s field-=value ...] [-g field]` +* `metadata [path ...]` - The content of a file can have any number of metadata fields + 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. This command can be used to set metadata, or show the currently set metadata. - To show current metadata, run without any -s parameters. The --json - option will enable json output. - - To only get the value(s) of a single field, use -g field. - The values will be output one per line, with no other output, so - this is suitable for use in a script. - - To set a field's value, removing any old value(s), use -s field=value. - - To add an additional value, use -s field+=value. - - To remove a value, use -s field-=value. - - To set a value, only if the field does not already have a value, - use -s field?=value - - To set a tag, use -t tag, and use -u tag to remove a tag. - - For example, to set some tags on a file and also its author: - - git annex metadata annexscreencast.ogv -t video -t screencast -s author+=Alice + See [[git-annex-metadata]](1) for details. * `view [tag ...] [field=value ...] [field=glob ...] [!tag ...] [field!=value ...]` @@ -807,68 +429,42 @@ subdirectories). metadata matches all the specified field values and tags will be shown in the view. - Multiple values for a metadata field can be specified, either by using - a glob (`field="*"`) or by listing each wanted value. The resulting view - will put files in subdirectories according to the value of their fields. - - 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. - - There are fields 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. - - For example, `/=podcasts` will only include files from the podcasts - directory in the view, while `podcasts/=*` will preserve the - subdirectories of the podcasts directory in the view. + See [[git-annex-view]](1) for details. * `vpop [N]` Switches from the currently active view back to the previous view. Or, from the first view back to original branch. - - The optional number tells how many views to pop. + + See [[git-annex-vpop]](1) for details. * `vfilter [tag ...] [field=value ...] [!tag ...] [field!=value ...]` Filters the current view to only the files that have the specified field values and tags. + + See [[git-annex-vfilter]](1) for details. * `vadd [field=glob ...] [field=value ...] [tag ...]` Changes the current view, adding an additional level of directories to categorize the files. - - For example, when the view is by author/tag, `vadd year=*` will - change it to year/author/tag. - - So will `vadd year=2014 year=2013`, but limiting the years in view - to only those two. + + See [[git-annex-vfilter]](1) for details. * `vcycle` When a view involves nested subdirectories, this cycles the order. - - For example, when the view is by year/author/tag, `vcycle` will switch - it to author/tag/year. + + See [[git-annex-vcycle]](1) for details. # UTILITY COMMANDS * `migrate [path ...]` - Changes the specified annexed files to use the default key-value backend - (or the one specified with `--backend`). Only files whose content - is currently available are migrated. - - Note that the content is also still available using the old key after - migration. Use `git annex unused` to find and remove the old key. - - Normally, nothing will be done to files 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. - (To force migration of keys already using the new backend, use --force.) + Changes the specified annexed files to use a different key-value backend. + + See [[git-annex-migrate]](1) for details. * `reinject src dest` @@ -876,46 +472,26 @@ subdirectories). This can be useful if you have obtained the content of a file from elsewhere and want to put it in the local annex. - Automatically runs fsck on dest to check that the expected content was - provided. - - Example: - - git annex reinject /tmp/foo.iso foo.iso + See [[git-annex-reinject]](1) for details. * `unannex [path ...]` Use this to undo an accidental `git annex add` command. It puts the file back how it was before the add. - - Note that for safety, the content of the file remains in the annex, - until you use `git annex unused` and `git annex dropunused`. - - This is not the command you should use if you intentionally annexed a - file and don't want its contents any more. In that case you should use - `git annex drop` instead, and you can also `git rm` the file. - - Normally this does a slow copy of the file. In `--fast` 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. + + See [[git-annex-unannex]](1) for details. * `uninit` - 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. + De-initialize git-annex and clean out repository. + + See [[git-annex-unannex]](1) for details. * `reinit uuid|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. - - Use this with caution; it can be confusing to have two existing - repositories with the same UUID. Also, you will probably want to run - a fsck. + Initialize repository, reusing old UUID. + + See [[git-annex-reinit]](1) for details. # PLUMBING COMMANDS @@ -923,115 +499,81 @@ subdirectories). This is meant to be called from git's pre-commit hook. `git annex init` automatically creates a pre-commit hook using this. - - Fixes up symlinks that are staged as part of a commit, to ensure they - point to annexed content. Also handles injecting changes to unlocked - files into the annex. When in a view, updates metadata to reflect changes - made to files in the view. + + See [[git-annex-pre-commit]](1) for details. * `lookupkey [file ...]` - 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. - -* `examinekey [key ...]` + Looks up key used for file. - This plumbing-level command is given a key, and prints information - that can be determined purely by looking at the key. + See [[git-annex-lookupkey]](1) for details. - To specify what information to print, use `--format`. Or use `--json` - to get all available information in JSON format. - - The same variables can be used in the format string as can be used in - the format string of git annex find (except there is no file option - here). - - For example, the location a key's value is stored (in indirect mode) - can be looked up by running: +* `examinekey [key ...]` - git annex examinekey --format='.git/annex/objects/${hashdirmixed}${key}/${key}' + Print information that can be determined purely by looking at the key. + + See [[git-annex-examinekey]](1) for details. * `fromkey [key file]` - This plumbing-level command can be used to manually set up a file - in the git repository to link to a specified key. - - Normally, the annex needs to already contain the content object for the - key. To override this, use --force. - - If the key and file are not specified on the command line, they are - instead read from stdin. Any number of lines can be provided in this - mode, each containing a key and filename, sepearated by whitespace. + Manually set up a file in the git repository to link to a specified key. + + See [[git-annex-fromkey]](1) for details. * `registerurl [key url]` - This plumbing-level command can be used to register urls where a - key can be downloaded from. - - No verification is performed of the url's contents. - - If the key and url are not specified on the command line, they are - instead read from stdin. Any number of lines can be provided in this - mode, each containing a key and url, sepearated by whitespace. + Registers an url for a key. + + See [[git-annex-registerurl]](1) for details. * `dropkey [key ...]` - This plumbing-level command drops the annexed data for the specified - keys from this repository. - - 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. + Drops annexed content for specified keys. + + See [[git-annex-dropkey]](1) for details. -* `transferkey` +* `transferkey key [--from=remote|--to=remote]` - This plumbing-level command is used to request a single key be - transferred. Either the --from or the --to option can be used to specify - the remote to use. A --file option can be used to hint at the file - associated with the key. + Transfers a key from or to a remote. + + See [[git-annex-transferkey]](1) for details. * `transferkeys` + + Used internally by the assistant. - This plumbing-level command is used by the assistant to transfer data. - It 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). + See [[git-annex-transferkey]](1) for details. * `setpresentkey key uuid [1|0]` 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. + See [[git-annex-setpresentkey]](1) for details. + * `readpresentkey key uuid` - This plumbing-level command reads git-annex's records about whether - the specified key's content is present in the remote with the speficied - uuid. + Read records of where key is present. - It exits 0 if the key is recorded to be present and 1 if not. + See [[git-annex-readpresentkey]](1) for details. * `checkpresentkey key remote` - This plumbing-level command verifies if the specified key's content - is present in the specified remote. - - Exits 0 if the content is verified present, or 1 if it is verified to not - be present. If there is a problem checking the remote, the special - exit code 100 is used, and an error message is output to stderr. + Check if key is present in remote. + + See [[git-annex-checkpresentkey]](1) for details. * `rekey [file key ...]` - This plumbing-level command is similar to migrate, but you specify - both the file, and the new key to use for it. - - With `--force`, even files whose content is not currently available will - be rekeyed. Use with caution. + Change keys used for files. + + See [[git-annex-rekey]](1) for details. * `findref [ref]` - This is similar to the find command, but instead of finding files in the - current work tree, it finds files in the specified git ref. + Lists files in a git ref. + + See [[git-annex-findref]](1) for details. * `proxy -- git cmd [options]` @@ -1039,18 +581,7 @@ subdirectories). command with a temporary work tree, and updates the working tree to reflect any changes staged or committed by the git command. - For example, to revert the most recent change that was committed - to the repository: - - git annex proxy -- git revert HEAD - - To check out a past version of the repository: - - git annex proxy -- git checkout HEAD^^ - - To rename a directory: - - git annex proxy -- git mv mydir newname + See [[git-annex-proxy]](1) for details. * `resolvemerge` @@ -1058,41 +589,35 @@ subdirectories). file to the tree, using variants of their filename. This is done automatically when using `git annex sync` or `git annex merge`. - Note that only merge conflicts that involve an annexed file are resolved. - Merge conflicts between two files that are not annexed will not be - automatically resolved. + See [[git-annex-resolvemerge]](1) for details. * `diffdriver` - This is an external git diff driver shim. Normally, when using `git diff` - with an external git driver, the symlinks to annexed files are not set up - right, so the external git driver cannot read them in order to perform - smart diffing of their contents. This command works around the problem, - by passing the fixed up files to the real external diff driver. - - To use, just configure git to use "git-annex diffdriver -- cmd params --" - as the external diff command, where cmd is the real external diff - command you want to use, and params are any extra parameters to pass - to it. Note the trailing "--", which is required. + This can be used to make `git diff` use an external diff driver with + annexed files. - For example, set `GIT_EXTERNAL_DIFF=git-annex diffdriver -- j-c-diff --` + See [[git-annex-diffdriver]](1) for details. * `remotedaemon` Detects when network remotes have received git pushes and fetches from them. + See [[git-annex-remotedaemon]](1) for details. + * `xmppgit` - This command is used internally to perform git pulls over XMPP. + This command is used internally by the assistant to perform git pulls + over XMPP. + + See [[git-annex-xmppgit]](1) for details. # TESTING COMMANDS * `test` This runs git-annex's built-in test suite. - - There are several parameters, provided by Haskell's tasty test framework. - Pass --help for details. + + See [[git-annex-test]](1) for details. * `testremote remote` @@ -1101,22 +626,21 @@ subdirectories). It's safe to run in an existing repository (the repository contents are not altered), although it may perform expensive data transfers. - - To perform a smaller set of tests, use --fast. - - The --size option can be used to tune the size of the generated objects. - - Testing a single remote will use the remote's configuration, - automatically varying the chunk sizes, and with simple shared encryption - enabled and disabled. + + See [[git-annex-testremote]](1) for details. * `fuzztest` 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. + for use in testing the assistant. + + See [[git-annex-fuzztest]](1) for details. + +# COMMON OPTIONS -# OPTIONS +These common options are accepted by all git-annex commands, and +may not be explicitly listed on their individual man pages. +(Many commands also accept the [[git-annex-matching-options]](1).) * `--force` @@ -1135,23 +659,6 @@ subdirectories). will only do so when needed to help satisfy the setting of numcopies, and preferred content configuration. -* `--all` - - Operate on all data that has been stored in the git annex, - including old versions of files. This is the default behavior when - running git-annex in a bare repository; in a non-bare repository the - normal behavior is to only operate on specified files in the working - tree. - -* `--unused` - - Operate on all data that has been determined to be unused by - a previous run of `git-annex unused`. - -* `--key=key` - - Operate on only the specified key. - * `--quiet` Avoid the default verbose display of what is done; only show errors @@ -1161,13 +668,6 @@ subdirectories). Enable verbose display. -* `--json` - - Rather than the normal output, generate JSON. This is intended to be - parsed by programs that use git-annex. Each line of output is a JSON - object. Note that JSON output is only usable with some git-annex commands, - like info, find, whereis, and metadata. - * `--debug` Show debug messages. @@ -1176,19 +676,6 @@ subdirectories). Disable debug messages. -* `--from=repository` - - Specifies a repository that content will be retrieved from, or that - should otherwise be acted on. - - It should be specified using the name of a configured remote. - -* `--to=repository` - - Specifies a repository that content will be sent to. - - It should be specified using the name of a configured remote. - * `--numcopies=n` Overrides the numcopies setting, forcing git-annex to ensure the @@ -1234,16 +721,6 @@ subdirectories). are in the annex, their backend is known and this option is not necessary. -* `--format=value` - - Specifies a custom output format. 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 in a variable, - use '${escaped_var}' - - Also, '\\n' is a newline, '\\000' is a NULL, etc. - * `--user-agent=value` Overrides the User-Agent to use when downloading files from the web. @@ -1265,205 +742,6 @@ subdirectories). Overrides git configuration settings. May be specified multiple times. -# MATCHING OPTIONS - -These options can all be specified multiple times, and can be combined to -limit which files git-annex acts on. - -Arbitrarily complicated expressions can be built using these options. -For example: - - --exclude '*.mp3' --and --not -( --in=usbdrive --or --in=archive -) - -The above example prevents git-annex from working on mp3 files whose -file contents are present at either of two repositories. - -* `--exclude=glob` - - Skips files matching the glob pattern. The glob is matched relative to - the current directory. For example: - - --exclude='*.mp3' --exclude='subdir/*' - - Note that this will not match anything when using --all or --unused. - -* `--include=glob` - - Skips files not matching the glob pattern. (Same as `--not --exclude`.) - For example, to include only mp3 and ogg files: - - --include='*.mp3' --or --include='*.ogg' - - Note that this will not skip anything when using --all or --unused. - -* `--in=repository` - - Matches only files that git-annex believes have their contents present - in a repository. Note that it does not check the repository to verify - that it still has the content. - - 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 `--in=here` - -* `--in=repository@{date}` - - Matches files currently in the work tree whose content was present in - the repository on the given date. - - The date is specified in the same syntax documented in - gitrevisions(7). Note that this uses the reflog, so dates far in the - past cannot be queried. - - For example, you might need to run `git annex drop .` to temporarily - free up disk space. The next day, you can get back the files you dropped - using `git annex get . --in=here@{yesterday}` - -* `--copies=number` - - 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. - -* `--copies=trustlevel:number` - - Matches only files that git-annex believes have the specified number of - copies, on remotes with the specified trust level. For example, - `--copies=trusted:2` - - To match any trust level at or higher than a given level, - use 'trustlevel+'. For example, `--copies=semitrusted+:2` - -* `--copies=groupname:number` - - Matches only files that git-annex believes have the specified number of - copies, on remotes in the specified group. For example, - `--copies=archive:2` - -* `--lackingcopies=number` - - 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. - -* `--approxlackingcopies=number` - - Like lackingcopies, but does not look at .gitattributes annex.numcopies - settings. This makes it significantly faster. - -* `--inbackend=name` - - Matches only files whose content is stored using the specified key-value - backend. - -* `--inallgroup=groupname` - - Matches only files that git-annex believes are present in all repositories - in the specified group. - -* `--smallerthan=size` -* `--largerthan=size` - - Matches only files whose content is smaller than, or larger than the - specified size. - - The size can be specified with any commonly used units, for example, - "0.5 gb" or "100 KiloBytes" - -* `--metadata field=glob` - - Matches only files that have a metadata field attached with a value that - matches the glob. The values of metadata fields are matched case - insensitively. - -* `--want-get` - - Matches files that the preferred content settings for the repository - make it want to get. Note that this will match even files that are - already present, unless limited with e.g., `--not --in .` - - Note that this will not match anything when using --all or --unused. - -* `--want-drop` - - Matches files that the preferred content settings for the repository - make it want to drop. Note that this will match even files that have - already been dropped, unless limited with e.g., `--in .` - - Note that this will not match anything when using --all or --unused. - -* `--not` - - Inverts the next matching option. For example, to only act on - files with less than 3 copies, use `--not --copies=3` - -* `--and` - - Requires that both the previous and the next matching option matches. - The default. - -* `--or` - - Requires that either the previous, or the next matching option matches. - -* `-(` - - Opens a group of matching options. - -* `-)` - - Closes a group of matching options. - -# PREFERRED CONTENT - -Each repository has a preferred content setting, which specifies content -that the repository wants to have present. These settings can be configured -using `git annex vicfg` or `git annex wanted`. -They are used by the `--auto` option, and by the git-annex assistant. - -The preferred content settings are similar, but not identical to -the matching options specified above, just without the dashes. -For example: - - exclude=archive/* and (include=*.mp3 or smallerthan=1mb) - -The main differences are that `exclude=` and `include=` always -match relative to the top of the git repository, and that there is -no equivilant to `--in`. - -When a repository is in one of the standard predefined groups, like "backup" -and "client", setting its preferred content to "standard" will use a -built-in preferred content expression developed for that group. -See <https://git-annex.branchable.com/preferred_content/standard_groups/> - -If you have set a groupwanted expression for a group, it will be used -when a repository in the group has its preferred content set to -"groupwanted". - -# SCHEDULED JOBS - -The git-annex assistant 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. - -The scheduled jobs can be configured using `git annex vicfg` or -`git annex schedule`. - -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. - -To schedule multiple jobs, separate them with "; ". - -Some examples: - - 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 - # CONFIGURATION VIA .git/config Like other git commands, git-annex is configured via `.git/config`. @@ -1963,7 +1241,7 @@ whenever the git-annex branch is updated. You can make this hook run # SEE ALSO -Most of git-annex's documentation is available on its web site, +More git-annex documentation is available on its web site, <http://git-annex.branchable.com/> If git-annex is installed from a package, a copy of its documentation diff --git a/doc/internals.mdwn b/doc/internals.mdwn index a562d6067..824655a92 100644 --- a/doc/internals.mdwn +++ b/doc/internals.mdwn @@ -241,7 +241,7 @@ space and then its schedule, followed by a timestamp. There can be multiple events in the schedule, separated by "; ". The format of the scheduled events is the same described in -the SCHEDULED JOBS section of the man page. +[[git-annex-schedule]]. Example: |