Back to developer page.

Git

Our Git workflow (work in progress)

Outcome of the discussion in the Fast Downward meeting on 21 February:

• we want to use branches for issues and basically follow our previous Mercurial workflow, i.e., have one feature branch for each issue
• when integrating branches into master, we do not squash commits and we do not fast forward, i.e., we want to preserve the non-linear history of commits and always have a proper merge commit for the integration
• we delete branches (the pointer) after integration
• to identify commits on a branch, we prepend "[issue999] " to all commits of the branch issue999

  • [Jendrik] Thankfully, this can be automated (https://stackoverflow.com/questions/5894946/how-to-add-gits-branch-name-to-the-commit-message, https://gist.github.com/bartoszmajsak/1396344)

  • We want to use the "[main] " prefix for commits to the main branch.

• We want to use GitHub's autolink feature to link from commit messages to the issue tracker (https://help.github.com/en/github/writing-on-github/autolinked-references-and-urls).

Best practices:

• TODO: git bisect with --first-parent etc. (Malte sent a few links)
• TODO: how to configure git + meld
• TODO: can we use github's facilities on the webpage for, e.g., merging pull requests or does this do "wrong" things?

Suggested workflow:

• git checkout -b issue999
• ...
• git commit -m "[issue999] some changes"
• ...

• git tag issue999-base <rev>

• git tag issue999-v1 <rev>

• git push --set-upstream origin issue999 --tags
• ...
• git checkout main
• git merge --no-ff issue999
• git branch -d issue999
• git push

.gitconfig file:

[merge]
tool = meld

[mergetool "meld"]
#cmd = meld "$LOCAL" "$BASE" "$REMOTE" --output "$MERGED"
cmd = meld "$LOCAL" "$MERGED" "$REMOTE" --output "$MERGED"

[diff]
tool = meld

[difftool "meld"]
cmd = meld "$LOCAL" "$REMOTE"

[difftool]
prompt = false

[alias]
ci = commit
st = status
meld = difftool

# aliases that match the hg in / out commands
out = !git fetch && git log FETCH_HEAD..
in = !git fetch && git log ..FETCH_HEAD

• [Silvan] I also found out that meld actually knows about hg/git, so instead of configuring above and typing hg meld/git meld, one could also just type meld .

• [Silvan] Unfortunately, I haven't found a way for git merge to automatically open meld instead of first doing an incomplete merge and then viewing the failed merge via hg mergetool, which, if configured as above to take $MERGED as the middle file, contains the failed merge in the >>>> ... <<<< ... format, which I really don't like. If anyone finds out how to let git automatically merge what it can and then immediately prompt the user via mergetool instead of requiring this to be called manually, and even better, without showing the failed merge, I would be very happy.

GitHub code protection

We decided to protect all branches on the main Fast Downward repository. This means that no force pushes are allowed and branches can't be deleted.

Interact with a Git repo from Mercurial

The hg-git tool allows to pull and push from and to a Git repository with Mercurial, allowing you use Mercurial for working on Git projects. It does so by converting all Git branches to Mercurial bookmarks and vice versa. Here is how to set it up:

sudo apt install python3-venv

mkdir hg-git
cd hg-git
python3 -m venv --prompt hg-git .venv
pip install -U pip wheel
pip install certifi==2020.6.20 dulwich==0.20.5 hg-git==0.9.0a1 mercurial==5.4.2 pkg-resources==0.0.0 urllib3==1.25.9

# Add to ~/.hgrc file:
[extensions]
hggit =

# Ensure that new Mercurial binary is found before system Mercurial:
sudo ln -s /path/to/hg-git/.venv/bin/hg /usr/local/bin/hg  # or adjust $PATH

(Instead of the last two steps, you could also define a Bash alias that calls the new Mercurial with the hg-git extension enabled, but this breaks tab completion for Mercurial. Details: tab completion breaks if the alias is not named "hg" or if the alias command contains spaces.)

Now you can clone a repository. Remember to update to a bookmark to make it follow your commits:

hg clone git+ssh://git@github.com/aibasel/downward.git
cd downward
hg update main

[tested with Ubuntu 18.04]