git-for-windows · dscho · Feb 22, 2019 · Feb 25, 2019 · Mar 16, 2019 · Mar 16, 2019
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -39,8 +39,8 @@ When running `make`, you can use `-j$(nproc)` to automatically use the number of
 on your machine as the number of concurrent build processes.
 
 You can go deeper on the Windows-specific build process by reading the
-[technical overview](https://github.com/git-for-windows/git/wiki/Technical-overview) or the
-[guide to compiling Git with Visual Studio](https://github.com/git-for-windows/git/wiki/Compiling-Git-with-Visual-Studio).
+[technical overview](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Technical-overview.md) or the
+[guide to compiling Git with Visual Studio](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Compiling-Git-with-Visual-Studio.md).
 
 ## Building `git` on Windows with Visual Studio
 
@@ -120,7 +120,7 @@ you want to extend the functional tests to be sure no one breaks your feature in
 ### Functional Tests
 
 Navigate to the `t/` directory and type `make` to run all tests or use `prove` as
-[described in the Git for Windows wiki](https://github.com/git-for-windows/git/wiki/Building-Git):
+[described in the Git for Windows wiki](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Building-Git.md):
 
 ```
 prove -j12 --state=failed,save ./t[0-9]*.sh

diff --git a/Documentation/git-for-windows/0.-Index.md b/Documentation/git-for-windows/0.-Index.md
@@ -0,0 +1,51 @@
+This is for the poor souls in corporate IE environments who can't expand the page list.
+
+* [Home](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Home.md)
+* [32 bit issues](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/32-bit-issues.md)
+* [Adding regression tests](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Adding-regression-tests.md)
+* [Auto launching ssh agent when git starts](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Auto-launching-ssh-agent-when-git-starts.md)
+* [Building Git](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Building-Git.md)
+* [Building msys2 runtime](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Building-msys2-runtime.md)
+* [Building new package versions](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Building-new-package-versions.md)
+* [Compiling Git with Visual Studio](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Compiling-Git-with-Visual-Studio.md)
+* [Contact](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Contact.md)
+* [Continuous Integration (CI)](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Continuous-Integration-%28CI%29.md)
+* [Debugging Git](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Debugging-Git.md)
+* [Diagnosing performance issues](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Diagnosing-performance-issues.md)
+* [exec() semantics](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Windows-vs-Linux-fork%28%29/exec%28%29-semantics.md)
+* [FAQ](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/FAQ.md)
+* [File names, Branch names, Path quotation, Executable bit and file modes, core.FileMode](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/File-names,-Branch-names,-Path-quotation,-Executable-bit-and-file-modes,-core.FileMode.md)
+* [Git cannot create a file or directory with a long path](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Git-cannot-create-a-file-or-directory-with-a-long-path.md)
+* [Git-for-Windows' "snapshots"](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Snapshot-builds.md)
+* [Good commits](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Good-commits.md)
+* [How to participate](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/How-to-participate.md)
+* [Install inside MSYS2 proper](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Install-inside-MSYS2-proper.md)
+* [Install or update inside MSYS2, Cygwin or Git-for-windows itself](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Install-or-update-inside-MSYS2,-Cygwin-or-Git-for-windows-itself.md)
+* [Issue reporting guidelines](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Issue-reporting-guidelines.md)
+* [Making a portable Git](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Making-a-portable-Git.md)
+* [Making an installer](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Making-an-installer.md)
+* [Mapping between Git Installer GUI Settings And Command Line Arguments](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Mapping-between-Git-Installer-GUI-Settings-And-Command-Line-Arguments.md)
+* [Merge Conflicts Resolving and Remembering them](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Merge-Conflicts---Resolving-and-Remembering-them.md)
+* [MinGit is Git for Windows Applications](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/MinGit.md)
+* [MSYS2 Notes](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/MSYS2-Notes.md)
+* [OpenSSH Integration with Pageant](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/OpenSSH-Integration-with-Pageant.md)
+* [Package management](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Package-management.md)
+* [Performance profiling with Visual Studio](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Performance-profiling-with-Visual-Studio.md)
+* [Rebasing Git for Windows](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Rebasing-Git-for-Windows.md)
+* [Release Hashes](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Release-Hashes.md)
+* [Running Git's regression tests](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Running-Git%27s-regression-tests.md)
+* [Setting your Core.Editor (e.g. Notepad++)](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Setting-your-Core.Editor-%28e.g.-Notepad-Plus-Plus%29.md)
+* [Silent or Unattended Installation](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Silent-or-Unattended-Installation.md)
+* [Sourcetrail code viewer and linkage to Visual Studio, for Git](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Sourcetrail-code-viewer-and-linkage-to-Visual-Studio,-for-Git.md)
+* [Symbolic Links](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Symbolic-Links.md)
+* [Technical overview](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Technical-overview.md)
+* [The "Git-wrapper"](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Git-wrapper.md)
+* [The difference between MINGW and MSYS2](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/The-difference-between-MINGW-and-MSYS2.md)
+* [Updating your SDK](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Updating-your-SDK.md)
+* [Upgrading the 'perl' component to a new version](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Upgrading-the-%60perl%60-component-to-a-new-version.md)
+* [Using sshd to host a git server](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Using-sshd-to-host-a-git-server.md)
+* [Vagrant](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Vagrant.md)
+* [Visual Studio and MSVC compilation](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Visual-Studio-and-MSVC-compilation.md)
+* [Zip Archives extracting the released archives](https://github.com/git-for-windows/git/blob/HEAD/Documentation/git-for-windows/Zip-Archives---extracting-the-released-archives.md)
+
+-Fin-
diff --git a/Documentation/git-for-windows/32-bit-issues.md b/Documentation/git-for-windows/32-bit-issues.md
@@ -0,0 +1,87 @@
+# What is the problem with running Git for Windows in 32-bit mode?
+
+Note that typically, there is no problem because the solution described [here](#adjusting-msys-20dlls-address-range-manually) is executed preventively upon installation of Git for Windows.
+
+The problem only resurfaces if a `.dll` has been installed *after* Git for Windows' installation and only if that `.dll` [interferes with the address range hard-coded into the MSYS2 runtime](#background).
+
+The simplest solution to fix that problem if it rears its ugly head at all is to switch to the 64-bit version of Git for Windows (the 64-bit address range is so large that MSYS2's runtime virtually never has any run-in with another `.dll`).
+
+The second-simplest solution is to [reinstall Git for Windows](#reinstall-git-for-windows).
+
+# Background
+
+Git for Windows is not just a version of Git compiled and packaged for yet another Operating System. Many parts of Git are written in script languages (e.g. POSIX shell or Perl) and therefore Git for Windows has to bundle such script interpreters as well. In particular `bash.exe` (which is used by Git for Windows to execute POSIX shell scripts) expects a POSIX environment which is not available on Windows. The Git for Windows project uses [MSYS2](https://msys2.github.io/) (essentially a [portable](https://en.wikipedia.org/wiki/Portable_application) version of [Cygwin](https://cygwin.com/)) to provide the POSIX emulation layer.
+
+## The problem with `fork()`
+
+One of the most crucial POSIX calls expected by Bash is the `fork()` call. It starts a new process, inheriting the current process' memory contents, file descriptors and other resources. And it has no equivalent in the Win32 API (`fork()`'s closest Win32 relative is `CreateProcess()` which spawns a new process, inheriting nothing at all by default).
+
+To make it possible to emulate `fork()`, Cygwin -- and therefore MSYS2 -- needs to make certain assumptions about its core ("runtime") library called `cygwin1.dll` -- or `msys-2.0.dll`. In particular, it needs to pin it to a known address range to detect in child processes that there is a parent process already, and to copy the relevant data from there.
+
+That works very well. Until another `.dll` has been loaded into memory already, into a location that interferes with the hard-coded address range of the runtime. It is unfortunately not possible to catch that problem in a user-friendly way because there is no Win32 API call that can ask "has this address range been used by this and that `.dll`?".
+
+## The symptom of an address range that needs adjusting
+
+When there is already a `.dll` interfering with MSYS2's runtime's hard-coded address range, the user will be greeted by this error message when calling Bash :
+
+```
+> sh.exe
+      0 [main] sh.exe" 17588 handle_exceptions: Exception: STATUS_ACCESS_VIOLATION
+    865 [main] sh.exe" 17588 open_stackdumpfile: Dumping stack trace to sh.exe.stackdump
+```
+
+# Solutions
+
+There are several ways how to get out of this problem:
+
+## Upgrade to the 64-bit version of Git for Windows
+
+The address range available in 64-bit Windows is so large as to virtually guarantee that the address range of the MSYS2 runtime never has to be adjusted. This is by far the easiest solution, now that Git for Windows 2.x offers a 64-bit version.
+
+## Reinstall Git for Windows
+
+If you cannot switch to 64-bit for any reason, reinstalling Git for Windows will typically fix the problem because it [adjusts the address range preemptively](#adjusting-msys-20dlls-address-range-manually).
+
+## Adjusting `msys-2.0.dll`'s address range manually
+
+To fix the problem of address range overlaps, MSYS2 offers a utility called `rebase.exe` (which confusingly has nothing at all to do with `git rebase`) to adjust the address range of a given set of `.dll` files.
+
+Unfortunately the [symptom](#the-symptom-of-an-address-range-that-needs-adjusting) occurs not all that rarely, therefore there is even a script to make `rebase.exe` more convenient to use: `/usr/bin/rebaseall`. This script is meant to be executed via Dash instead of Bash, to avoid chicken-and-egg problems with Bash not being able to run properly unless the address range is already fixed. Typically it is unnecessary to run this script manually because it is run as part of Git for Windows' installation process. If the [symptom](#the-symptom-of-an-address-range-that-needs-adjusting) occurs at some stage long after Git for Windows was installed, reinstalling Git for Windows is the most convenient way to fix it.
+
+If you still insist on fixing it manually, please understand that this is *not* recommended without knowledge of MSYS2 internals (read: if you get stuck, please do not open a ticket to learn more about MSYS2; use the recommended way instead: reinstall Git for Windows). The manual way goes like this:
+
+1. close each and every `mintty` window
+2. terminate each and every Bash
+3. terminate even background processes that use the MSYS2 runtime, such as `ssh-agent`
+4. open `cmd.exe`, change the directory to Git's top-level one and then run
+
+   ```cmd
+   usr\bin\dash -c '/usr/bin/dash /usr/bin/rebaseall -p'
+   ```
+
+In the case that the MSYS2 runtime needs to be rebased, too, you will need to call something like this:
+
+```cmd
+copy usr\bin\msys-2.0.dll copy-msys-2.0.dll
+usr\bin\rebase.exe -b 0x67000000 copy-msys-2.0.dll
+copy copy-msys-2.0.dll usr\bin\msys-2.0.dll
+usr\bin\dash.exe  -c 'cd / && /usr/bin/dash.exe /usr/bin/rebaseall'
+```
+
+These commands need to be executed in the top-level directory, and the address (0x67000000) might need to be adjusted.
+
+# What's with this `Cwd.dll` problem?
+
+Under some circumstances, `/usr/bin/rebaseall` seems not to rebase the Perl `.dll` files "enough", and the symptom is something like this:
+
+```
+      1 [main] perl 297 child_info_fork::abort: address space needed by 'Cwd.dll' (0x1D0000) is already occupied
+```
+
+A work-around that appears to help in most of those cases is to call
+
+```sh
+/usr/bin/rebase -b 0x63070000 /usr/lib/perl5/core_perl/auto/*/{*,*/*}.dll
+```
+
+Your mileage may vary: it might be necessary to play with the base address a bit.
diff --git a/Documentation/git-for-windows/Adding-regression-tests.md b/Documentation/git-for-windows/Adding-regression-tests.md
@@ -0,0 +1,44 @@
+Git comes with an extensive regression test suite. It lives in the [`t/` subdirectory](https://github.com/git/git/tree/HEAD/t) of the source code repository and is organized into test scripts, e.g. `t8002-blame.sh`, which contain multiple test cases. The test scripts themselves are shell scripts.
+
+The best documentation how to add tests is the test suite itself, by example.
+
+# Adding test cases
+
+You will want to add test cases either to demonstrate bugs, or to ensure that certain operations work as expected (e.g. when you just implemented such an operation or fixed a bug).
+
+In the most common case, you will want to add your test case to an existing test script. Use the file name and `git grep`'s output as an indicator which script is the best one to which to add your test case.
+
+Each test case is written in the form
+
+```sh
+test_expect_success 'title' '
+    # Here come the shell script statements
+'
+```
+
+If you want to demonstrate a breakage, use `test_expect_failure` instead, and write the rest of the test case as if the bug was fixed, i.e. the way you want to see it succeed.
+
+Inside the script part, you need to connect everything into an ‘&&’ chain, i.e.
+
+```sh
+    test_commit this-will-write-a-file-and-commit &&
+    echo New file >new-file.txt &&
+    git status --porcelain --verbose --verbose >output &&
+    grep new-file.txt output
+```
+
+If you need to test anything Windows-specific, you can put `MINGW` before the case’s title, as a prerequisite. Likewise, you can use `!MINGW` to test only on non-Windows.
+
+Every script creates a test repository with a test working tree in a new directory called `t/trash directory.<basename>`, e.g. `t/trash directory.t8002-blame/`.
+
+Traditionally, the first “test case” is the setup, where you set up files and commits common to multiple test cases in the same script.
+
+There are a bunch of really useful functions for use in test scripts, e.g. `test_commit`, which not only abbreviates the common “write a file, add it, commit it, tag the commit” stanza, but also increments the timestamp from a fixed first timestamp, so that the commits are reproducible (read: so you can reliably debug even if the bug depends on some side effect of some compression or some such). You will find a comprehensive list in [`t/README`](https://github.com/git/git/blob/HEAD/t/README) under the “Test harness library” heading.
+
+There are also a bunch of useful test helpers in `t/helper/` (automatically added to the `PATH`) e.g. `test-chmtime`. If you need to test native functions, you can introduce a new test helper, or piggy-back onto an existing one.
+
+As you will most likely add a test case to an existing script, you can use whatever the test repository’s current state is. To find out, just run the script with the `-d` option, which will leave the trash directory behind instead of removing it after a successful conclusion of the script: `cd t && sh t8002-blame.sh -d`.
+
+In addition to `-d`, I found the options `-i` (stop upon first failing test case), `-x` (show the tests’ commands before they are executed) and `-v` (show the entire output instead of suppressing it) useful.
+
+If you want to use `-x`, it is best to run through bash instead of sh, as some tests require a bash feature where the trace is printed to a different file descriptor than stderr, although in Git for Windows’ SDK, sh still refers to bash, so it is the same.
diff --git a/Documentation/git-for-windows/Auto-launching-ssh-agent-when-git-starts.md b/Documentation/git-for-windows/Auto-launching-ssh-agent-when-git-starts.md
@@ -0,0 +1,32 @@
+If you want your passphrase to be 'remembered' for a session (or configurable timeout period) you will need to setup an ssh-agent process to handle this key.
+
+Recent versions of git for windows 2.x come with an ssh agent startup script and the installer also checks if an ssh agent is currently running and asks you to kill this process.
+
+Run the ssh agent:
+
+    start-ssh-agent.cmd
+
+This should work both in a `cmd` and `bash` shell and can be included in `~/.profile` or `~/.bashrc`.
+
+The [GitHub instructions](https://help.github.com/articles/working-with-ssh-key-passphrases/#auto-launching-ssh-agent-on-msysgit) are still valid but not needed anymore.
+
+## Manually
+
+To launch, put in `~/.profile` or `~/.bashrc`:
+
+```bash
+# ssh-agent auto-launch (0 = agent running with key; 1 = w/o key; 2 = not run.)
+agent_run_state=$(ssh-add -l >| /dev/null 2>&1; echo $?)
+if   [ $agent_run_state = 2 ]; then
+  eval $(ssh-agent -s)
+  ssh-add ~/.ssh/id_rsa
+elif [ $agent_run_state = 1 ]; then
+  ssh-add ~/.ssh/id_rsa
+fi
+```
+
+To close on shell exit, put in `~/.bash_logout`:
+
+```bash
+ssh-agent -k
+```