Ensure that there is at most one top-level header

It is a no-no to have multiple top-level headers in the same file, see
https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md025.md

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

content/32-bit-issues.md

@@ -3,7 +3,9 @@ title: "32 bit issues"
 aliases:
   - "32-bit-issues"
 ---
-# What is the problem with running Git for Windows in 32-bit mode?
+# 32-bit issues
+
+## 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.
 
@@ -13,7 +15,7 @@ The simplest solution to fix that problem if it rears its ugly head at all is to
 
 The second-simplest solution is to [reinstall Git for Windows](#reinstall-git-for-windows).
 
-# Background
+## 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.
 
@@ -35,7 +37,7 @@ When there is already a `.dll` interfering with MSYS2's runtime's hard-coded add
     865 [main] sh.exe" 17588 open_stackdumpfile: Dumping stack trace to sh.exe.stackdump
 ```
 
-# Solutions
+## Solutions
 
 There are several ways how to get out of this problem:
 
@@ -75,7 +77,7 @@ 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?
+## 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:
 
@@ -89,4 +91,4 @@ A work-around that appears to help in most of those cases is to call
 /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.
+Your mileage may vary: it might be necessary to play with the base address a bit.

content/building-git.md

@@ -3,13 +3,15 @@ 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
+## Installing a build environment
 
 1. Just run the [SDK installer](https://gitforwindows.org/#download-sdk).
 
-# Build Git
+## Build Git
 
 1. An initial `git clone` and `make` should have already occurred when running the [SDK installer](https://gitforwindows.org/#download-sdk).
 
@@ -33,7 +35,7 @@ Once the SDK built Git, it is *very* easy to build another revision of Git, such
 4. check out the revision that was just fetched: `git checkout FETCH_HEAD`,
 5. continue as [above](https://github.com/git-for-windows/git/wiki/Building-Git#build-git) either by `make install` or `make test`.
 
-# Updating to the newest Git for Windows version
+## Updating to the newest Git for Windows version
 
 ```bash
 cd /usr/src/git

content/building-msys2-runtime.md

@@ -7,22 +7,22 @@ aliases:
 
 1. Download and run the [Git for Windows SDK installer](https://gitforwindows.org/#download-sdk).
 
-# Building msys2-runtime
+## Building msys2-runtime
 
 2. Open the Git for Windows SDK MSys shell by double-clicking the `msys2_shell.cmd` script in the install folder (by default `C:\git-sdk-<arch>`).
 
 3. From the MSys shell do: `sdk build msys2-runtime`
 
 This last step may take a while, so please be patient!
 
-# Rebuilding the msys2-runtime
+## Rebuilding the msys2-runtime
 
 When there are bugs in the msys2-runtime (e.g. problems with the POSIX-to-Windows path mangling), you need to rebuild the `msys-2.0.dll`, possibly frequently.
 
 To rebuild the `msys-2.0.dll` -- assuming that you have built it already as described above -- you first need to start an *MSys* shell by double-clicking the `msys2_shell.cmd` script in your Git SDK's top-level directory. Then call `cd /usr/src/MSYS2-packages/msys2-runtime/src/msys2-runtime/winsup/cygwin`. Now you can modify the source code to your heart's content. It is actually a local clone of https://github.com/git-for-windows/msys2-runtime; you probably want to add your own fork as a remote.
 
 To actually build the `msys-2.0.dll`, switch to `src/build-<arch>-pc-msys/<arch>-pc-msys/winsup/cygwin` and type `make`. This will generate an `msys0.dll` file in that directory. This is the new `msys-2.0.dll`, but you cannot simply copy it into `/usr/bin/` because it is in use by the current `mintty` as well as by the current Bash. To update, you need to close all programs using the msys2-runtime (including all of the terminal windows), then copy the `msys0.dll` file, replacing the existing `/usr/bin/msys-2.0.dll`, either using Explorer, `cmd.exe` or a separate Git SDK (for example, when debugging the 64-bit msys2-runtime, a 32-bit Git SDK comes in real handy). You will **want** to make a backup copy of the old `msys-2.0.dll`...
 
-# Related: building/rebuilding Bash
+## Related: building/rebuilding Bash
 
-The process to rebuild the `Bash` is very similar to the `msys2-runtime` one; You will just need to work in the `src/bash-<version>/` subdirectory of `/usr/src/MSYS2-packages/bash/` (both the sources and the generated `bash.exe` live there). Bash also requires all Bash instances to be exited before the executable is replaced by the new one. And like with the msys2-runtime, you will **want** to make a backup copy of the old `bash.exe`.
+The process to rebuild the `Bash` is very similar to the `msys2-runtime` one; You will just need to work in the `src/bash-<version>/` subdirectory of `/usr/src/MSYS2-packages/bash/` (both the sources and the generated `bash.exe` live there). Bash also requires all Bash instances to be exited before the executable is replaced by the new one. And like with the msys2-runtime, you will **want** to make a backup copy of the old `bash.exe`.

content/compiling-git-with-visual-studio.md

@@ -3,9 +3,11 @@ title: "Compiling Git with Visual Studio"
 aliases:
   - "Compiling-Git-with-Visual-Studio"
 ---
+# Compiling Git with Visual Studio
+
 Please note: this page describes how to compile Git's source code in Visual Studio 2015 or later.
 
-# Checking out `vs/main`
+## Checking out `vs/main`
 
 > [!WARNING]  
 > The `vs/main` branch and `git.sln` is deprecated. The current approach is to open the `git` folder in VS directly, refer to the [README of the `vs/main` branch](https://github.com/git-for-windows/git/tree/vs/main).
@@ -16,7 +18,7 @@ However, as of Git for Windows v2.11.0, a much more convenient way is available:
 
 Simply open the `git.sln` file and build the solution. DO NOT upgrade Build Tools to v141 - it will not work. If you are using VS 2017 or later, you need to install Build Tools v140 manually.
 
-# Running the tests
+## Running the tests
 
 When building Git in Visual Studio, you do not actually need a full-blown Git for Windows SDK. Simply install Git for Windows, make sure that the entire solution was built, open a Git Bash and run the tests in the `t/` subdirectory.
 
@@ -43,6 +45,6 @@ prove --timer --jobs 15 ./t[0-9]*.sh
 ```
 
 
-# Browsing the code
+## Browsing the code
 
-You can also use the Sourcetrail code browser (now open source) in conjunction with Visual Studio, see [Sourcetrail code viewer](https://github.com/git-for-windows/git/wiki/Sourcetrail-code-viewer-and-linkage-to-Visual-Studio,-for-Git) page.
+You can also use the Sourcetrail code browser (now open source) in conjunction with Visual Studio, see [Sourcetrail code viewer](https://github.com/git-for-windows/git/wiki/Sourcetrail-code-viewer-and-linkage-to-Visual-Studio,-for-Git) page.

content/contact.md

@@ -3,13 +3,15 @@ title: "Contact"
 aliases:
   - "Contact"
 ---
+# How to contact the Git for Windows project
+
 Please state the nature of your medical emergency.
 
-# I found a bug!
+## I found a bug!
 
 Please follow [our guide lines](https://github.com/git-for-windows/git/wiki/Issue-reporting-guidelines) on reporting bugs.
 
-# I have a question!
+## I have a question!
 
 We have [GitHub Discussions](https://github.com/git-for-windows/git/discussions/). If, for some reason or other, you prefer a mailing list, use [the Git mailing list](mailto:[email protected]). It is actually a Google Group which can be used as if it were a forum, too.
 

content/debugging-git.md

@@ -116,7 +116,7 @@ GDB (since version 10.1) can use the [Pygments](https://pygments.org/) Python li
 pacman -Syy mingw-w64-x86_64-python-pygments
 ~~~
 
-# Debugging with GDB in Emacs
+## Debugging with GDB in Emacs
 
 First, install `emacs` and run it:
 

content/diagnosing-performance-issues.md

@@ -3,29 +3,31 @@ title: "Diagnosing performance issues"
 aliases:
   - "Diagnosing-performance-issues"
 ---
+# How to diagnose when Git for Windows is slow
+
 Under certain circumstances, Git can become very slow on Windows. Here are a couple of hints to figure out why.
 
-# Identify specific Git commands' performance issues
+## Identify specific Git commands' performance issues
 
 If the problem lies with a specific Git command, the most straight-forward way to investigate is to use profiling tools.
 
 The canonical profiling tool in GCC's tool set is [`gprof`](https://sourceware.org/binutils/docs/gprof/). However, the MINGW version of the GCC tools offered by MSYS2 has been known to produce empty output on occasion.
 
 An more convenient alternative is to use [Visual Studio's Performance Profiler](https://github.com/git-for-windows/git/wiki/Performance-profiling-with-Visual-Studio) (which is available in the free-of-cost Community version) which offers a powerful graphical user interface.
 
-# Trace executions in the Bash startup
+## Trace executions in the Bash startup
 
 When starting Git Bash is already slow, edit the file `<GIT_HOME>/etc/profile` and insert a `set -x` somewhere at the top. This command will tell Bash to echo the commands it is executing so that you can find out which commands are slow and investigate more closely in that direction.
 
-# Activate Git's own tracing
+## Activate Git's own tracing
 
 Git often executes subcommands, hence it is possible that you run a certain Git command but the tardiness stems from a *different* Git command. To find out which commands Git executes internally, set the environment variable `GIT_TRACE` like so:
 
 ```bash
 GIT_TRACE=1 git stash
 ```
 
-# Redirecting output to a file
+## Redirecting output to a file
 
 Sometimes the output is too verbose – or the command-line window flashes and closes too quickly to read – to make direct diagnosing of the output practical. In this case, simply redirect the entire output of the Bash to a file, like so:
 
@@ -35,18 +37,18 @@ exec > "$HOME"/Desktop/debug.txt 2>&1
 
 After diagnosing the problem, you *will* want to remove the redirection, otherwise you will not be able to interact normally with the Bash.
 
-# Enable the filesystem cache
+## Enable the filesystem cache
 
 Windows' filesystem layer is inherently different from Linux' (for which Git's filesystem access is optimized). As a workaround, Git for Windows offers a filesystem cache which accelerates operations in many cases, after an initial "warm-up". This workaround can be activated in the installer, on the last wizard page, or you can activate the filesystem cache per-repository:
 
 ```bash
 git config core.fscache true
 ```
 
-# Avoid inspecting large working trees' modification times
+## Avoid inspecting large working trees' modification times
 
 When working with large working trees, Git's (frequent) checking whether files were modified since Git's internal index was last updated can lead to substantial lags. In such a case, it can make sense to switch off this check, but it comes at a price: it requires discipline on the developer's side to keep track which files were changed *and `git add` them explicitly for the next commit* (the output of `git status` will *no longer* identify modified files). You can disable the check per-repository thusly:
 
 ```bash
 git config core.ignoreStat true
-```
+```

content/file-names-branch-names-path-quotation-executable-bit-and-file-modes-core-filemode.md

@@ -17,19 +17,19 @@ Likewise Windows will not be able to check out both an upper case and lower case
 
 Windows also cannot checkout files which contain special characters, such as colon(:) etc. This can cause cross system management issues.
 
-# Path Quotation
+## Path Quotation
 
 Spaces in filenames is common in Windows, but rare in Linux. Linux has, like Windows, multiple path quoting mechanisms. In addition Linux can accept any character in any filename, including 'special' characters. This means that the path conversion between Windows and Git is imperfect and dependant on the particular command structure and 'terminal' in use.
 
 Many Git commands do not report errors in the way that maybe expected by Windows users - some will simply ignore invalid options and paths, leaving the unfamiliar user wondering what happened. The `git config` is one area where this may happen, especially as there can be quoting confusion (single, double, or none) between bash, cmd, and powershell. (e.g. see [thread](https://public-inbox.org/git/[email protected]/))
 
-# Executable and Mode Bits
+## Executable and Mode Bits
 
 Linux attaches a mode word to each file, with bits that indicate if the file is executable, readable, writable, and other ownership aspects (`chmod`). This does not map well to Windows semantics, especially for the executable bit. The existing mode bits are retained in the repository tree meta data, which is then held locally in the index.
 
 Users may need to directly manipulate the mode bits where necessary - the [stackoverflow page](https://stackoverflow.com/a/38285462/717355) shows how to use the `--chmod` option while adding or updating files.
 
-# core.FileMode
+## core.FileMode
 
 The core.FileMode configuration records, for the locally cloned repository, the local file system semantics (i.e. is it case sensitive / case preserving or not). DO NOT change this, unless it is actually set wrong. Git will trust this setting and mis-setting it may cause unexpected effects and damage - Don't do it, the internet, as ever, is probably wrong.
 
@@ -38,6 +38,6 @@ From https://git-scm.com/docs/git-config#git-config-corefileMode
 
 > Some filesystems lose the executable bit when a file that is marked as executable is checked out, or checks out a non-executable file with executable bit on. git-clone[1] or git-init[1] probe the filesystem to see if it handles the executable bit correctly and this variable is automatically set as necessary.
 
-# Windows Drive (C:) paths vs Bash rooted (/) paths
+## Windows Drive (C:) paths vs Bash rooted (/) paths
 
 In the Git for Windows bash, the classic `C:` drive letter is replaced by the the implicit `/c/` directory path. This conversion is commonly used in the `git config` paths that need to be absolute.

content/git-cannot-create-a-file-or-directory-with-a-long-path.md

@@ -3,11 +3,13 @@ title: "Git cannot create a file or directory with a long path"
 aliases:
   - "Git-cannot-create-a-file-or-directory-with-a-long-path"
 ---
-# The problem
+# Git for Windows vs long paths
+
+## The problem
 
 Windows does not properly support files and directories longer than 260 characters. This applies to Windows Explorer, `cmd.exe` and many other applications (including many IDEs as well as bash, perl and tcl that come with Git for Windows).
 
-# Opt-In configuration
+## Opt-In configuration
 
 For this reason, long paths support in Git for Windows is disabled by default.
 
@@ -17,12 +19,12 @@ That being said, long paths support for C-based git commands can be enabled by s
 git config core.longpaths true
 ```
 
-# Technical background
+## Technical background
 
 The root cause of the technical limitation of 260 chars lies deeply within the Win32 API.
 Microsoft's online article [Naming Files, Paths, and Namespaces](http://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx#maxpath) describes the reasons.
 Git's source code itself does not have the limitation, it is Windows-only.
 
-# Implementation details
+## Implementation details
 
 Originally [introduced into Git for Windows 1.9.0](https://github.com/msysgit/git/pull/122), the idea to overcome the length limitation is to convert them into UNC paths (i.e. network paths of the form `\\?\...`). Such paths are accepted by many of the Win32 API's functions accepting UTF-16 strings (many functions in the Win32 API are available as ASCII and UTF-16 functions, marked by an `A` and a `W` suffix, respectively) and are allowed to have a length up to 32,767 wide characters. See e.g. [this commit](https://github.com/git-for-windows/git/commit/38b94fe15fb60e3871a166eec8cfd4265fee727f) for more details.

content/git-wrapper.md

@@ -3,15 +3,17 @@ title: "Git wrapper"
 aliases:
   - "Git-wrapper"
 ---
+# What _is_ the "Git wrapper"?
+
 One of the more confusing aspects of Git for Windows is that its main entry points (`<Git>\git-bash.exe`, `<Git>\cmd\git.exe`, `<Git>\bin\bash.exe`, where `<Git>` is the location into which Git was installed, typically `C:\Program Files\Git`) are _not_ the actual binaries implementing the functionality.
 
 All of these executables are variants of the ["Git wrapper"](https://github.com/git-for-windows/MINGW-packages/blob/main/mingw-w64-git/git-wrapper.c). Its only purpose is to set a couple of environment variables and then spawn the _actual_ program. For example, `Git/bin/bash.exe` will set `MSYSTEM` and `PATH` and spawn `Git/usr/bin/bash.exe`.
 
-# Why is this needed?
+## Why is this needed?
 
 The actual programs, e.g. `bash.exe` or `git.exe`, live in `<Git>\usr\bin` and `<Git>\mingw64\bin` (or `<Git>\mingw32\bin` in 32-bit setups), and the issue is that either links dynamically to some `.dll` files (e.g. `msys-2.0.dll`). So if we were to add those directories to the `PATH` variable, 3rd-party software that links _to the same_ `.dll` files would quite possibly be broken (or Git's own programs). Even worse, some of the other `.dll` files present in those folders are in much more widespread use, e.g. OpenSSL. This has been the cause for quite a few tickets in the past, and the `<Git>\cmd` directory was added to help this, at first having Batch scripts for `git`, `git-gui` and `gitk`, and later those were turned into Visual Basic scripts, but eventually we just bit the bullet and turned them into real executables because we needed more control than scripts allowed us (e.g. to prevent ugly console windows from "flashing").
 
-# What environment variables are overridden by the Git wrapper?
+## What environment variables are overridden by the Git wrapper?
 
 - **`PATH`**
 
@@ -31,6 +33,6 @@ The actual programs, e.g. `bash.exe` or `git.exe`, live in `<Git>\usr\bin` and `
 
 For full information, read the source code of [the `setup_environment()` function of the Git wrapper](https://github.com/git-for-windows/MINGW-packages/blob/0a7407a39c3015cc7a3c296d8a0db38439c65eed/mingw-w64-git/git-wrapper.c#L116-L200).
 
-# Avoiding the Git wrapper
+## Avoiding the Git wrapper
 
-Especially when running scripts that call Git tens of thousands of times, the start-up cost for the Git wrapper might be noticed, and users might want to side-step it. To address this desire, starting with https://github.com/git-for-windows/git/pull/2506 Git for Windows supports the use case the hard-coded absolute path to `<Git>\mingw64\bin\git.exe` is used to launch Git, without the need to add it to the `PATH`.
+Especially when running scripts that call Git tens of thousands of times, the start-up cost for the Git wrapper might be noticed, and users might want to side-step it. To address this desire, starting with https://github.com/git-for-windows/git/pull/2506 Git for Windows supports the use case the hard-coded absolute path to `<Git>\mingw64\bin\git.exe` is used to launch Git, without the need to add it to the `PATH`.