Skip to content

Commit

Permalink
INSTALL.md, README.md: make installation instructions less "sassy"
Browse files Browse the repository at this point in the history
The complaints about the installation instructions will never end and
I'll be fielding them until the end of time.  No install process is
too trivial for users to misunderstand and replace with ridiculously
complex alternative undocumented and completely wrong instructions;
unfortunately, venting about this reality causes other users to complain
about my venting.  It's a fair point, though, I shouldn't vent in the
official documentation.  That belongs somewhere that those users would
never look, like commit messages.  Touch up a few related items in the
documentation while at it.

Signed-off-by: Elijah Newren <newren@gmail.com>
  • Loading branch information
newren committed Nov 29, 2024
1 parent 40e3f56 commit 05c7dfb
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 13 deletions.
19 changes: 9 additions & 10 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,14 @@ If you place the git-filter-repo script in your $PATH, then you can
shorten commands by replacing `python3 git-filter-repo` with `git
filter-repo`; the manual assumes this but you can use the longer form.

If for some reason downloading a single file is too much of an
installation hassle for you, or you really want some kind of "official
installation", the other sections may have useful tips.

Optionally, if you also want to use some of the contrib scripts, then
you need to make sure you have a `git_filter_repo.py` file which is
either a link to or copy of `git-filter-repo`, and you need to place
that git_filter_repo.py file in $PYTHONPATH.

If you prefer an "official" installation over the manual installation
explained above, the other sections may have useful tips.

# Installation via Package Manager

If you want to install via some [package
Expand Down Expand Up @@ -147,7 +146,7 @@ you'll still need to do that yourself.

# Notes for Windows Users

Windows likes to make things difficult. Common and historical issues:
Sadly, Windows sometimes makes things difficult. Common and historical issues:

* **Non-functional Python stub**: Windows apparently ships with a
[non-functional
Expand All @@ -160,11 +159,11 @@ Windows likes to make things difficult. Common and historical issues:
[Python](https://docs.microsoft.com/en-us/windows/python/beginners)
from the [Microsoft
Store](https://apps.microsoft.com/store/search?publisher=Python%20Software%20Foundation)
* **Modifying PATH, making the script executable**: For some reason lots of
Windows users have a hard time modifying their PATH and/or making scripts
executable. You can skip that step by just using
`python3 git-filter-repo` instead of `git filter-repo` in your commands.
* **Different python executable name**: It seems some users don't have
* **Modifying PATH, making the script executable**: If modifying your PATH
and/or making scripts executable is difficult for you, you can skip that
step by just using `python3 git-filter-repo` instead of `git filter-repo`
in your commands.
* **Different python executable name**: Some users don't have
a `python3` executable but one named something else like `python`
or `python3.8` or whatever. You may need to edit the first line
of the git-filter-repo script to specify the appropriate path. Or
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,10 @@ filter-repo requires:

# How do I install it?

`git-filter-repo` is a single-file python script, which was done to make
installation for basic use on many systems trivial: just place that
file into your $PATH.
While the `git-filter-repo` repository has many files, the main logic
is all contained in a single-file python script named
`git-filter-repo`, which was done to make installation for basic use
on many systems trivial: just place that one file into your $PATH.

See [INSTALL.md](INSTALL.md) for things beyond basic usage or special
cases. The more involved instructions are only needed if one of the
Expand Down

0 comments on commit 05c7dfb

Please sign in to comment.