Get the Haiku Source Code / Pushing Patches to Haiku 101

Haiku’s source code is currently being hosted on a Git-based repository using Gerrit.

If you are already familiar with the pull request workflow as used, for example, on GitHub, you can find an overview of the differences in Gerrit user’s manual.

Anonymous access will allow anyone to download Haiku’s source code; However, the authenticated (non-anonymous) method is required for submitting patches.

Git Access - Anonymous testers

Build Tools:

git clone https://review.haiku-os.org/buildtools

Haiku:

git clone https://review.haiku-os.org/haiku

If you don’t care about the commit history and want to limit the download size, use the parameter --depth when cloning. For example, --depth 10 limits the history to the last 10 commits.

GitHub

If your Internet provider limits the websites you are allowed to use, you can use our mirror repositories on GitHub instead.

They are kept in sync with our main repository, however, these repositories do not have any Git tags, which the compiler uses to determine the revision of Haiku. To work around this limitation, you can use the HAIKU_REVISION build variable when building Haiku.

The commands for cloning the repositories from GitHub are:

Build Tools:

git clone http://github.com/haiku/buildtools.git

Haiku:

git clone http://github.com/haiku/haiku.git

Git Access - Contributors and patch submitters

So, you want to contribute to Haiku. That’s awesome, thank you for your interest! This section will include instructions for setting up your local Git environment, an account on our Gerrit instance, as well as some guidelines on how to work with other contributors to get your changes included. This guide assumes that you are new to contributing to open-source projects. If that is not the case, you can skip some of the sections.

A visual overview of our Git workflow

Configuring Git locally

A global Git configuration is stored in Git configuration directory (~/.git/ or for Haiku: ~/config/settings/git/) and will be included in every commit.

git config --global user.name "John Doe"
git config --global user.email "john.doe@example.com"

Although most contributors tend to disclose their real names, we do not have a real name policy and plenty of contributors contribute to Haiku using a pseudonym. You are not required to use your “real” name, a pseudonym is fine and several Haiku contributors chose to do that. However, make sure the e-mail address is correct and working, it is what we will use if we need to contact you later.

On macOS, you must set the following option in order to avoid problems with the unicode representation of filenames:

git config core.precomposeunicode true

Setup an account on Gerrit

Log in to Gerrit code review. For the time being, using a GitHub account is necessary.

Upload your SSH public key in the Gerrit SSH Keys settings page. If you don't have a key yet, you can generate one using ssh-keygen.

Cloning repositories from Gerrit

If the email address used in your commits does not match the one in your Github account, you will need to add and verify it in Gerrit email address settings.

This can happen if the username on your Gerrit account does not match the username that you use to log in to your computer. This would be the case in Haiku itself, as the default username is user.

$USER is an environment variable that is specific to Unix-like operating systems (e.g. Haiku, Linux, FreeBSD, etc.). If your system does not fall under that category, you will probably have to replace it.

Build Tools:

git clone "ssh://$USER@git.haiku-os.org/buildtools" && curl -Lo "buildtools/.git/hooks/commit-msg" https://review.haiku-os.org/tools/hooks/commit-msg

Haiku:

git clone "ssh://$USER@git.haiku-os.org/haiku" && curl -Lo "haiku/.git/hooks/commit-msg" https://review.haiku-os.org/tools/hooks/commit-msg
chmod +x haiku/.git/hooks/commit-msg

Preparing your first patch

Before making a commit, install a Git hook that will automatically generate Change-Id’s for you:

curl -Lo "haiku/.git/hooks/commit-msg" https://review.haiku-os.org/tools/hooks/commit-msg
chmod +x haiku/.git/hooks/commit-msg

If a maintainer asks you to correct something later on, Gerrit will use that Change-Id to keep track of your newest changes.

If you wish to change something in your commit, you can amend it in retrospect making them using git add . and git commit –amend.

Case Sensitive Filesystems

In short, such a file system recognizes ThisIsAFile.txt and THISISAFILE.txt as two different files. Some file systems that are (or could be) case insensitive include FAT32, NTFS, and HFS+.

macOS’s HFS+ is also case insensitive by default, but that can be changed: See this article for more information.

Commit Message Standards

Making a new commit

In Git, you make commits to your local tree, then push the final results to the central remote Haiku repository. Split your work in commits that are not too large commits, but remember that each commit will be reviewed separately, so don’t make them too small either.

The commit message will also be reviewed, and should describe the change in as much detail as possible. You can refer to other commits by either their hrev tag or their SHA1 hash, and to bugs using the #number notation. Gerrit and cgit will then automatically add an hyperlink to the relevant place.

The commit message should include a short description on the first line (ideally less than 64 characters), then a blank line, and a more detailed explanation. The short message is visible in “git log”, the web interface, and many other git tools, and allows to know what the commit is about. The details are available separately (for example in git log -p or when looking at the commit directly in the web interface), so they are both important.

Here is an example of a good commit message:

kernel: Perform the usual early morning tasks

* Ensure cats are fed.
* Clean up white space.
* Adjust retroencabulator to accept input from multiple sources of data
  and ensure the buffer is free for shenanigans.

Short commit messages

If your commit is very short, you can include it directly on the Git command line:

git commit -a -m "WebPositive: Style cleanup, no functional change"

Long commit messages

If you want to make a longer commit message, you can put it in a file and use it this way:

git commit -a -F ~/mycommitlog

Alternatively, you can use “git commit -a”, which will open a text editor and let you write down the message when you commit your changes.

It may be a good idea to check Gerrit as a point of reference if you are not sure how you should format your commit message.

Amending commits

Commit messages, as well as the contents of a commit itself, can be corrected using git commit –amend.

Common tasks

Updating the source code

This section assumes that you are actively working on new commits and need to test them on a newer revision of the source code.

You can make Git take care of this automatically for you, so that git pull does the right thing for Haiku:

cd haiku
git config pull.rebase true

Alternatively, a single path or multiple paths can be given to git pull. This will allow you to run the following command from any directory. This becomes extremely useful if you use an external object directory or if you wish to update both the buildtools and haiku directories at the same time.

git pull --rebase ./haiku ./buildtools

Pushing changes for review

Assuming that your local repository’s remote URL points to Gerrit and that you have configured your environment as previously described in this document, this should work:

git push origin HEAD:refs/for/master -o topic="something"

After your changes are complete, the push command will push your local tree to the remote Haiku repository. The commits will be added to the review page and people will review them. You can then amend your commits and push them again, until they are reviewed and merged.

It is recommended to set a topic - a single keyword that can easily be searched for in the web interface and help categorize commits.

GitHub

To submit a patch, you can change the remote URL of the Haiku repository to Gerrit using this command:

git remote set-url origin ssh://$USER@git.haiku-os.org/haiku

Assessing review comments and updating a commit

Usually, your changes will not be accepted on the first try. Other developers will review it, making sure they understand what you are doing, and maybe help you find better ways of doing it. They will also check that your code follows the coding guidelines, which are important to make sure the code is easy to read and uses the same conventions that other contributors use as well.

Single-commit change

To update an existing commit, you need to download it locally, modify it, and send it again. When your change consists of a single commit, you can cherry-pick it.

First make sure you start from a clean working tree with the latest Haiku changes (note that this will remove all your work-in-progress commits from the working copy - make sure these commits are in a branch. Git will remind you about this if you haven’t done so).

git fetch
git checkout origin/master

Then you can download your commit from Gerrit. To do this, use the Gerrit web interface and the Download -> Cherry Pick button, which allows you to copy the required git command. It looks like this, but it is different for each commit and each version of a commit so make sure to get the correct one from Gerrit:

git fetch "ssh://user@git.haiku-os.org/haiku" refs/changes/28/3228/4 && git cherry-pick FETCH_HEAD

You can now edit the files to make the needed changes. Once you are done, edit the commit to include your changes:

git add a/modified/file.cpp another/modified/file.h # you can use wildcards, or just 'git add .' to add everything modified
git commit --amend # modify the commit

Make sure the commit message contains the change-id for the commit. If it doesn’t, copy it from Gerrit and add it at the end of the commit message.

Finally, send your work for review:

git push origin HEAD:refs/for/master

HEAD:refs/for/master means that your change was built on top of the master branch and that your changes are meant to be applied to the master branch.

Multiple-commit change

The process is similar when your change is split into multiple commits, but you can’t as easily use cherry-pick since it would have to be done once per commit. So, a different process can be used instead.

First of all make sure you have the latest version of the Haiku source code:

git fetch

Then go to the latest commit of your change in progress and use the Download -> Checkout menu to get all the changes at once. Again, note that the command changes for each commit, so be sure to get the correct one from Gerrit. The one below is only an example.

git fetch "ssh://user@git.haiku-os.org/haiku" refs/changes/99/1299/5 && git checkout FETCH_HEAD

You can then rebase your changes on the current version of Haiku:

git rebase origin/master

You can use git commit –amend to edit the latest commits and add more commits to the branch. To modify the previous commits, you need to use git interactive rebase (git rebase -i). See

git help rebase

Once you are done, you can update the patches that you have previously submitted for review:

git push origin HEAD:refs/for/master

Read more:

• dev.haiku-os.org - Submitting Patches
• Gerrit Code Review - Uploading Changes