git-annex-filter-branch man page

doc/git-annex-filter-branch.mdwn

@@ -0,0 +1,129 @@
+# NAME
+
+git-annex filter-branch - filter information from the git-annex branch
+
+# SYNOPSIS
+
+git annex filter-branch [...]
+
+# DESCRIPTION
+
+This copies selected information from the git-annex branch into a git
+commit object, and outputs its hash. The git commit can be transported
+to another git repository, and given a branch name such as "foo/git-annex",
+and git-annex there will automatically merge that into its git-annex
+branch. This allows publishing some information from your git-annex branch,
+without publishing the whole thing.
+
+Other ways to avoid publishing information from a git-annex branch
+include [[git-annex-forget]](1), the `annex.private` git config,
+and the `--private` option to [[git-annex-initremote](1). Those are much
+easier to use, but this provides full control for those who need it.
+
+With no options, no information at all will be included from the git-annex
+branch. Use options to specify what to include. All options can be specified
+multiple times.
+
+# OPTIONS
+
+* `path`
+
+  Include information about all keys of annexed files in the path.
+
+* file matching options
+
+  The [[git-annex-matching-options]](1)
+  can be used to specify which files in a path to include.
+
+* `--branch=ref`
+
+  Include information about keys referred of annexed files in the branch
+  or treeish.
+
+* `--key=key`
+
+  Include information about a specific key.
+
+* `--all`
+
+  Include information about all keys.
+
+* `--include-key-information-for=repo`
+
+  When including information about a key, include information specific to
+  this repository. The repository can be specified with a uuid or the name
+  of a remote.
+
+* `--exclude-key-information-for=repo`
+
+  When including information about a key, exclude information specific to
+  this repository. The repository can be specified with a uuid or the name
+  of a remote. When this is used, all repositories that are not
+  excluded will be included.
+
+* `--include-all-key-information`
+
+  Include key information for all repositories.
+
+* `--include-repo-config-for=repo`
+
+  Include configuration specific to this repository. 
+  The repository can be specified with a uuid or the name of a remote.
+
+  This includes the configuration of special remotes, which may include
+  embedded credentials, or encryption parameters. It also includes trust
+  settings, preferred content, etc. It does not include information
+  about any git-annex keys.
+
+* `--exclude-repo-config-for=repo`
+
+  Exclude configuration specific to this repository. 
+  The repository can be specified with a uuid or the name of a remote.
+  When this is used, all repositories that are not excluded will be included.
+
+* `--include-all-repo-config`
+
+* `--include-global-config`
+
+  Include global configuration, that is not specific to any repository.
+
+  This includes configs stored by [[git-annex-numcopies]](1),
+  [[git-annex-config]](1), etc.
+
+* `--exclude-global-config`
+
+  Do not include global configuration.
+
+# EXAMPLES
+
+You have a big git-annex repository and are splitting the directory "foo"
+out, to make a smaller repository. You want the smaller repo's git-annex
+branch to contain all the information about remotes and other configuration,
+but only information about keys in that directory.
+
+	git-annex filter-branch foo --include-all-key-information \
+		--include-all-repo-config --include-global-config
+
+That only includes information about the keys that are currently
+in the directory "foo", not keys used by old versions of files.
+To also include information about the version of the subdir in
+tag "1.0", add the option `--branch=1.0:foo`
+
+Your repository has a special remote "bar", and you want to share information
+about which annexed files are stored in it, but without sharing anything
+about the configuration of the remote.
+
+	git-annex filter-branch --all --include-all-key-information \
+		--exclude-repo-config-for=bar --include-global-config
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-forget]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.

doc/git-annex-forget.mdwn

@@ -32,6 +32,8 @@ git to push the branch to any git repositories not running git-annex.)
 
 [[git-annex]](1)
 
+[[git-annex-filter-branch]](1)
+
 # AUTHOR
 
 Joey Hess <id@joeyh.name>

doc/git-annex.mdwn

@@ -404,6 +404,12 @@ content from the key-value store.
   
   See [[git-annex-forget]](1) for details.
 
+* `filter-branch`
+
+  Produces a filtered version of the git-annex branch.
+  
+  See [[git-annex-filter-branch]](1) for details.
+
 * `repair`
 
   This can repair many of the problems with git repositories that `git fsck`