From fd64b0c7c0c2509ec7399c55128a2651a388b82c Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 11 Jun 2021 13:29:07 -0700 Subject: [PATCH] INSTALL.md: more clarifications and links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Someone was surprised by my claim that someone else had reported Microsoft provided a stub or stripped down python. Link to where it was reported in case others hit the same problem. Vilius Šumskas reported that the need to edit the shebang line has been corrected with the newest Git for Windows, so update the text to note this. It's possible other users may still have problems given the variety of Windows versions and the number of reports I had about this, so I want to still leave links there for at least a little while. Be more explicit about how pip is lame and provides virtually no benefit since it leaves you to fix your $PATH yourself, which was the only step that was needed in installing the whole package anyway. Signed-off-by: Elijah Newren --- INSTALL.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 87efe16..00aabb7 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -20,22 +20,24 @@ these versions. # Notes for Windows Users The first hurdle for Windows users is installing a functional version -of Python (it has been reported that Windows ships with a stripped -down python-like program that just doesn't work). python.org probably -has good instructions here, though many users report a preference -getting it from the [Microsoft +of Python (it has been reported that Windows ships with a [stub or +stripped down python-like program that just doesn't +work](https://github.com/newren/git-filter-repo/issues/36#issuecomment-568933825)). +python.org probably has good instructions here, though many users +report a preference getting it from the [Microsoft Store](https://docs.microsoft.com/en-us/windows/python/beginners) and seem to be successful with that (particularly since [msys2 issue #27](https://github.com/msys2/msys2-runtime/pull/27) was fixed by the Git for Windows maintainer). -Several users also needed to modify the first line of the -git-filter-repo script to change paths, especially if installing -git-filter-repo using the pip method instead of Scoop, and +In the past, several users also needed to modify the first line of the +git-filter-repo script to change the python path, particularly when +installing git-filter-repo using the pip method instead of Scoop, and particularly with older versions of Git for Windows (anything less than 2.32.0.windows.1) as GitBash had an unfortunate shebang length limitation (see [git-for-windows issue -#3165](https://github.com/git-for-windows/git/pull/3165)). +#3165](https://github.com/git-for-windows/git/pull/3165)). Hopefully, +this isn't needed anymore. For additional details (if needed, though be aware these might not be accurate anymore given both git-for-windows and git-filter-repo @@ -124,17 +126,20 @@ So, installation might look something like the following: # Installation via [pip](https://pip.pypa.io/) -For those who prefer to install python packages via pip, you merely need -to run: +This method is NOT recommended, because [installing via pip does not +place the package in your +$PATH](https://stackoverflow.com/questions/35898734/pip-installs-packages-successfully-but-executables-not-found-from-command-line). +If you go this route, you have to copy the file into an appropriate +directory (either `git --exec-path` or something else in $PATH), or +modify your $PATH to include the directory where pip places things, +but you could have just done that after cloning filter-repo directly +so this installation method provides virtually no benefit. + +However, some people still prefer installing this way. If you are +one of them, you can use: $ pip3 install git-filter-repo -However, the place where pip places that package might not be in your -$PATH (thus requiring you to manually update your $PATH afterwards), -and on windows the pip install might not take care of python-specific -issues for you (see "Notes for Windows Users", above). As such, -installation via package managers is recommended instead. - # Installation via Makefile