Using Git on Windows

Preamble

On Windows Git runs via an MSYS shell which is installed with Git. But to run the DMD test-suite you need to have an MSYS installation that has some tools which are missing from the Git MSYS system. Therefore you need a separate MSYS install. Additionally, using the MSYS shell from a Windows command prompt is difficult (lack of easy copy and paste functionality, tiny fonts, limited window size, etc..).

By using Console2 you can improve your workflow with Git.

Requirements

Download Console2 and extract it somewhere.

Download MSYS and install it.

Setting up Console2

Set up a Git Tab

Run Console2, open the Edit->Settings menu, and select the Tabs tree on the left. Click on the Add button and then set a Title (e.g. Git). Set the Shell to C:\Program Files\Git\bin\sh.exe --login -i (or wherever you've installed Git). You can set the Startup dir so you're always ready to cd to a project and start using Git.

You can now use CTRL+F1 to open this tab (configurable in settings).

Set up an MSYS Tab

Click the Add button again, and set the Title to e.g. msys. Set the Shell to C:\msys\1.0\bin\sh.exe --login -i (or wherever you've installed MSYS). Note that using the Startup Dir may not work, but there's a workaround.

Working with git-head and release versions of DMD, Druntime and Phobos

A simple way to work with both an existing D installation and git-head is to have two DMD folders, both of which are in the PATH environment variable, e.g.:

C:\dmd2    # A release version of DMD
C:\dmd-git # the src subdir inside contains git-head of dmd, druntime and phobos

To create and fully prepare the dmd-git folder you can take these steps:

1. Fork DMD/Druntime/Phobos on Github (fork the ones you intend working on, or all if you want to)
2. Copy the existing dmd2 dir and rename it to dmd-git
3. Delete everything in the dmd-git\src directory
4. Open the Git Tab (CTRL+F1), enter the src directory and clone your forks (replace YourUserName accordingly):

cd /c/dmd-git/src

git clone git@github.com:<YourUserName>/dmd.git
cd dmd
git remote add upstream https://github.com/dlang/dmd
cd..

git clone git@github.com:<YourUserName>/druntime.git
cd druntime
git remote add upstream https://github.com/dlang/druntime
cd..

git clone git@github.com:<YourUserName>/phobos.git
cd phobos
git remote add upstream https://github.com/dlang/phobos
cd..

Then set C:\dmd2\windows\bin and C:\dmd-git\windows\bin so they're both in PATH. You can put the release version in PATH before the git version so it overrides it. When you work on the git-head version rename the release version (e.g. dmd2 to dmd2_) so the git-head version is picked up over the release version when running dmd from a console window.

Set up the MSYS startup dir and aliases

You should have a profile file in the C:\msys\1.0\etc folder. Open it in a text editor and change cd $HOME$ to the test subdir of wherever you're keeping a local clone of DMD, e.g.:

cd /c/dmd-git/src/dmd/test

You can also add some aliases to simplify running the DMD test-suite:

alias tclean="make clean"
alias tall="make DMD=/c/dmd-git/windows/bin/dmd"
alias tfail="make DMD=/c/dmd-git/windows/bin/dmd run_fail_compilation_tests"
alias tcomp="make DMD=/c/dmd-git/windows/bin/dmd run_compilable_tests"
alias trun="make DMD=/c/dmd-git/windows/bin/dmd run_runnable_tests"

Now when you open the MSYS Tab (e.g. CTRL+F2) you can immediately begin running the test-suite by entering tall.

Note: The DMD environment variable must be either an absolute or relative path, e.g. /absolute/path/to/dmd.exe or ../dmd.exe, using DMD=dmd.exe will not work.

Set up a 3rd party diff tool with Git

As an example, to use BeyondCompare as your diff editor on command you can edit your .bashrc file (usually located in your Documents and Settings\YourName folder) and add some aliases:

# diff all changes in the dir, optionally followed by an argument
alias bdiff='git difftool --dir-diff'

# diff only cached changes (staging area)
alias bcdiff='git difftool --dir-diff --cached'

# diff the head commit with the previous commit
alias bhdiff='git difftool --dir-diff head~1'

The first command allows you to diff between specific revisions, e.g. bdiff head 8f9ee7b11. The others are there just for convenience.

Additionally you will have to add these lines to your .gitconfig file (located in the same dir as .bashrc):

[diff]
	tool = bc3
[difftool "bc3"]
	path = c:/program files/beyond compare 3/BCompare.exe

Ensure you set the right path to BCompare.exe. Note that you need to use BCompare.exe rather than BComp.exe, since the latter will not block Git while viewing the diff and will make git delete the temporary diff files before you can view them.

Checking out pull requests

If you want to test other people's pull requests you can define a function in your .bashrc file (usually located in your Documents and Settings\YourName folder):

# note: the function opening brace must be followed by a newline and indentation
# fetch a pull request
function getpull() {
    git fetch upstream pull/$1/head
    git checkout pull$1 2> nul || git checkout -b pull$1
    git reset --hard FETCH_HEAD
}

This will allow you to quickly fetch and checkout a pull request by calling getpull 1234. (replacing 1234 with the pull request number). If you've already called this command and the pull request author has updated his commits, you can call getpull 1234 again to get the latest version of the pull request.

Another way of checking out pull requests locally is described here: https://gist.github.com/piscisaureus/3342247

Building DMD git-head

Once you have your C:\dmd-git\src\dmd clone prepared, you can add a build script to simplify building DMD and copying it to the windows\bin directory. Add this build.bat file to C:\dmd-git\src\dmd\src:

@echo off
:: Uncomment this to clean out the dir to force rebuilding entire DMD (typically required when you have linking errors)
:: make -f win32.mak clean > nul 2>&1
make -f win32.mak > log.txt && copy dmd.exe C:\dmd-git\windows\bin\dmd.exe /Y > nul
if errorlevel 1 GOTO ERROR
goto :CONTINUE

:ERROR
type log.txt
goto :EOF

:CONTINUE
:: These are examples of automatically running DMD (e.g. when developing and testing some code):

:: Run dmd on a test-file
cd C:\dfiles\ && dmd Fix2171.d

:: Run dmd from the windbg debugger (useful during an access violation or assert(0))
:: Tip: use F5 in windbg to run DMD, use "k" to show the stack trace
:: Tip: In newer versions of windbg you need to use "g" before "k" to show the proper stacktrace
cd C:\dfiles\ && windbg dmd Fix2171.d

:: When testing ddoc you probably want to generate an html file
cd C:\dfiles\ && dmd -D -w -o- -c ddoc1000.d

You also need to add this file (and the log file) to your local exclude file. Open the C:\dmd-git\src\dmd\.git\info\exclude file, and add these lines:

src/build.bat
src/log.txt

To build DMD run build.bat, this will copy DMD to your windows\bin directory or print out an error.

Note that you typically need a fresh version of Phobos in order to use the new DMD.

Building Phobos git-head

Building Phobos requires building Druntime first. The workflow is typically:

cd C:\dmd-git\src\druntime
make -f win32.mak

cd ..\phobos
make -f win32.mak && copy phobos.lib C:\dmd-git\windows\lib\phobos.lib /Y > nul

When you build Phobos, Druntime is included into the phobos.lib library.

Editing Environment Variables

You can use the freeware Rapid Environment Editor to edit the PATH and other environment variables. Remember that after editing the environment variables you may need to re-login so the system can pick up the new changes.

Common Issues

See Building DMD