finished splitting out man pages for all commands

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.

doc/git-annex-copy.mdwn

@@ -36,6 +36,8 @@ Copies the content of files from or to another remote.
   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.

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.

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.

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.

doc/git-annex-find.mdwn

@@ -17,20 +17,30 @@ finds files in the current directory and its subdirectories.
 
   Output filenames terminated with nulls, for use with `xargs -0`
 
-* `--format=fmt`
+* `--format=value`
 
   Use custom output formatting.
 
-  The default output format is the same as `--format='${file}\\n'`
+  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)

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.

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.

doc/git-annex-fsck.mdwn

@@ -65,6 +65,8 @@ With parameters, only the specified files are checked.
   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.

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.

doc/git-annex-get.mdwn

@@ -24,6 +24,8 @@ or transferring them from some kind of key-value store.
   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.

doc/git-annex-info.mdwn

@@ -23,7 +23,8 @@ for the repository as a whole.
 
 * `--json`
 
-  Enable JSON output.
+  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
 

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.

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.

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.

doc/git-annex-mirror.mdwn

@@ -39,6 +39,8 @@ contents.
   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)

doc/git-annex-move.mdwn

@@ -27,6 +27,8 @@ Moves the content of files from or to another remote.
   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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

doc/git-annex-status.mdwn

@@ -18,7 +18,8 @@ Particularly useful in direct mode.
 
 * `--json`
 
-  Enable JSON output.
+  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
 

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

doc/git-annex-whereis.mdwn

@@ -24,7 +24,8 @@ For example:
 
 * `--json`
 
-  Enable JSON output format.
+  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
   

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.

doc/git-annex.mdwn

@@ -411,36 +411,16 @@ subdirectories).
 
 # 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
+  See [[git-annex-metadata]](1) for details.
-  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
 
 * `view [tag ...] [field=value ...] [field=glob ...] [!tag ...] [field!=value ...]`
 
@@ -449,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
+  See [[git-annex-view]](1) for details.
-  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.
 
 * `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
+  See [[git-annex-vfilter]](1) for details.
-  change it to year/author/tag.
-
-  So will `vadd year=2014 year=2013`, but limiting the years in view
-  to only those two.
 
 * `vcycle`
 
   When a view involves nested subdirectories, this cycles the order.
-
+  
-  For example, when the view is by year/author/tag, `vcycle` will switch
+  See [[git-annex-vcycle]](1) for details.
-  it to author/tag/year.
 
 # UTILITY COMMANDS
 
 * `migrate [path ...]`
 
-  Changes the specified annexed files to use the default key-value backend
+  Changes the specified annexed files to use a different key-value backend.
-  (or the one specified with `--backend`). Only files whose content
+  
-  is currently available are migrated.
+  See [[git-annex-migrate]](1) for details.
-
-  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.)
 
 * `reinject src dest`
 
@@ -518,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
+  See [[git-annex-reinject]](1) for details.
-  provided.
-
-  Example:
-
-        	git annex reinject /tmp/foo.iso foo.iso
 
 * `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,
+  See [[git-annex-unannex]](1) for details.
-  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.
 
 * `uninit`
 
-  Use this to stop using git annex. It will unannex every file in the
+  De-initialize git-annex and clean out repository.
-  repository, and remove all of git-annex's other data, leaving you with a
+  
-  git repository plus the previously annexed files.
+  See [[git-annex-unannex]](1) for details.
 
 * `reinit uuid|description`
 
-  Normally, initializing a repository generates a new, unique identifier
+  Initialize repository, reusing old UUID.
-  (UUID) for that repository. Occasionally it may be useful to reuse a
+  
-  UUID -- for example, if a repository got deleted, and you're
+  See [[git-annex-reinit]](1) for details.
-  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.
 
 # PLUMBING COMMANDS
 
@@ -565,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
+  See [[git-annex-pre-commit]](1) for details.
-  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.
 
 * `lookupkey [file ...]`
 
-  This plumbing-level command looks up the key used for a file in the
+  Looks up key used for file.
-  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),
+  See [[git-annex-lookupkey]](1) for details.
-  nothing is output, and it exits nonzero.
 
 * `examinekey [key ...]`
 
-  This plumbing-level command is given a key, and prints information
+  Print information that can be determined purely by looking at the key.
-  that can be determined purely by looking at the key.
+  
-
+  See [[git-annex-examinekey]](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:
-
-        	git annex examinekey --format='.git/annex/objects/${hashdirmixed}${key}/${key}'
 
 * `fromkey [key file]`
 
-  This plumbing-level command can be used to manually set up a file
+  Manually set up a file in the git repository to link to a specified key.
-  in the git repository to link to a specified key.
+  
-
+  See [[git-annex-fromkey]](1) for details.
-  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.
 
 * `registerurl [key url]`
 
-  This plumbing-level command can be used to register urls where a
+  Registers an url for a key.
-  key can be downloaded from.
+  
-
+  See [[git-annex-registerurl]](1) for details.
-  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.
 
 * `dropkey [key ...]`
 
-  This plumbing-level command drops the annexed data for the specified
+  Drops annexed content for specified keys.
-  keys from this repository.
+  
+  See [[git-annex-dropkey]](1) for details.
 
-  This can be used to drop content for arbitrary keys, which do not need
+* `transferkey key [--from=remote|--to=remote]`
-  to have a file in the git repository pointing at them.
 
-* `transferkey`
+  Transfers a key from or to a remote.
-
+  
-  This plumbing-level command is used to request a single key be
+  See [[git-annex-transferkey]](1) for details.
-  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.
 
 * `transferkeys`
+  
+  Used internally by the assistant.
 
-  This plumbing-level command is used by the assistant to transfer data.
+  See [[git-annex-transferkey]](1) for details.
-  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).
 
 * `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
+  Read records of where key is present.
-  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.
+  See [[git-annex-readpresentkey]](1) for details.
 
 * `checkpresentkey key remote`
 
-  This plumbing-level command verifies if the specified key's content
+  Check if key is present in remote.
-  is present in the specified remote.
+  
-
+  See [[git-annex-checkpresentkey]](1) for details.
-  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.
 
 * `rekey [file key ...]`
 
-  This plumbing-level command is similar to migrate, but you specify
+  Change keys used for files.
-  both the file, and the new key to use for it.
+  
-
+  See [[git-annex-rekey]](1) for details.
-  With `--force`, even files whose content is not currently available will
-  be rekeyed. Use with caution.
 
 * `findref [ref]`
 
-  This is similar to the find command, but instead of finding files in the
+  Lists files in a git ref.
-  current work tree, it finds files in the specified git ref.
+  
+  See [[git-annex-findref]](1) for details.
 
 * `proxy -- git cmd [options]`
 
@@ -681,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
+  See [[git-annex-proxy]](1) for details.
-  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
 
 * `resolvemerge`
 
@@ -700,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.
+  See [[git-annex-resolvemerge]](1) for details.
-  Merge conflicts between two files that are not annexed will not be
-  automatically resolved.
 
 * `diffdriver`
 
-  This is an external git diff driver shim. Normally, when using `git diff`
+  This can be used to make `git diff` use an external diff driver with
-  with an external git driver, the symlinks to annexed files are not set up
+  annexed files.
-  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 --"
+  See [[git-annex-diffdriver]](1) for details.
-  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 --`
 
 * `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.
+  See [[git-annex-test]](1) for details.
-  Pass --help for details.
 
 * `testremote remote`
 
@@ -743,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.
+  See [[git-annex-testremote]](1) for details.
-
-  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.
 
 * `fuzztest`
 
   Generates random changes to files in the current repository,
-  for use in testing the assistant. This is dangerous, so it will not
+  for use in testing the assistant.
-  do anything unless --forced.
+  
+  See [[git-annex-fuzztest]](1) for details.
 
-# OPTIONS
+# COMMON 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`
 
@@ -777,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
@@ -803,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.
@@ -818,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
@@ -876,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.