The BFG is a tool specifically designed for the task of removing
unwanted data from Git repository history - a common use-case for which
git-filter-branch has been the traditional workhorse.

It's beneficial to let users know that filter-branch has an alternative

* speed : The BFG is 10-50x faster
* complexity of configuration : filter-branch is a very flexible tool,
  but demands very careful usage in order to get the desired results

Obviously, filter-branch has it's advantages too - it permits very
complex rewrites, and doesn't require a JVM - but for the common
use-case of deleting unwanted data, it's helpful to users to be aware
that an alternative exists.

The BFG was released under the GPL in February 2013, and has since seen
widespread production use (The Guardian, RedHat, Google, UK Government
Digital Service), been tested against large repos (~300K commits, ~5GB
packfiles) and received significant positive feedback from users:

Signed-off-by: Roberto Tyley <>
 Documentation/git-filter-branch.txt | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-filter-branch.txt 
index e4c8e82..918e965 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -18,6 +18,12 @@ SYNOPSIS
+NOTE: For simply removing unwanted data from repository history, you may
+want to use link:[The BFG 
+instead - it's generally faster and simpler for eliminating large files
+or private data.
 Lets you rewrite Git revision history by rewriting the branches mentioned
 in the <rev-list options>, applying custom filters on each revision.
 Those filters can modify each tree (e.g. removing a file or running
@@ -393,7 +399,7 @@ git filter-branch --index-filter \
 Checklist for Shrinking a Repository
-git-filter-branch is often used to get rid of a subset of files,
+git-filter-branch can be used to get rid of a subset of files,
 usually with some combination of `--index-filter` and
 `--subdirectory-filter`.  People expect the resulting repository to
 be smaller than the original, but you need a few more steps to
@@ -429,6 +435,12 @@ warned.
   (or if your git-gc is not new enough to support arguments to
   `--prune`, use `git repack -ad; git prune` instead).
+link:[The BFG Repo-Cleaner]
+- a tool specifically designed for removing unwanted data from Git
+repository history.
 Part of the linkgit:git[1] suite
-- (Apple Git-47)

To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to
More majordomo info at

Reply via email to