From 05c7dfb002a88ac783fe268c5f9bb1df738ac502 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Thu, 28 Nov 2024 17:49:37 -0800 Subject: [PATCH] INSTALL.md, README.md: make installation instructions less "sassy" 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 --- INSTALL.md | 19 +++++++++---------- README.md | 7 ++++--- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 2e28b492..cc5515c1 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -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 @@ -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 @@ -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 diff --git a/README.md b/README.md index 1fd72ab0..f9d09153 100644 --- a/README.md +++ b/README.md @@ -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