@ -44,40 +44,44 @@ filter-repo requires:
# How do I install it?
# How do I install it?
git-filter-repo is a single-file python script, which was done to make
` git-filter-repo` is a single-file python script, which was done to make
installation for basic use on many systems trivial: just place the
installation for basic use on many systems trivial: just place that
script into your $PATH.
file into your $PATH.
See [INSTALL.md ](INSTALL.md ) for things beyond basic usage or special
See [INSTALL.md ](INSTALL.md ) for things beyond basic usage or special
cases. The more involved instructions are only needed if you
cases. The more involved instructions are only needed if one of the
following apply:
* are working with a python3 executable named something other than "python3"
* want to install documentation (beyond the builtin docs shown with -h)
* you do not find the above comment about trivial installation intuitively
* want to run some of the [contrib ](contrib/filter-repo-demos/ ) examples
obvious
* want to create your own python filtering scripts using filter-repo as a
* you are working with a python3 executable named something other than
module/library
"python3"
* you want to install documentation (beyond the builtin docs shown with -h)
* you want to run some of the [contrib ](contrib/filter-repo-demos/ ) examples
* you want to create your own python filtering scripts using filter-repo as
a module/library
# How do I use it?
# How do I use it?
See the [user
For comprehensive documentation:
manual](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html).
* see the [user manual ](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html )
* alternative formating of the user manual is available on various
external sites
([example](https://www.mankier.com/1/git-filter-repo)), for those
that don't like the htmlpreview.github.io layout, though it may
only be up-to-date as of the latest release
If you prefer learning from examples:
If you prefer learning from examples:
* the [simple example ](#simple-example-with-comparisons ) below may
be of interest
* the user manual has an extensive [examples
section](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES)
* there is a [cheat sheet for converting filter-branch
* there is a [cheat sheet for converting filter-branch
commands](Documentation/converting-from-filter-branch.md#cheat-sheet-conversion-of-examples-from-the-filter-branch-manpage),
commands](Documentation/converting-from-filter-branch.md#cheat-sheet-conversion-of-examples-from-the-filter-branch-manpage),
which covers every example from the filter-branch manual
which covers every example from the filter-branch manual
* there is a [cheat sheet for converting BFG Repo Cleaner
* there is a [cheat sheet for converting BFG Repo Cleaner
commands](Documentation/converting-from-bfg-repo-cleaner.md#cheat-sheet-conversion-of-examples-from-bfg),
commands](Documentation/converting-from-bfg-repo-cleaner.md#cheat-sheet-conversion-of-examples-from-bfg),
which covers every example from the BFG website
which covers every example from the BFG website
* the [simple example ](#simple-example-with-comparisons ) below may
External sites also have [alternative formats of the user
be of interest
manual](https://www.mankier.com/1/git-filter-repo) available, at least
* the user manual has an extensive [examples
for the most recent release. This also may be beneficial if
section](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES)
htmlpreview.github.io starts hitting load limits.
# Why filter-repo instead of other alternatives?
# Why filter-repo instead of other alternatives?
@ -304,9 +308,9 @@ But this comes with some nasty caveats and limitations:
# Design rationale behind filter-repo
# Design rationale behind filter-repo
None of the existing repository filtering tools did what I wanted;
None of the existing repository filtering tools did what I wanted;
they all came up short for my needs. No tool provided any of the
they all came up short for my needs. No tool provided any of the
first eight traits below I wanted, and all failed to provide at least
first eight traits below I wanted, and no tool provided more than
one of the last four traits as well :
two of the last four traits either :
1. [Starting report] Provide user an analysis of their repo to help
1. [Starting report] Provide user an analysis of their repo to help
them get started on what to prune or rename, instead of expecting
them get started on what to prune or rename, instead of expecting