Roberto Tyley [off-list ref] writes:
* The BFG takes advantage of multi-core machines, cleaning commit
file-trees in parallel, which git-filter-branch currently does not do.
* Any particular version of a file is cleaned exactly _once_. The BFG,
unlike git-filter-branch, does not give you the opportunity to handle
a file differently based on where or when it was committed within your
history.
* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command-set]
is much more restrictive than git-filter branch, and dedicated just to
the tasks of removing unwanted data - e.g. `--strip-blobs-bigger-than
1M`.
I do not know offhand if the above formats well with AsciiDoc. You
may have to do it like this:
* The first line of the bulletted paragraph is
followed by the second and subsequent lines indented
to align with the first one.
The first bullet point may be somewhat misleading, though. Nothing
stops your script you use in filter-branch from processing blobs
belonging to a single tree in parallel---the user just needs to do a
bit more work to do so.
I think the second point is the most characteristic in BFG (and that
is what allows easy parallelization of the filtering). Also, it
cannot be stressed enough that the "removing unwanted contents" use
case can take advantage of the "bad contents in a blob is bad, no
matter where in the tree and when in the history the blob appears".
That is what makes BFG particularly shine for the use case. Its
design very much aligns the objective the use case wants to achieve.
On 18 December 2013 05:57, Junio C Hamano [off-list ref] wrote:
The first bullet point may be somewhat misleading, though. Nothing
stops your script you use in filter-branch from processing blobs
belonging to a single tree in parallel---the user just needs to do a
bit more work to do so.
Thanks, I've moved this entry down and clarified the capabilities -
I think there's quite a big difference to the user (of a multi-core
machine) as to whether parallelism happens by default, or whether they
have to work out how to introduce it into the operation they're trying
to perform.
I think the second point is the most characteristic in BFG (and that
is what allows easy parallelization of the filtering). Also, it
cannot be stressed enough that the "removing unwanted contents" use
case can take advantage of the "bad contents in a blob is bad, no
matter where in the tree and when in the history the blob appears".
That is what makes BFG particularly shine for the use case. Its
design very much aligns the objective the use case wants to achieve.
I've moved this up to the first bullet-point and added text emphasising
the significance the constraint plays in making the BFG work quickly
while satisfying the common use-case.
Roberto Tyley (1):
docs: add filter-branch notes on The BFG
Documentation/git-filter-branch.txt | 33 ++++++++++++++++++++++++++++++++-
1 file changed, 32 insertions(+), 1 deletion(-)
--
1.8.3.4 (Apple Git-47)
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
here:
* speed : The BFG is 10-50x faster
http://rtyley.github.io/bfg-repo-cleaner/#speed
* complexity of configuration : filter-branch is a very flexible tool,
but demands very careful usage in order to get the desired results
http://rtyley.github.io/bfg-repo-cleaner/#examples
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:
http://rtyley.github.io/bfg-repo-cleaner/#feedback
Signed-off-by: Roberto Tyley <redacted>
---
Documentation/git-filter-branch.txt | 33 ++++++++++++++++++++++++++++++++-
1 file changed, 32 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index e4c8e82..2eba627 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -393,7 +393,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 +429,37 @@ warned.
(or if your git-gc is not new enough to support arguments to
`--prune`, use `git repack -ad; git prune` instead).
+Notes
+-----
+
+git-filter-branch allows you to make complex shell-scripted rewrites
+of your Git history, but you probably don't need this flexibility if
+you're simply _removing unwanted data_ like large files or passwords.
+For those operations you may want to consider
+link:http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],
+a JVM-based alternative to git-filter-branch, typically at least
+10-50x faster for those use-cases, and with quite different
+characteristics:
+
+* Any particular version of a file is cleaned exactly _once_. The BFG,
+ unlike git-filter-branch, does not give you the opportunity to
+ handle a file differently based on where or when it was committed
+ within your history. This constraint gives the core performance
+ benefit of The BFG, and is well-suited to the task of cleansing bad
+ data - you don't care _where_ the bad data is, you just want it
+ _gone_.
+
+* By default The BFG takes full advantage of multi-core machines,
+ cleansing commit file-trees in parallel. git-filter-branch cleans
+ commits sequentially (ie in a single-threaded manner), though it
+ _is_ possible to write filters that include their own parallellism,
+ in the scripts executed against each commit.
+
+* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]
+ are much more restrictive than git-filter branch, and dedicated just
+ to the tasks of removing unwanted data- e.g:
+ `--strip-blobs-bigger-than 1M`.
+
GIT
---
Part of the linkgit:git[1] suite
--
1.8.3.4 (Apple Git-47)