git-annex/doc/git-annex-filter-branch.mdwn

# 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,
or remove information from it 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.

When the repository contains information about a private
repository (due to `annex.private` being set, or `git-annex initremote
--private` being used), that private information will be included when
allowed by the options, even though it is not recorded on the git-annex
branch.

When a repository was created with `git annex initremote --sameas=foo`,
its information will be included when the information for foo is,
and excluded when foo is excluded.

When a special remote is configured with importtree=yes or exporttree=yes,
normally the git tree corresponding to the repository is included in
the git-annex branch, to make sure it does not get garbage collected
by `git gc`. Those trees are *not* included when filtering the git-annex
branch. Usually this will not cause any problems, but if such a tree does
get garbage collected, it will prevent accessing files on the special
remote, until the next time a tree is imported or exported to it.

# 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. This option can be used repeatedly to include several
  repositories.

* `--include-all-key-information`

  Include key information for all repositories, except any excluded with
  the `--exclude-key-information-for` option.

* `--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. This option can be used repeatedly to exclude
  several 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. This option can be used repeatedly to include
  several repositories.

* `--include-all-repo-config`

  Include the configuration of all repositories, except for any excluded
  with the `--exclude-repo-config-for` option.

* `--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.
  This option can be used repeatedly to exclude several repositories.

* `--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.

# 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 \
		--include-all-repo-config --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.