Merge pull request #59 from dscho/merge-g4w-wiki

Migrate the wiki pages

Author: dscho

assets/sass/style.scss

@@ -2,10 +2,6 @@ html {
 	font: 16px/1 'Open Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
 }
 
-li a {
-	font-size: .875em;
-}
-
 a {
 	color: #4B8CD2;
 	text-decoration: none;
@@ -247,7 +243,7 @@ div.version {
 	margin-top: 0;
 }
 
-.details p a:not(.button) {
+.details a:not(.button) {
 	color: #A3CFFF;
 	text-decoration: underline;
 }
@@ -307,6 +303,10 @@ div.version {
 	text-shadow: 0 -1px rgba(0, 0, 0, 0.35);
 }
 
+.details :is(h3, h4, p) + p {
+	margin-top: 1em;
+}
+
 .details .vcentercontainer:first-child {
 	margin-right: 5%;
 }
@@ -356,9 +356,25 @@ body.page {
 		text-align: center;
 	}
 
-	article p,h3,ul {
+	article > :not(h1, h2),h3,ul {
 		margin-left: auto;
 		margin-right: auto;
 		width: 65%;
 	}
 }
+.markdown-important::before {
+	content:url('img/important.svg');
+	padding-left: 0.6em;
+	padding-right: 0.2em;
+}
+.markdown-important {
+	border-left: .25em solid #f34f29;
+}
+.anchor {
+	transform: translateX(-80%) scale(.6);
+	position: absolute;
+}
+
+:is(h1, h2, h3, h4):not(:hover) .anchor {
+	display: none;
+}

content/_index.md

@@ -56,7 +56,7 @@ Simply right-click on a folder in Windows Explorer to access the BASH or GUI.
 <div class="vcentercontainer detailstext">
 <div>
 
-As an open source project, Git for Windows benefits greatly from both the volunteer work of helpful developers and [good bug reports](https://github.com/git-for-windows/git/wiki/Issue-reporting-guidelines) made by Git for Windows' users.
+As an open source project, Git for Windows benefits greatly from both the volunteer work of helpful developers and [good bug reports](./issue-reporting-guidelines.html) made by Git for Windows' users.
 
 ### Governance Model
 
@@ -72,7 +72,7 @@ If you've noticed a bug or simply have an idea that you'd like to see become rea
 
 The _Git for Windows SDK_ is a build environment that includes all the tools necessary for developers who want to contribute by writing code for Git for Windows.
 
-Please look at the [technical overview](https://github.com/git-for-windows/git/wiki/Technical-overview) of the Git for Windows packaging and how to include your changes in your own custom installer.
+Please look at the [technical overview](./technical-overview.html) of the Git for Windows packaging and how to include your changes in your own custom installer.
 
 <a name="download-sdk" /><a class="button" href="https://github.com/git-for-windows/build-extra/releases/latest" target="_blank">Download <span class="gittext">Git for Windows SDK</span></a>
 

content/adding-regression-tests.md

@@ -0,0 +1,49 @@
+---
+title: "Adding regression tests"
+aliases:
+  - "Adding-regression-tests"
+---
+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.

content/auto-launching-ssh-agent-when-git-starts.md

@@ -0,0 +1,37 @@
+---
+title: "Auto launching ssh agent when git starts"
+aliases:
+  - "Auto-launching-ssh-agent-when-git-starts"
+---
+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
+```

content/backporting-upstream-git-patches.md

@@ -0,0 +1,63 @@
+---
+title: "Backporting upstream Git patches"
+aliases:
+  - "Backporting-upstream-Git-patches"
+---
+# How to backport a patch (series) that was contributed to upstream Git
+
+Git for Windows' [release cadence](https://github.com/git-for-windows/git/security/policy#supported-versions) closely follows the [release cycle of the "upstream" Git project](https://tinyurl.com/gitcal).
+
+Sometimes patches that already made it into upstream Git, but that have not been released as part of an official version, are important enough for Git for Windows that they need to be "backported", i.e. they to be integrated into Git for Windows' `main` branch.
+
+Contributions to the upstream Git project [are only accepted in the form of patches or patch series sent via mail to the Git mailing list](https://git-scm.com/docs/SubmittingPatches#send-patches). This makes backporting them a bit more challenging than if regular Git tools like `git pull` could be used.
+
+## GitGitGadget contributions
+
+If the contribution was sent to the mailing list via [GitGitGadget](https://gitgitgadget.github.io/) (which is a tool allowing to send GitHub PRs to the Git mailing list without having to fiddle with mail programs until they send the contribution in the precise form that the Git project wants them), the backporting process is comparatively hassle-free: GitGitGadget contributions have a fetch'able Git branch and the PRs contain other relevant information such as the date and the commit which integrated the patches into Git's main branch.
+
+Take for example [the "ci: use a newer `github-script` version" patch that avoids warnings in CI runs about using deprecated Actions/node.js versions](https://lore.kernel.org/git/[email protected]/): That mail contains the information in the footer from which PR it originated (in this example, [`gitgitgadget/git#1387`](https://github.com/gitgitgadget/git/pull/1387)). That PR receives labels depending on the contribution process: `seen` if it was integrated into the daily hodgepodge branch of Git, `next` once the contribution advanced to the "let's cook this for a bit" stage, and `master` once the contribution has been slated for the next official Git version.
+
+That PR also receives a comment once the patches have been integrated into a tentative topic branch, in this example ["js/ci-set-output"](https://github.com/gitgitgadget/git/pull/1387#issuecomment-1307968188). Following the [`js/ci-set-output` link](https://github.com/gitgitgadget/git/commits/js/ci-set-output), you can see the Git commits of the topic branch in which for upstream Git tracks the patches. You can also see the original shape of the contribution by clicking on the link to the PR branch at the top of the PR page.
+
+When backporting patches, the Git for Windows project typically prefers the shape that was already accepted upstream, i.e. once it made it into `next`, we backport the _upstream topic branch_'s commits.
+
+The typical way to backport such a branch is to first see whether it needs to be rebased at all, i.e. if there are any additional commits between Git for Windows' `main` branch and that topic branch. The quickest way is to direct a web browser to a URL like this: https://github.com/git-for-windows/git/compare/main...gitgitgadget:next (replace `gitgitgadget:next` with your own fork and branch).
+
+### Scenario: The upstream topic branch can be used as-is
+
+If that comparison only shows the commits of the contribution, we're almost done: hit the "Create pull request" button on that page and populate the PR description with [informative, enjoyable content](https://github.blog/2022-06-30-write-better-commits-build-better-projects/), i.e. providing enough context and motivation to understand why the patches need to be backported, enough detail to understand the contribution, how it solves the issue(s) at hand and what other impact the patches have, and of course add links to the relevant discussions such as the Git mailing list thread, the relevant Git for Windows tickets (if any), etc
+
+### Scenario: The upstream topic branch _cannot_ be used as-is
+
+There seems to be little rhyme nor reason on top of which commit, precisely, the Git maintainer decides to apply the patches received via the Git mailing list. At times it seems rather arbitrary and is not always conducive to using the upstream topic branch in Git for Windows as-is. In the example mentioned above, the comparison between Git for Windows' `main` branch and the topic branch showed 386 commits instead of the single desired one, at the time of writing.
+
+In such scenarios, a backport involves creating a local branch from the upstream topic branch, rebasing the patch on top of a more suitable base commit (typically, a Git tag, or a Git for Windows tag if necessary to avoid merge conflicts, falling back to the tip of Git for Windows' `main` branch), then pushing the result and opening a PR from that. In the example above:
+
+1. `git fetch https://github.com/gitgitgadget/git js/ci-set-output`
+2. `git switch -c js/ci-set-output FETCH_HEAD`
+3. `git rebase -i --onto v2.38.0 HEAD~1 # increase 1 accordingly for multiple patches`
+4. `git push <personal-fork> HEAD`
+
+After that, as detailed above, open a PR with an [informative, enjoyable description](https://github.blog/2022-06-30-write-better-commits-build-better-projects/), i.e. providing enough context and motivation to understand why the patches need to be backported, enough detail to understand the contribution, how it solves the issue(s) at hand and what other impact the patches have, and of course add links to the relevant discussions such as the Git mailing list thread, the relevant Git for Windows tickets (if any), etc
+
+## Non-GitGitGadget contributions
+
+If the contribution that needs to be backported did _not_ use GitGitGadget, it can become a bit more daunting, in particular when going off of a bug report on the Git mailing list. The first step, then, is to find the relevant topic branch (if any).
+
+### If there is not even an upstream topic branch yet
+
+The most challenging scenario is when there exists a patch that needs to be backported but it has not been integrated into Git yet (not even into the `seen` branch), and all one has to go for is a thread on the Git mailing list (or even just a Message-Id, which can be turned into a link to the Git mailing list archive via https://lore.kernel.org/git/<message-id>).
+
+The first order of business is to find the mail containing the patch. Often, these mails have either been linked to from a reply to the bug report, or they are sent as replies directly, with the mail's subject line starting with `[PATCH]`. If that is not the case, the mail containing the patch can be identified by scrolling all the way to the beginning of the mail thread at the bottom of the lore.kernel.org page that has the bug report, then click the "nested" link so that all mails in the thread are shown, and then using the browser's "Find" functionality to search for the needle "diff --git".
+
+Once the mail containing the patch was found, the [`apply-from-lore.sh` script](https://github.com/git-for-windows/build-extra/blob/HEAD/apply-from-lore.sh) can be used with the mail's permalink to apply it to a local branch in a checkout of [the `git-for-windows/git` repository](https://github.com/git-for-windows/git/).
+
+Then, continue as detailed in the first sections above.
+
+### If there _is_ an upstream topic branch
+
+Sometimes, contributors are asked to backport patches that have made it into upstream Git. If it is already clear what name the Git maintainer gave the topic branch, continue as outlined in the corresponding subsection of [the "GitGitGadget" section](#gitgitgadget-contributions) above.
+
+If it is unclear what the name of that topic branch is, search for the first line of a commit message ("commit subject" or "oneline") of that contribution in the [What's cooking mail](https://github.com/git/git/blob/todo/whats-cooking.txt); The name of the topic branch will be mentioned above the line mentioning the commit subject.
+
+If all else fails, you can also try to fetch the `seen` branch and search for the topic branch via `git show FETCH_HEAD^{/<regex>}` where the regular expression matches the commit subject in question.

content/building-git.md

@@ -0,0 +1,62 @@
+---
+title: "Building Git"
+aliases:
+  - "Building-Git"
+---
+# Building Git on Windows
+
+We build Git for Windows using an [MSYS2](https://msys2.github.io/) based *Git for Windows SDK*. This SDK can be installed via the [SDK installer](https://gitforwindows.org/#download-sdk)
+
+## Installing a build environment
+
+1. Just run the [SDK installer](https://gitforwindows.org/#download-sdk).
+
+## Build Git
+
+1. An initial `git clone` and `make` should have already occurred when running the [SDK installer](https://gitforwindows.org/#download-sdk).
+
+2. Open the *Git for Windows SDK* *MinGW* shell by double clicking either the Shortcut on the desktop `Git SDK 32-bit.lnk` or by double clicking `mingw32_shell.bat` in the install folder. That is `Git SDK 64-bit.lnk` and `mingw64_shell.bat` for the `64bit` [SDK installer](https://gitforwindows.org/#download-sdk).
+
+2. Change directory to the initial clone: `cd /usr/src/git`. If the directory is empty you may have the `master` branch checked out: `git checkout main`.
+
+4. (Optional) build Git: `make install`
+
+5. Run the test suite: `make test`. If you are a fan of statistics, you can use the following `prove` invocation to run the testsuite. But first we have to change to the test directory with the command `cd t`. After that you can issue `/usr/bin/time prove -j 15 --state=failed,save ./t[0-9]*.sh`. If *15* threads are too many for your system, you can provide the number of threads via the `-j <num>` (j for jobs) parameter.
+
+## Build Git from a Pull Request or another branch
+
+Once the SDK built Git, it is *very* easy to build another revision of Git, such as per a different branch or Pull Request.
+
+1. open the Git Bash of the SDK unless it is still open: execute the `git-bash.exe` binary in the top-level directory of the SDK,
+2. switch the working directory: `cd /usr/src/git`,
+3. fetch the Pull Request's revision or the branch:
+ 1. if you want to test a Pull Request, call `git fetch origin refs/pull/<id>/head`, where `<id>` is the number of the Pull Request (e.g. if you want to test Pull Request #606, you would call `git fetch origin refs/pull/606/head`),
+ 2. if you want to test a custom branch, call `git fetch <url> <branch>` instead, where `<url>` is the URL of the repository and `<branch>` is the name of the branch to test (e.g. if you wanted to test @dscho's `cool-new-feature` branch, you would call `git fetch https://github.com/dscho/git cool-new-feature`),
+4. check out the revision that was just fetched: `git checkout FETCH_HEAD`,
+5. continue as [above](./building-git.html#build-git) either by `make install` or `make test`.
+
+## Updating to the newest Git for Windows version
+
+```bash
+cd /usr/src/git
+git pull
+make -j15 install install-html
+```
+
+## Testing the new Git version
+
+As before:
+
+```bash
+cd /usr/src/git/t
+/usr/bin/time prove -j 5 --state=failed,save ./t[0-9]*.sh
+```
+
+## See also Regression Testing
+
+Single tests, block of tests, or the whole test suite can be run, as detailed in
+[Running Git's regression-tests](./running-gits-regression-tests.html)
+
+
+---
+TODO: mention good practices to develop using Eclipse, MSVC