git-annex-filter-branch(1)

✨ git-annex-filter-branch ✨

okay so bestie, this is git-annex-filter-branch from the General Commands Manual section of the git-annex fam 💖 — it's the picky-eater version of your git-annex branch. Like, it only takes the bites you tell it to.

---

🌸 NAME 🌸

git-annex-filter-branch — filter information from the git-annex branch

---

🎀 SYNOPSIS 🎀

git annex filter-branch [...]

---

🦋 DESCRIPTION 🦋

So what this does: it copies selected info from the git-annex branch into a git commit object, and then it spits out that commit's hash. That git commit can be transported to another git repository, and given a branch name like "foo/git-annex", and over there git-annex will automatically merge it into its own git-annex branch. Basically it lets you publish some of your git-annex branch info without publishing the whole entire thing. no cap 🔥

Other ways to avoid publishing info from a git-annex branch, or to remove info 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 one gives you full control for those who need it. main character energy 👑

With no options at all, no information at all will be included from the git-annex branch. You use options to specify what to include. And good news: all options can be specified multiple times. 💅

When the repository contains information about a private repository (because annex.private is set, or because git-annex initremote --private was used), that private information will be included when it's 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 gets included when the information for foo is included, and excluded when foo is excluded. besties stick together fr fr 🫶

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, so that it doesn't get garbage collected by git gc. Those trees are not included when filtering the git-annex branch. Usually that won't 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. everything. the whole vibe. 🌈
• --include-key-information-for=repo — when including information about a key, also 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 🌈

🍓 splitting a subdir out

You have a big git-annex repository and you're 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. ⭐

💜 sharing key info but not remote config

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>

---

okay that's the whole thing, you're literally a git-annex branch surgeon now, slay 💅✨ this came from the git-annex General Commands Manual, page git-annex-filter-branch(1), so if you forget anything just yell for the manpage again bestie 🫶🎀🦋