INSTALL.md: add notes about common installation issues

Signed-off-by: Elijah Newren <[email protected]>

Author: newren

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/[email protected]/)
+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