From 74ea810872b41331ffdbf02cdc2d474c98b88514 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Mon, 19 Oct 2020 08:08:30 -0700 Subject: [PATCH] INSTALL.md: add notes about common installation issues Signed-off-by: Elijah Newren --- INSTALL.md | 47 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 7704f58..8e6791e 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -17,6 +17,19 @@ no interest in doing so); https://repology.org tracks who packages these versions. +# Notes for Windows Users + +It seems that the default python on Windows is not fully functional, +and windows might not allow executing python scripts by default. See +[issue 124](https://github.com/newren/git-filter-repo/issues/124), +[issue 36](https://github.com/newren/git-filter-repo/issues/36), and +[this git mailing list +thread](https://lore.kernel.org/git/nycvar.QRO.7.76.6.2004251610300.18039@tvgsbejvaqbjf.bet/) +for details and workarounds. I believe that Windows users installing +git-filter-repo via Scoop will be okay, but those using a manual +installation or pip install may run into these issues. + + # Manual Installation filter-repo only consists of a few files that need to be installed: @@ -70,14 +83,26 @@ filter-repo only consists of a few files that need to be installed: instructions regardless of whether the html version of help is installed. -So, installation might look something like -``` -cp -a git-filter-repo $(git --exec-path) -cp -a git-filter-repo.1 $(git --man-path)/man1 -cp -a git-filter-repo.html $(git --html-path) -ln -s $(git --exec-path)/git-filter-repo \ - $(python -c "import site; print(site.getsitepackages()[-1])")/git_filter_repo.py -``` +So, installation might look something like the following: + +1. If you don't have the necessary documentation files (because you + are installing from a clone of filter-repo instead of from a + tarball) then you can first run: + + `make snag_docs` + + (which just copies the generated documentation files from the + `docs` branch) + +2. Run the following + + ``` + cp -a git-filter-repo $(git --exec-path) + cp -a git-filter-repo.1 $(git --man-path)/man1 + cp -a git-filter-repo.html $(git --html-path) + ln -s $(git --exec-path)/git-filter-repo \ + $(python -c "import site; print(site.getsitepackages()[-1])")/git_filter_repo.py + ``` # Installation via [pip](https://pip.pypa.io/) @@ -86,6 +111,12 @@ to run: $ 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