GitGitGadget

Mon, 01 Jan 0001 00:00:00 +0000

32-bit

Mon, 01 Jan 0001 00:00:00 +0000

32-bit support of Git for Windows

While Git for Windows v1.x was only ever offered as 32-bit installer (i.e. targeting the i686 CPU architecture), with the switch of Git for Windows v2.x in August 2015 to depend on MSYS2, there have been two variants: the 32-bit and the 64-bit (x86_64) one.

However, due to Git for Windows’ reliance on the MSYS2, which dropped 32-bit support (the 32-bit version of the MSYS2 runtime cannot even be built as of version 3.4.0), Git for Windows started to phase out 32-bit support after Git for Windows v2.40.x.

Adding regression tests

Mon, 01 Jan 0001 00:00:00 +0000

Git comes with an extensive regression test suite. It lives in the t/ subdirectory 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).

Auto launching ssh agent when git starts

Mon, 01 Jan 0001 00:00:00 +0000

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.

Backporting upstream Git patches

Mon, 01 Jan 0001 00:00:00 +0000

How to backport a patch (series) that was contributed to upstream Git

Git for Windows’ release cadence closely follows the release cycle of the “upstream” Git project.

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.

Building Git

Mon, 01 Jan 0001 00:00:00 +0000

Building Git on Windows

We build Git for Windows using an MSYS2 based Git for Windows SDK. This SDK can be installed via the SDK installer

Installing a build environment

Just run the SDK installer.

Build Git

An initial git clone and make should have already occurred when running the SDK installer.
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.

Building msys2 runtime

Mon, 01 Jan 0001 00:00:00 +0000

Installing a build environment

Download and run the Git for Windows SDK installer.

Building msys2-runtime

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>).
From the MSys shell do: sdk build msys2-runtime

This last step may take a while, so please be patient!

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.

Building new package versions

Mon, 01 Jan 0001 00:00:00 +0000

As described in Package management, Git for Windows’ SDK is a close derivative of the MSYS2 system, and as such, its components are built using makepkg and makepkg-mingw (borrowed from Arch Linux’ pacman).

Most of those packages are actually built by the MSYS2 project and consumed by Git for Windows. However, a couple of components (including cURL and OpenSSH) are built by Git for Windows, e.g. to be able to react faster to newly-available versions, or to allow for modifications specific to Git for Windows.

Choosing the default behavior of `git pull`

Mon, 01 Jan 0001 00:00:00 +0000

Choosing the default behavior of `git pull`

TL;DR

The git pull command offers different default behaviors. This guide clarifies the differences between these settings. Essentially, this installer screen configures what happens when you type a plain git pull in your terminal. It sets a global preference so you don’t have to manually type flags (like --rebase).

You can change your choice later with the git config command.

What does `git pull` actually do?

Behind the scenes, git pull is a two-step command. It first runs git fetch to download the latest commits from the remote, then it integrates those commits into your current branch. The three options on the installer screen only affect the second step.

Compiling Git with Visual Studio

Mon, 01 Jan 0001 00:00:00 +0000

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`

[!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.

Git’s source code (and hence also Git for Windows’ source code) is usually built using GNU C and GNU Make in a Git for Windows SDK.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

How to contact the Git for Windows project

Please state the nature of your medical emergency.

I found a bug!

Please follow our guide lines on reporting bugs.

I have a question!

We have GitHub Discussions. If, for some reason or other, you prefer a mailing list, use the Git mailing list.

But I really have only a quick question!

Ask away on Discord.

But I would prefer to email somebody directly!

Please keep in mind that the time of competent Open Sourcerers is better spent on communicating publicly.

Continuous Integration (CI)

Mon, 01 Jan 0001 00:00:00 +0000

All of Git for Windows’ CI builds happen in GitHub Actions:

git
git-for-windows-automation
There are also various automated runs in other repositories in Git for Windows’ org

Debugging Git

Mon, 01 Jan 0001 00:00:00 +0000

Debugging Git using the GNU debugger (GDB)

First of all, Git’s .exe files should be rebuilt with debugging information, and without optimization (because gdb has serious troubles single-stepping code compiled using -O2 for some reason). To this end:

install the Git for Windows SDK
Create /usr/src/git/config.mak with the following contents to disable compiler optimization and ASLR:

DEVELOPER=1
ifndef NDEBUG
CFLAGS := $(filter-out -O2,$(CFLAGS))
ASLR_OPTION := -Wl,--dynamicbase
BASIC_LDFLAGS := $(filter-out $(ASLR_OPTION),$(BASIC_LDFLAGS))
endif

run make in /usr/src/git/.

After that, you can run Git’s executables in GDB like so:

Diagnosing performance issues

Mon, 01 Jan 0001 00:00:00 +0000

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

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. However, the MINGW version of the GCC tools offered by MSYS2 has been known to produce empty output on occasion.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Which versions of Windows are supported?

Git for Windows currently works with all recent, commercially released x64 versions of Windows, starting with Windows 8.1.

[!IMPORTANT] Git for Windows version 2.46.2 was the last version supporting Windows 7 and 8.

[!IMPORTANT] Git for Windows version 2.40.1 was the last version with full support for any 32-bit Windows version.

[!IMPORTANT] Git for Windows version 2.37.1 was the last version supporting Windows Vista and Server 2008.

File names, Branch names, Path quotation, Executable bit and file modes, core.FileMode

Mon, 01 Jan 0001 00:00:00 +0000

Case Preservation, Case insensitivity

Windows is case insensitive, but case preserving for filenames. Meanwhile Linux/Posix, for which Git is designed, is case sensitive.

In addition Git branch names are stored as filenames.

This means that in normal usage, Git will have difficulty when it meets a changed case file or branch. Lower case is common for Linux usage!

E.g. Main branch and main branch are different, even though, on Windows, Git will often mistake one for the other (because Windows will read the ‘other’ case version of the file.

Git cannot create a file or directory with a long path

Mon, 01 Jan 0001 00:00:00 +0000

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

For this reason, long paths support in Git for Windows is disabled by default.

That being said, long paths support for C-based git commands can be enabled by setting the core.longpaths option to true. Scripted git commands may still fail with this option, so use at your own risk. Example:

Git wrapper

Mon, 01 Jan 0001 00:00:00 +0000

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”. 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.

Good commits

Mon, 01 Jan 0001 00:00:00 +0000

Please note that it is a best practice embraced by us to craft elegant, well-separated commits. Each commit is kind of its own little story, so if you make a typo fix, that is its own commit. If you add documentation, that is another commit. If you have multiple typo fixes, you could consider to put them into the same commit, depending on your taste.

In short, make sure that commits are logical units of changes.

governance-model

Mon, 01 Jan 0001 00:00:00 +0000

Git for Windows governance model

Overview

Git for Windows is led by a benevolent dictator (Johannes Schindelin) and managed by the community. That is, the community actively contributes to the day-to-day maintenance of the project, but the general strategic line is drawn by the benevolent dictator. In case of disagreement, they have the last word. It is the benevolent dictator’s job to resolve disputes within the community and to ensure that the project is able to progress in a coordinated way. In turn, it is the community’s job to guide the decisions of the benevolent dictator through active engagement and contribution.

How to participate

Mon, 01 Jan 0001 00:00:00 +0000

You want to contribute? Great. Here’s how!

There are several ways to participate in the Git for Windows project. First off, have a look at the governance model of the project.

Help users

In Git for Windows’ discussions or on the issue tracker, help is always welcome.

Add documentation

A lot of documentation wants to be written, still. A good place is Git for Windows’ home page. Tutorials, step by step instructions and general background information, etc. Even just keep the links up to date and reporting inconsistencies is helpful.

Install inside MSYS2 proper

Mon, 01 Jan 0001 00:00:00 +0000

Please note that this scenario is not officially supported by Git for Windows

[!IMPORTANT] You shouldn’t need this anymore. We’ve worked with MSYS2 to make mingw-w64-git available directly in MSYS2. Of the packages mentioned here only mingw-w64-git-extra isn’t available in MSYS2.

Git for Windows being based on MSYS2, it’s possible to install the mingw-w64-git package into an existing MSYS2 installation. That means that if you are already using MSYS2 on your computer, you can use Git for Windows without running the full installer or using the portable version. There are some caveats for going this way, details below. Reading the whole guide before starting is recommended.

Install or update inside MSYS2, Cygwin or Git for windows itself

Mon, 01 Jan 0001 00:00:00 +0000

It’s different from Install inside MSYS2 proper

Instead of configuring and installing Git for Windows using pacman, this guide introduces another approach to properly install or update Git for Windows inside MSYS2, Cygwin or even Git for Windows itself. The only thing you need is a bash interpreter on Windows and a curl.

How to

With the script getgit introduced by git-for-windows/build-extra#261, you can download and run the script or just run curl https://raw.githubusercontent.com/git-for-windows/build-extra/HEAD/git-extra/getgit | bash.

Issue reporting guidelines

Mon, 01 Jan 0001 00:00:00 +0000

Search Existing issues & pull requests, both open and closed. Determine whether or not a bug report has been dispatched. What is the status of the report? Are there any other bugs to be looked at? If so issue another bug report.
Include the output of the git --version in addition to the Windows version as that information is often necessary to reproduce the issue. When reporting problems involving a server, include the same information for the server side (insofar possible). Likewise, please mention if you use 32-bit Windows, or a 32-bit version of Git on a 64-bit Windows. If in doubt, try to provide more information rather then less; It’s better than leaving a lot of guess work! :)
Describe the options used when installing Git for Windows, and the console type/window (if any).
If your setup is different from “normal” setups in any way, it is a good idea to put specifics about that into your bug report, too.
Describe your issue properly. If you spend 30 seconds throwing out a sloppy report, do expect that others will spend exactly the same amount on trying to resolve it. In contrast, if you write a complete and pleasantly informative bug report, you will almost certainly be rewarded by excellent help with your problem.
Include a Minimal, Complete, and Verifiable example using GitHub Markdown’s codeblock delimiters.
If your issue stems from a particular repository include its URL. If the repository is proprietary try to create a public test repository showing the same issue.
Be prepared to test fixes!
Be polite. You are asking highly competent software developers for help, for free, so you might want to avoid treating them as if they were a commodity or at your free disposal.
An example for an outstanding report can be found here. You may want to imitate the level of detail.
For further inspiration, read reports that were resolved successfully, http://www.chiark.greenend.org.uk/~sgtatham/bugs.html, http://stackoverflow.com/questions/how-to-ask and http://whathaveyoutried.com/.

Making a portable Git

Mon, 01 Jan 0001 00:00:00 +0000

As the portable Git is made by putting together files from the Git SDK, it is advisable to update those files first. To update the packages, call pacman -Syu (caveats apply). If you want to test Git changes or make an portable Git from your own Git fork, you need to call cd /usr/src/git && make install (for documentation changes, make install-html and afterwards prefix=/mingw64 make -C contrib/subtree install-html - without the second make you get a error message about a missing git-subtree.html file).

Making an installer

Mon, 01 Jan 0001 00:00:00 +0000

Making a Git for Windows installer

The quick way

Download the Git for Windows SDK, install it and run sdk build installer.

If you need to include a Git version built with custom patches, call sdk cd git, then make sure that it is at the commit you want, then call sdk build git-and-installer.

Debugging/Developing a single installer “wizard page”

Sometimes the wording needs to be changed, or the layout, or something, in a single page of the installer. To avoid having to build the entire installer (and compressing all of Git for Windows), run sdk cd installer and run ./release.sh -d <page>. For example, to modify the page where Git’s default editor can be configured, run this:

Mapping between Git Installer GUI Settings And Command Line Arguments

Mon, 01 Jan 0001 00:00:00 +0000

The following table maps Git GUI Installation settings to corresponding Git Command Line Installation arguments:

Screenshot	Available Arguments (in sequence)	Example Arguments
	`Components=` `icons` `ext\reg\shellhere` `gitlfs` `assoc` `assoc_sh` `windowsterminal` `scalar`	`Components=gitlfs,scalar`
	`EditorOption=` `Nano` `VIM` `Notepad++` `VisualStudioCode` `VisualStudioCodeInsiders` `SublimeText` `Atom` `VSCodium` `Notepad` `Wordpad` `CustomEditor`	`EditorOption=VisualStudioCode`
	`DefaultBranchOption=` {branch name}	`DefaultBranchOption=main`
	`PathOption=` `BashOnly` `Cmd` `CmdTools`	`PathOption=Cmd`
	`SSHOption=` `OpenSSH` `ExternalOpenSSH` `Plink`	`SSHOption=ExternalOpenSSH`
	`CurlOption=` `OpenSSL` `WinSSL`	`CurlOption=WinSSL`
	`CRLFOption=` `CRLFAlways` `LFOnly` `CRLFCommitAsIs`	`CRLFOption=CRLFAlways`
	`BashTerminalOption=` `MinTTY` `ConHost`	`BashTerminalOption=ConHost`
	`GitPullBehaviorOption=` `Merge` `Rebase` `FFOnly`	`GitPullBehaviorOption=Merge`
	`UseCredentialManager=` `Enabled` `Disabled` `Core`	`UseCredentialManager=Enabled`
	`PerformanceTweaksFSCache=` `Enabled` `Disabled` `EnableSymlinks=` `Auto` `Enabled` `Disabled`	`PerformanceTweaksFSCache=Enabled` `EnableSymlinks=Disabled`
	`EnablePseudoConsoleSupport=` `Auto` `Enabled` `Disabled` `EnableFSMonitor=` `Auto` `Enabled` `Disabled`	`EnablePseudoConsoleSupport=Disabled` `EnableFSMonitor=Enabled`

For a comprehensive list of Git for Windows Installer command line arguments see here.

Merge Conflicts Resolving and Remembering them

Mon, 01 Jan 0001 00:00:00 +0000

Work in Progress as I try and work out how to do this (06-04-2019)..

When building a new release for Git-for-Windows, the full range of Windows patches the maintainer applies need to be moved (rebased) from being on top of the old upstream Git, to being on top of the new upstream release.

There is a process, a script and the support of the merging-rebase code, but still there maybe conflicts, old and new, especially if some of the Windows code has been adopted upstream in a different form.

MinGit

Mon, 01 Jan 0001 00:00:00 +0000

MinGit is Git for Windows Applications

Rationale

Git for Windows targets end users, and for a long time third-party applications that spawn git.exe in order to provide Git-specific functionality piggy-backed onto the end-user installation.

However, for third-party applications it can be quite important to target certain minimum Git versions, e.g. when features such as git reset --stdin are needed that were introduced only recently.

Bundling a complete portable Git for such cases may very well be overkill, as the applications that want to call Git usually do not require all of Git for Windows’ functionality, especially not the interactive features including Git GUI and Git Bash.

MSYS2 Notes

Mon, 01 Jan 0001 00:00:00 +0000

Page for things that pop up while fiddling with MSYS2.

PS1 script

I had to replace PS1="$PS1"'\n' with PS1="$PS1"$'\n' within the profile file to get the git prompt working. See also this msys2 ticket page

PS1 Script (continuation)

If you have this error (or something alike) with a prompt like this one: \e[0;36m[\e[1;36m\t\e[0m\e[0;36m]\e[0m \e[0;33m\w\e[0m$(__git_ps1 ' \e[0;31m(\e[1;31m%s\e[0m\e[0;31m)\e[0m')\n$, then you will have to replace the $(...) syntax by backtick (`).

This PS1 will do the following error:

OpenSSH Integration with Pageant

Mon, 01 Jan 0001 00:00:00 +0000

For some users, it may be desirable to tie OpenSSH in to the PuTTY authentication agent (Pageant) using ssh-pageant. This is a drop-in replacement for ssh-agent, which simply builds a connection between OpenSSH and Pageant for key-based authentication. The tool makes it easy to leverage OpenSSH for remote repository access, which tends to be the most reliable choice within the specific context of Git for Windows (Git), without the need to run multiple agents which don’t interoperate.

Package management

Mon, 01 Jan 0001 00:00:00 +0000

Git for Windows’ package management

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 for Linux, homebrew for macOS, maven for Java and pip for Python.

While Git for Windows is based on MSYS2 which bundles the Pacman tool (known from Arch Linux) for dependency management, the pacman.exe command is only bundled with the Git for Windows SDK, not the normal installer.

Performance profiling with Visual Studio

Mon, 01 Jan 0001 00:00:00 +0000

A very powerful method to identify performance bottlenecks is performance profiling. Visual Studio (including the free-of-cost Community edition) offers convenient tools for that via the Debug>Performance Profiler… menu entry.

This space intentionally left blank for volunteers to fill in walkthroughs with screenshots, and links for further reading

Analyze the performance of a Git command specified as a command-line

Open the “git.exe” file via File>Open
Specify the arguments and the working directory via Debug>git Properties
Debug>Performance Profiler…

Analyze executables compiled by GCC

Visual Studio obtains the debug information used in the output from “.pdb” files, but GCC does not generate debug information in that format.

Problems specific to 32-bit

Mon, 01 Jan 0001 00:00:00 +0000

Problems specific to 32-bit

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 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.

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).

Rebasing Git for Windows

Mon, 01 Jan 0001 00:00:00 +0000

Rebasing Git for Windows to a new Git version

To do a rebase of the Git for Windows source onto a new upstream Git release, follow this guideline.

Assumptions

You want to rebase onto a new upstream release tagged as v2.3.4
The latest rebase was done onto a upstream release tagged as v2.3.3
the origin/main below means remote https://github.com/git-for-windows/git, its main branch. You may have them named differently.

Preconditions

A working Git for Windows SDK.
A fetched build-extra repository. cd /usr/src/build-extra git fetch git checkout main (git pull if your branch is behind the upstream)
Working directory set to current Git for Windows source. cd /usr/src/git
Added upstream as a remote. git remote add git https://github.com/git/git git fetch git

Starting the rebase

Run the shears.sh script to build up the actual rebase script. /usr/src/build-extra/shears.sh --merging --onto v2.3.4 merging-rebase Note: v2.3.4 is a tag in the remote git. See the script if you are testing changes initiated in a local branch of the git upstream.

Release Hashes

Mon, 01 Jan 0001 00:00:00 +0000

Release hashes are detailed in:

the ANNOUNCE mail notifications on the Git mailing list and
on the https://github.com/git-for-windows/git/releases page.

The list can be read at https://lore.kernel.org/git/ and joined here.

Releasing Git for Windows

Mon, 01 Jan 0001 00:00:00 +0000

Git for Windows’ release process

The release process of Git for Windows is ever-evolving. For now, it consists of these steps:

Making sure that there are no unaddressed issues
Rebasing Git for Windows’ patches
Opening a PR to kick off a PR build (and waiting for it to succeed)
Kicking off the /git-artifacts slash command
Verifying that the resulting installer works
Kicking off the /release slash command that publishes the release
Pushing directly to main to close the PR and set the stage for the Azure Pipeline (at some stage during the -rc<N> cycle)

Note: the hardest part is traditonally preparing -rc0 of every major release.

requirements

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

This page lists the prerequisites required to run Git for Windows.

Windows version

Git for Windows requires Windows 8.1 or later on a 64-bit CPU (x64 or amd64). The last version to support Windows 7, 8, Server 2008 R2 and Server 2012 was v2.46.2. The last version to support Windows Vista and Server 2008 was v2.37.1. The last version of Git for Windows to support Windows XP and Windows Server 2003 is v2.10.0.

Running Git's regression tests

Mon, 01 Jan 0001 00:00:00 +0000

Git’s test suite

Running tests

Git’s source code ships with a lot of regression tests. This gives us a pretty good indicator of the source code’s health: if a regression test starts failing for a topic branch, it is safe to assume that there is some “room for improvement” in the changes introduced by said topic branch.

It is a good practice to add a regression test when fixing bugs. Such a test not only illustrates what is going wrong (and lets other developers verify that there is indeed a bug that needs fixing), it also ensures that it is much harder to re-introduce that bug by mistake in the future: the regression tests would sound an alarm.

Setting your Core.Editor (e.g. Notepad Plus Plus)

Mon, 01 Jan 0001 00:00:00 +0000

Many Windows users are not familiar with vi/vim/emacs style command line terminal editors. [To quit: type :q in the bottom bar and press Enter. If you’re typing into the file contents, press Esc first.]

Many users prefer their local Windows graphic editor, such as Notepad++, this note shows how.

Setting Notepad++ as your Core.Editor

Notepad++ provides multiple useful options (Npp online help. Install as required.

The command

git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noplugin"

Silent or Unattended Installation

Mon, 01 Jan 0001 00:00:00 +0000

Using Command-Line Options

It is possible to install Git for Windows silently using the following flags when called from a command-line prompt:

Git-<version>-<bitness>.exe /VERYSILENT /NORESTART /NOCANCEL /SP- /CLOSEAPPLICATIONS /RESTARTAPPLICATIONS /COMPONENTS="icons,ext\reg\shellhere,assoc,assoc_sh"

Using Installer Options From a File

You can also load install parameters from a file with /LOADINF="filename", and you can record parameters to a file using /SAVEINF="filename".

Example for saving selected options to a file during an interactive run started from the command-line:

Site Map

Mon, 01 Jan 0001 00:00:00 +0000

Site Map

Snapshot builds

Mon, 01 Jan 0001 00:00:00 +0000

Git for Windows’ main branch is kept in an always-releasable state as much as possible.

For example, in case that a critical bug is discovered that really needs to be fixed within the same day, Git for Windows does not have a maintenance branch (or, “stable” branch). Such a fix would be applied on top of main and a new version would be created from that state.

To allow users to help verifying that “always-releasable state”, as well as to allow users to verify fixes introduced via PRs, Git for Windows builds “snapshot” releases (published here) whenever the main branch advances.

Sourcetrail code viewer and linkage to Visual Studio, for Git

Mon, 01 Jan 0001 00:00:00 +0000

Sourcetrail is an interactive source explorer that simplifies navigation in existing source code. It is now open source. You can support them on Patreon.

This note is a quick start to setting up a Sourcetrail project for exploring the Git source code in conjunction with Visual Studio. Source trail is configurable and some parameter need to be set on initial project setup.

Git-for-Windows is available as a Visual Studio build in the main branch. Visual Studio will detect the CMakeLists.txt file in \contrib\buildsystems to build the project. See that file for instructions on generating the .sln and vcproj files needed for Sourcetrail and other VS Extensions. The VS project comprises ~19 sub-projects including ALL BUILD and libgit.
This was tested with the free VS2019 community edition.
Build the project in Visual Studio so that it’s vcpkg dependencies are downloaded and compiled (may take some time).
Download and install the Sourcetrail software. Check the documentation, especially the intro video.
Download and install the VS Sourcetrail Extension.

For Git, Sourcetrail will need it’s pre-processor dependencies which are numerous, so let’s extract them from Visual Studio. We need to collect the main preprocessor directives from libgit (which everything depends on) and git.

Symbolic Links

Mon, 01 Jan 0001 00:00:00 +0000

Git for Windows vs symbolic links

Short version: there is no exact equivalent for POSIX symlinks on Windows, and the closest thing is unavailable for non-admins by default unless Developer Mode is enabled and a relatively recent Windows 10 version is used. Therefore, symlink emulation support is only turned on by default when that scenario is detected. Support can be enabled by the user, via the core.symlinks=true config setting.

Background

Starting with Windows Vista, there is support for symbolic links. These are not your grandfather’s Unix symbolic links; they differ in quite a few ways:

Technical overview

Mon, 01 Jan 0001 00:00:00 +0000

Git for Windows is essentially a subset of MSYS2 with a defined set of installed packages of which a subset is included in the installer.

The process to build an instance of the Git for Windows installer is made easier with the Git for Windows SDK. Basically, the steps are as follows:

Download and install the SDK, which installs the sources for git, additional msys and mingw packages, and helpers to build the installer. It also provides the Git for Windows SDK MSys shell
[optional] Hack in the changes you want and make these changes available to the installer.
Call the right helper tools to build the package you want.

Installing the SDK

Download the SDK and run it (using “Run as Administrator”). You will end up with a console window running the Git for Windows SDK shell, which you can use for the next steps. You need to fetch the latest version of the Git sources - just run the command sdk init git. After that, if you just want to build an installer from the latest development, you are ready to go.

The difference between MINGW and MSYS2

Mon, 01 Jan 0001 00:00:00 +0000

tl;dr

MINGW refers to executables that are compiled using the MINGW GCC Compiler and target the Win32 API. MSYS2 refers to executables that are compiled by MSYS2 GCC Compiler and make use of a POSIX emulation layer.

Background

First of all, it needs to be noted that many parts of Git are not written in portable C; Git relies on a POSIX shell and Perl to be available instead.

Git for Windows 1.x (MINGW and MSys)

To support the scripts, Git for Windows has to ship a minimal POSIX emulation layer with Bash and Perl thrown in, and when the Git for Windows effort started in August 2007, it used MSys, a stripped down version of Cygwin. Consequently, the original name of the project was “msysGit” (which, sadly, caused a lot of confusion because few Windows users know about MSys, and even less care).

Updating your SDK

Mon, 01 Jan 0001 00:00:00 +0000

Installing the SDK

The Git for Windows SDK release is a self extracting and auto executing 7-zip archive that clones the latest version of files in Git for Windows SDK 64 repository using a temporary bundled git. For the 32 bit version it also performs a run time optimisation on cloned DLLs (rebase).

This was previously called the ’net installer’, see below. It provides everything required to bootstrap a development environment, even if no git is available (or an unstable one is being worked on).

Upgrading the `perl` component to a new version

Mon, 01 Jan 0001 00:00:00 +0000

One of the many components included in Git for Windows’ SDK is the perl package. Part of its components are included in Git for Windows’ installer and Portable Git versions, to allow for running Perl scripts. The two most prominent Perl scripts in Git for Windows are, of course, git svn and git send-email.

Upgrading to a new Perl version is unfortunately a bit more involved than only following the advice in Building new package versions. In addition to adjusting the patches applied via the PKGBUILD script, the major problem with Perl is that its DLL embeds the Perl version in its file name.

Using an external OpenSSH client

Mon, 01 Jan 0001 00:00:00 +0000

OpenSSH on Windows 10

Modern versions of Windows and Windows Server come with OpenSSH installed, and available on the system PATH. By default, the OpenSSH binaries are located in C:\WINDOWS\System32\OpenSSH\.

The ssh-agent is also implemented as a Windows service, allowing it to be run automatically, during boot or login, and so on.

NOTE: By default the ssh-agent service is disabled, and if its use required — to manage your private keys, for instance — it will need to be explicitly enabled, and then started (or configured to start as necessary).

Using sshd to host a git server

Mon, 01 Jan 0001 00:00:00 +0000

Everything you need to host a git server on Windows is included with Git for Windows. In these instructions it is assumed that Git for Windows is installed at %GIT_HOME% and that you have %GIT_HOME%\cmd in your path on both client and server machines.

Configure sshd

You need to create a key pair within %GIT_HOME%\etc\ssh for sshd to use as the server identity, e.g. ssh_host_rsa_key and ssh_host_rsa_key.pub files.

Here is a good description of how to create the key pair: http://www.geekride.com/how-to-generate-ssh-host-keys/

Vagrant

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Vagrant is a modern way to define the requirements of a project. In the case of Git for Windows, it allows us to set up a minimal virtual Linux machine that makes it easy to run the same revision of Git on Windows as well as on Linux without much effort.

Note: while Vagrant makes things easy, quite a bit of bandwidth is required for the setup (roughly a gigabyte will be downloaded in total).

Versioning

Mon, 01 Jan 0001 00:00:00 +0000

Git for Windows is a fork of Git, and therefore follows Git’s versions. Therefore, whenever a new Git version comes out, we release a new Git for Windows version whose version number is derived from Git’s. Example: short after Git v2.29.0 was released, Git for Windows v2.29.0 was released.

Sometimes, Git for Windows needs to release intermediate versions that do not follow a release by the Git project. For example, in November 2020 a new Git LFS version was released that fixed a critical security bug. Since Git for Windows ships with Git LFS included and enabled by default, we had to quickly release a new Git for Windows version, too. We called the corresponding tag v2.29.2.windows.2 and the version “v2.29.0(2)” (the first part of the version still indicates the upstream Git version, and the number in parentheses indicates the iteration of Git for Windows on top of that, and that number is identical to the suffix of the tag name).

Visual Studio and MSVC compilation

Mon, 01 Jan 0001 00:00:00 +0000

This page curates tidbits regarding the use of Microsoft tools when editing or creating a personal version of Git.

You can comple Git using the MSVC compiler, or create a Visual Studio project for Git.

As Git upstream develops, the MSVC and VS projects can get left behind, so this page is to help folk keep up to date, keep testing, reporting breakages, and hopefully offering fixes or at least a bit of analysis using their favourite tool (you’re here, so it must be..)

Why Git for Windows does not work with Mandatory Address Space Layout Randomization

Mon, 01 Jan 0001 00:00:00 +0000

A common source for exploits has been to cause buffer overflows. When executables are loaded to the same address range every time they are launched, such buffer overflows can rely on encountering the same scenario every time, which makes it easier to exploit them.

To remedy that, Address Space Layout Randomization (ASLR) has been invented. Essentially, it causes executables and dynamic libraries to be loaded into somewhat random memory locations, making the common buffer overflows much harder to exploit. There is even an option to require all programs to use ASLR, whether the executables indicate that they want that or not: Mandatory ASLR.

Wiki

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Git for Windows originally had a wiki, meant for more technical information than was presented on its home page. To prevent vandalism from going unnoticed for weeks, that wiki had to be shut down. It is still possible to edit these pages, though, via Pull Request in the repository. See also the documentation how you can contribute.

About

Git for Windows is very different from Git in one very important respect: As Windows does not provide the POSIX infrastructure Git expects, Git for Windows always had to ship with much more than any other Git distribution: provide a bash, a perl, many POSIX tools such as sed, awk, tr, etc.

Windows-vs-Linux-fork()/exec()-semantics

Mon, 01 Jan 0001 00:00:00 +0000

TL;DR

Traditionally, you needed to make 2 separate calls to create new process in Linux: fork() and then exec(). Windows has a different way, using a single call (CreateProcess()), and doesn’t support fork(). Software originally written for Linux has to use an emulated (way slower and somewhat imperfect) fork() to run on Windows. If this software creates a lot of processes during its normal workload, it will then run noticeably slower on Windows than on Linux.

Zip Archives extracting the released archives

Mon, 01 Jan 0001 00:00:00 +0000

The self-extracting 7z archives that are currently released (e.g. for the portable version) can easily be installed in a headless manner using the extraction options.

The self-extracting 7z archives are far more compact than regular .zip archives as the compaction is done across the whole content, rather than file by file, which would make .zip files inconveniently large.

For a quiet extraction of the archive from the command line:

> .\PortableGit-2.11.0-64-bit.7z.exe -y -gm2 -InstallPath="C:\\use\\double\\backslashes"

We use the old .sfx component that used to be hosted on http://7zsfx.info. This provides more options for a fully quiet extraction - as shown, in this case:

GitGitGadget

32-bit

32-bit support of Git for Windows

Adding regression tests

Adding test cases

Auto launching ssh agent when git starts

Backporting upstream Git patches

How to backport a patch (series) that was contributed to upstream Git

Building Git

Building Git on Windows

Installing a build environment

Build Git

Building msys2 runtime

Installing a build environment

Building msys2-runtime

Rebuilding the msys2-runtime

Building new package versions

Choosing the default behavior of `git pull`

Choosing the default behavior of git pull

TL;DR

What does git pull actually do?

Compiling Git with Visual Studio

Compiling Git with Visual Studio

Checking out vs/main

Contact

How to contact the Git for Windows project

I found a bug!

I have a question!

But I really have only a quick question!

But I would prefer to email somebody directly!

Continuous Integration (CI)

Debugging Git

Debugging Git using the GNU debugger (GDB)

Diagnosing performance issues

How to diagnose when Git for Windows is slow

Identify specific Git commands’ performance issues

FAQ

Which versions of Windows are supported?

File names, Branch names, Path quotation, Executable bit and file modes, core.FileMode

Case Preservation, Case insensitivity

Git cannot create a file or directory with a long path

Git for Windows vs long paths

The problem

Opt-In configuration

Git wrapper

What is the “Git wrapper”?

Good commits

governance-model

Git for Windows governance model

Overview

How to participate

You want to contribute? Great. Here’s how!

Help users

Add documentation

Install inside MSYS2 proper

Please note that this scenario is not officially supported by Git for Windows

Install or update inside MSYS2, Cygwin or Git for windows itself

It’s different from Install inside MSYS2 proper

How to

Issue reporting guidelines

Making a portable Git

Making an installer

Making a Git for Windows installer

The quick way

Debugging/Developing a single installer “wizard page”

Mapping between Git Installer GUI Settings And Command Line Arguments

Merge Conflicts Resolving and Remembering them

MinGit

MinGit is Git for Windows Applications

Rationale

MSYS2 Notes

PS1 script

PS1 Script (continuation)

OpenSSH Integration with Pageant

Package management

Git for Windows’ package management

Performance profiling with Visual Studio

Analyze the performance of a Git command specified as a command-line

Analyze executables compiled by GCC

Problems specific to 32-bit

Choosing the default behavior of `git pull`

What does `git pull` actually do?

Checking out `vs/main`