@matheusbsbs / matheus-bagliano / commits / 615b8f1a8d

docs: add filter-branch notes on The BFG

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 <roberto.tyley@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Roberto Tyley committed Dec 18, 2013 at 14:25 UTC 615b8f1a8d41e6c27f308e74eacb5ef9e99a26af
1 file changed +32 -1
Documentation/git-filter-branch.txt
+32 -1
@@ -393,7 +393,7 @@ git filter-branch --index-filter \
393 Checklist for Shrinking a Repository
394 ------------------------------------
395
396 -git-filter-branch is often used to get rid of a subset of files,
396 +git-filter-branch can be used to get rid of a subset of files,
397 usually with some combination of `--index-filter` and
398 `--subdirectory-filter`. People expect the resulting repository to
399 be smaller than the original, but you need a few more steps to
@@ -429,6 +429,37 @@ warned.
429 (or if your git-gc is not new enough to support arguments to
430 `--prune`, use `git repack -ad; git prune` instead).
431
432 +Notes
433 +-----
434 +
435 +git-filter-branch allows you to make complex shell-scripted rewrites
436 +of your Git history, but you probably don't need this flexibility if
437 +you're simply _removing unwanted data_ like large files or passwords.
438 +For those operations you may want to consider
439 +link:http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],
440 +a JVM-based alternative to git-filter-branch, typically at least
441 +10-50x faster for those use-cases, and with quite different
442 +characteristics:
443 +
444 +* Any particular version of a file is cleaned exactly _once_. The BFG,
445 + unlike git-filter-branch, does not give you the opportunity to
446 + handle a file differently based on where or when it was committed
447 + within your history. This constraint gives the core performance
448 + benefit of The BFG, and is well-suited to the task of cleansing bad
449 + data - you don't care _where_ the bad data is, you just want it
450 + _gone_.
451 +
452 +* By default The BFG takes full advantage of multi-core machines,
453 + cleansing commit file-trees in parallel. git-filter-branch cleans
454 + commits sequentially (ie in a single-threaded manner), though it
455 + _is_ possible to write filters that include their own parallellism,
456 + in the scripts executed against each commit.
457 +
458 +* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]
459 + are much more restrictive than git-filter branch, and dedicated just
460 + to the tasks of removing unwanted data- e.g:
461 + `--strip-blobs-bigger-than 1M`.
462 +
463 GIT
464 ---
465 Part of the linkgit:git[1] suite