From a71c002ac19aa3c506d7e6119c67ee693c787c72 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Thu, 13 May 2021 16:17:45 -0400 Subject: [PATCH] git-annex-filter-branch man page --- doc/git-annex-filter-branch.mdwn | 129 +++++++++++++++++++++++++++++++ doc/git-annex-forget.mdwn | 2 + doc/git-annex.mdwn | 6 ++ 3 files changed, 137 insertions(+) create mode 100644 doc/git-annex-filter-branch.mdwn diff --git a/doc/git-annex-filter-branch.mdwn b/doc/git-annex-filter-branch.mdwn new file mode 100644 index 0000000000..4565977287 --- /dev/null +++ b/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 + +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 index 003e2946ca..61cf4d506a 100644 --- a/doc/git-annex-forget.mdwn +++ b/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 diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn index 5038f30e49..bfa1a3a06d 100644 --- a/doc/git-annex.mdwn +++ b/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` -- 2.30.2