git-for-windows/git
1
0
Fork 0
mirror of https://github.com/git-for-windows/git.git synced 2025-12-11 11:16:01 -06:00
Code Issues Packages Projects Releases 335 Wiki Activity

Use the preferred spelling of the MSYS2 project 

While it does not make sense to pretend that the project name is a
four-letter acronym (it really stands for "Minimal System"), it is
definitely not worth an issue to fight over. We have much bigger fish
to fry.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Johannes Schindelin 2016-01-20 07:23:35 +01:00
parent 8e33243389
commit af7c6c8e6f
8 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
32-bit-issues.md

@ -2,27 +2,27 @@
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 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 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.
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.
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 :
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
@ -36,7 +36,7 @@ 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.
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
@ -44,17 +44,17 @@ If you cannot switch to 64-bit for any reason, reinstalling Git for Windows will
## 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.
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:
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`
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'
```
```

2
Building-Git.md

@ -1,4 +1,4 @@
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://git-for-windows.github.io/#download-sdk)
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://git-for-windows.github.io/#download-sdk)
# Installing a build environment

2
Building-msys2-runtime.md

@ -6,7 +6,7 @@
1. Open the *Git for Windows SDK* *MSys* shell by double clicking `msys2_shell.bat` in the install folder. (i.e. not the *MinGW 32-bit* nor the *MinGW 64-bit* one).
2. Install the MSys2 Toolchain: `pacman -S base-devel`.
2. Install the MSYS2 Toolchain: `pacman -S base-devel`.
3. Initialize the local MSYS2-packages clone: `cd /usr/src/MSYS2-packages && git fetch origin && git checkout master`.

10
Home.md

@ -12,15 +12,15 @@ This became really too tedious, so much so that there was not enough time to pro
At some stage, it became obvious that there needs to be a better solution. [@sschuberth](https://github.com/sschuberth) had already started a [separate project](https://github.com/sschuberth/gfw-msys1-sdk) to leverage the package manager that _MSys_ had introduced at that stage, `mingw-get`. However, it turned out that the packages were not maintained all that well, and besides, _MSys_' runtime had not been kept up-to-date with [Cygwin](https://www.cygwin.com/), and was falling behind in terms of features and support.
In a two-hour Skype session about the course of _Git for Windows_ [@dscho](https://github.com/dscho), [@t-b](https://github.com/t-b) and [@sschuberth](https://github.com/sschuberth) decided to give [MSys2](https://msys2.github.io/) a whirl. _MSys2_ was started with the idea to restart the _MSys_ project, frequently updating with _Cygwin_ and just keeping the spirit of _MSys_ to provide a very stripped-down *POSIX* layer, essentially a bare-minimum version of _Cygwin_. _MSys2_ also sports a package manager (`pacman`) and keeps those packages up-to-date very well. Another bonus: _MSys2_ is available for `64-bit` in addition to `32-bit`, while _MSys_ was stuck with `32-bit`.
In a two-hour Skype session about the course of _Git for Windows_ [@dscho](https://github.com/dscho), [@t-b](https://github.com/t-b) and [@sschuberth](https://github.com/sschuberth) decided to give [MSYS2](https://msys2.github.io/) a whirl. _MSYS2_ was started with the idea to restart the _MSys_ project, frequently updating with _Cygwin_ and just keeping the spirit of _MSys_ to provide a very stripped-down *POSIX* layer, essentially a bare-minimum version of _Cygwin_. _MSYS2_ also sports a package manager (`pacman`) and keeps those packages up-to-date very well. Another bonus: _MSYS2_ is available for `64-bit` in addition to `32-bit`, while _MSys_ was stuck with `32-bit`.
Thanks to sponsoring of _GitHub_, [@dscho](https://github.com/dscho) could afford to spend the time to investigate the possibilities with _MSys2_. It turned out that _MSys2_ already provided most of the parts needed, and would make maintenance much, much easier. [@dscho](https://github.com/dscho) (and others too) really spent an insane amount of time (thanks GitHub!) to get everything up to speed, even fixing a couple of long-standing bugs in _Git for Windows_. It essentially came down to modifying the `msys2-runtime` to _Git for Windows_ needs. The rest is basically upstream _MSys2_ architecture.
Thanks to sponsoring of _GitHub_, [@dscho](https://github.com/dscho) could afford to spend the time to investigate the possibilities with _MSYS2_. It turned out that _MSYS2_ already provided most of the parts needed, and would make maintenance much, much easier. [@dscho](https://github.com/dscho) (and others too) really spent an insane amount of time (thanks GitHub!) to get everything up to speed, even fixing a couple of long-standing bugs in _Git for Windows_. It essentially came down to modifying the `msys2-runtime` to _Git for Windows_ needs. The rest is basically upstream _MSYS2_ architecture.
And yes, the idea is still the same as the original one: Update the _MSys2_ setup, together with a _Git_ package built from _Git for Windows_' source code, then bundle the relevant files together with a couple of extra files into an installer. Then I sign it and upload it. And that is _Git for Windows_ 2.x.
And yes, the idea is still the same as the original one: Update the _MSYS2_ setup, together with a _Git_ package built from _Git for Windows_' source code, then bundle the relevant files together with a couple of extra files into an installer. Then I sign it and upload it. And that is _Git for Windows_ 2.x.
Now, keep in mind that _MSys2_ and Linux (The original target for _Git_'s distribution) are very different beasts. Their distributions might include packages that are built from the same source code (i.e. the `binutils`, `gcc` or `bash` package), but the runtime is very, very different: _MSys2_'s runtime is a stripped-down, slightly modified _Cygwin_ runtime running on top of the Windows kernel, while Linux' runtime is the Linux kernel, running as a separate OS altogether.
Now, keep in mind that _MSYS2_ and Linux (The original target for _Git_'s distribution) are very different beasts. Their distributions might include packages that are built from the same source code (i.e. the `binutils`, `gcc` or `bash` package), but the runtime is very, very different: _MSYS2_'s runtime is a stripped-down, slightly modified _Cygwin_ runtime running on top of the Windows kernel, while Linux' runtime is the Linux kernel, running as a separate OS altogether.
So if you are missing some packages - feel free to start making one. This is Open Source, however, so everybody interested and capable enough can contribute whatever they need to address their needs. And that includes you: you could imitate e.g. [a simple `PKGBUILD` file](https://github.com/Alexpux/MINGW-packages/blob/master/mingw-w64-assimp-git/PKGBUILD) to build a new package e.g. `msmtp`, the component that _Git for Windows_ 1.x uses to support `sendemail`. Then open a Pull Request so that _Git for Windows_ can ship it. Our documentation will be helpful in that endeavor: [package-management](https://github.com/git-for-windows/git/wiki/Package-management), in particular [package-management#rebuild-packages](https://github.com/git-for-windows/git/wiki/Package-management#rebuild-packages).
# Start documenting
If you need inspiration what you could write about: document your common work flows. Write a tutorial how to start coding _Git for Windows_, how to run the test suite. Write a tutorial how to debug a failing test. Write about something you would have wished you had known about Git for Windows a long time ago.
If you need inspiration what you could write about: document your common work flows. Write a tutorial how to start coding _Git for Windows_, how to run the test suite. Write a tutorial how to debug a failing test. Write about something you would have wished you had known about Git for Windows a long time ago.

4
MSYS2-Notes.md

@ -1,4 +1,4 @@
Page for things that pop up while fiddling with MSys2.
Page for things that pop up while fiddling with MSYS2.
# PS1 script
@ -78,4 +78,4 @@ This means the `_vimrc` have CRLF end line style instead of LF. You can either u
```
dos2unix $HOME/_vimrc
```
```

12
Package-management.md

@ -1,6 +1,6 @@
Modern software development relies heavily on a way to manage dependencies, i.e. to keep track of required software libraries and their versions. Examples are `apt-get` for Linux, `homebrew` for MacOSX, `Maven` for Java and `pip` for Python.
Git for Windows is based on [MSys2](https://msys2.github.io/) which bundles Arch Linux' [Pacman](https://wiki.archlinux.org/index.php/Pacman) tool for dependency management.
Git for Windows is based on [MSYS2](https://msys2.github.io/) which bundles Arch Linux' [Pacman](https://wiki.archlinux.org/index.php/Pacman) tool for dependency management.
# How to use `pacman`
@ -28,9 +28,9 @@ pacman -Syu
### Updating `msys2-runtime`, `pacman` and `bash`
As `pacman.exe` is itself an MSys2 executable, it is strongly suggested to update `msys2-runtime` and `pacman` packages individually if they need to be updated, and let `pacman` quit *immediately* afterwards.
As `pacman.exe` is itself an MSYS2 executable, it is strongly suggested to update `msys2-runtime` and `pacman` packages individually if they need to be updated, and let `pacman` quit *immediately* afterwards.
Likewise, if you run `pacman` from a `bash` -- an MSys2 program, too -- you should quit the shell *immediately* (it might show an infinite stream of heap messages instead of quitting, requiring to be force-quit).
Likewise, if you run `pacman` from a `bash` -- an MSYS2 program, too -- you should quit the shell *immediately* (it might show an infinite stream of heap messages instead of quitting, requiring to be force-quit).
## Remove packages
@ -82,7 +82,7 @@ To build MSys packages, you need to start the `MSys` shell (which sets `MSYSTEM=
makepkg -s
```
*Note*: Before building the first MSys package, as per [MSys2's own documentation](http://sourceforge.net/p/msys2/wiki/Contributing%20to%20MSYS2/) you need to install the development packages for development:
*Note*: Before building the first MSys package, as per [MSYS2's own documentation](http://sourceforge.net/p/msys2/wiki/Contributing%20to%20MSYS2/) you need to install the development packages for development:
```sh
pacman -Sy base-devel msys2-devel
@ -128,7 +128,7 @@ perl -MCPAN -e shell
Pacman repositories are served via HTTP, as static files in a single directory. The most important file in that directory is the *package index*, called `<name>.db.tar.xz` by convention. This package index can be updated via `repo-add <package-index> <package-file>...` (this updated *only* the package index, it does *not* copy the package files into the same directory). Pacman expects to find the package files referenced in the package index in the same directory as the index.
The *Git for Windows*-specific packages are served from Bintray, see [below](#Bintray).
We ship MSys2 and MinGW packages for two architectures, [`i686`](https://dl.bintray.com/git-for-windows/pacman/i686/) and [`x86_64`](https://dl.bintray.com/git-for-windows/pacman/x86_64/).
We ship MSYS2 and MinGW packages for two architectures, [`i686`](https://dl.bintray.com/git-for-windows/pacman/i686/) and [`x86_64`](https://dl.bintray.com/git-for-windows/pacman/x86_64/).
## Bintray
@ -156,4 +156,4 @@ To upload new files, a maintainer needs to have permission to write to the `pacm
The `fetch` step will initialize or synchronize the local mirror of the Pacman repository, the `add` step will copy the packages into the appropriate location, and the `push` step will update the package index, and upload the packages that are not yet on Bintray as well as the package index.
Note: The `pacman-mirror.sh` tool takes no precaution against simultaneous use. You *will* want to coordinate with your fellow maintainers to avoid running it at the same time as somebody else.
Note: The `pacman-mirror.sh` tool takes no precaution against simultaneous use. You *will* want to coordinate with your fellow maintainers to avoid running it at the same time as somebody else.

6
Running-Git's-regression-tests.md

@ -63,7 +63,7 @@ Some parts of Git are implemented as Perl scripts. To trigger execution tracing
### `GIT_TRACE=1`
When Git sees that the environment variable `GIT_TRACE` is set, it will print out an internal execution trace when Git wants to call external executables and builtins. This is extremely helpful in particular when debugging posix-to-windows mangling issues with the MSys2 runtime. All you do is to prefix the Git command to be executed in the test script with `GIT_TRACE=1 `, e.g. `GIT_TRACE=1 git difftool --extcmd "$2"`.
When Git sees that the environment variable `GIT_TRACE` is set, it will print out an internal execution trace when Git wants to call external executables and builtins. This is extremely helpful in particular when debugging posix-to-windows mangling issues with the MSYS2 runtime. All you do is to prefix the Git command to be executed in the test script with `GIT_TRACE=1 `, e.g. `GIT_TRACE=1 git difftool --extcmd "$2"`.
### Interactive Bash/GDB
@ -79,7 +79,7 @@ It gets even trickier when there is no `stdout`/`stderr` available (e.g. when de
While it is a little cumbersome to add such debug print statements (after all, you typically have to rebuild the executables and run the tests from the top), there is also a big benefit to this technique over single-stepping: the debug output can be made conditional upon the particulars of the problem to be debugged. For example, instead of writing out information *every* time, say, `get_sha1_hex()` is called, it can be written out *only* the third time it is called with an SHA-1 beginning with two specific byte values. This technique can also be combined with single-stepping, by setting a breakpoint on that conditional debug output, saving a lot of time to get back to the same point after modifying and recompiling the source code.
There exist even more problematic situations when working on Git for Windows, though: when trying to figure out issues in the MSys2 runtime, there might not be any `fprintf(...)` functionality available at that point of execution (yet). In this case, you need to revert to the plain Win32 API to write into a file:
There exist even more problematic situations when working on Git for Windows, though: when trying to figure out issues in the MSYS2 runtime, there might not be any `fprintf(...)` functionality available at that point of execution (yet). In this case, you need to revert to the plain Win32 API to write into a file:
```c
...
@ -97,4 +97,4 @@ CloseHandle(h);
} }
```
Of course, if it is possible to write to `stderr` instead, the code should use `HANDLE h = GetStdHandle(STD_ERROR_HANDLE);` instead of the `CreateFile()` call instead, and *not* close the handle...
Of course, if it is possible to write to `stderr` instead, the code should use `HANDLE h = GetStdHandle(STD_ERROR_HANDLE);` instead of the `CreateFile()` call instead, and *not* close the handle...

10
Updating-your-SDK.md

@ -12,10 +12,10 @@ with 7-Zip need to run that batch file manually, too. The script is
extensively commented to assist in understanding the installation process
and issues.
The files contained in the net installer are parts of MSys2's
The files contained in the net installer are parts of MSYS2's
'msys2-runtime', 'pacman' and 'gnupg' packages, carefully selected to
keep the size of the installer small yet still allowing to use the
Pacman package manager to initialize a full-fledged MSys2 environment
Pacman package manager to initialize a full-fledged MSYS2 environment
plus Git for Windows' packages.
The bootstrap script needs to force-install the packages because the net
@ -27,7 +27,7 @@ therefore refuse to overwrite the files from above-mentioned packages.
To keep the development environment up-to-date, developers need to run
update-core
# If core-packages are updated during that call you MUST restart MSys2
# If core-packages are updated during that call you MUST restart MSYS2
pacman -Syu
from time to time.
@ -37,7 +37,7 @@ from time to time.
Core packages like the `msys2-runtime`, `bash` or `pacman` itself should be updated
via the pacman `update-core` script. Because those core packages are linked to the
`msys2-runtime` (and each other), and updating the runtime "in flight" results most
often in heap corruption as far as MSys2 is concerned.
often in heap corruption as far as MSYS2 is concerned.
## Alternative Method
@ -62,4 +62,4 @@ project when it was still based on MSys 1.x. At that time, MSys 1.x did
not have a package manager, therefore the original net installer
(ab-)used Git as a package manager.
Since the new net installer no longer needs to ship with Git (instead using Pacman to install all the packages (including the `mingw-w64-git` package) that are current at the time the net installer is launched), its versions are no longer tightly coupled to the Git version.
Since the new net installer no longer needs to ship with Git (instead using Pacman to install all the packages (including the `mingw-w64-git` package) that are current at the time the net installer is launched), its versions are no longer tightly coupled to the Git version.