On 17 December 2013 18:13, Junio C Hamano <gits...@pobox.com> 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? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html