Re: [PATCH] docs: add filter-branch note about The BFG

On 17 December 2013 18:13, Junio C Hamano [off-list ref] wrote:

Having said that, "You may want to use ..." without giving the
reason why we recommend the other tool leaves the reader wondering
what the pros and cons are, and why git-filter-branch exists if BFG
is the first thing its document recommends even before it describes
what git-filter-branch is and does.  "You may want to check ..."
might be slightly better, but probably by not that much improvement.

Rewriting "it's generally faster ..."  part to give a bit more info
to allow readers decide the pros and cons themselves may be needed.

Thanks for that feedback, it makes sense. Here's an alternative
version which gives more information on the pros and cons of each
tool, and why you might want to use either - as Jonathan suggested,
this would be for the NOTES section at the bottom of the file, where
it's less intrusive:

Notes
-----

git-filter-branch allows you to make complex shell-scripted rewrites
of your Git history, but you may not 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
properties:

* 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 can re-submit this as a patch if it's acceptable?