development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-08-28 12:09:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add filter-branch notes on The BFG

Browse source 
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>
This commit is contained in:
Roberto Tyley 2013-12-18 14:25:16 +00:00 committed by Junio C Hamano
parent 2f93541d88
commit 615b8f1a8d
1 changed files with 32 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
Documentation/git-filter-branch.txt
View file

@ -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