Latest Posts

Changes in GitPrimer

Editor Comment

Add Working on and contributing code


Revision Differences of Revision 15

We'll be moving everything except for widelands-media to GitHub. This page explains how to obtain the source code and how to work with it. We are prodiving instructions for how to do it on the command line / in a terminal, but we recommend that you also use a GUI client to make your life easier. ¶

[TOC] ¶

# Installing Git ¶

First, you will need to download install [Git](https://git-scm.com/) on your machine. Follow the instructions on the [Git Downloads](https://git-scm.com/downloads) page. We also recommend that you get a [GUI client](https://git-scm.com/downloads/guis). ¶


# Getting the Source Code ¶

Rather than working on the Widelands repository directly, you will create your own fork, work on a branch there and then make a Pull Request when your code is ready. If you don't expect to be working on the code and only want to play the development version, call `git clone https://github.com/widelands/widelands.git` on the command line and you're done. ¶

## 1. Create a fork ¶

1. Visit [https://github.com/widelands](https://github.com/widelands) and pick the repository that you want to clone. For the Widelands game, this will be "widelands". We will be using this as an example throughout, but it works the same for all our repositories. ¶
2. Hit the "Fork" button. This will create a new Git repository on GitHub at `<username>/widelands` that links back to `widelands/widelands` on the GitHub website. ¶

## 2. Download the code ¶

We want to set up both your fork ("origin") and the original ("upstream") repository on your machine. Your fork is for you to work on, and the upstream repository is for keeping up with the changes in our master branch. ¶

1. Open a command line / terminal and `cd` to where you want to clone widelands. ¶
2. Visit `<username>/widelands` on GitHub and locate the green "Clone or download" button. This will give you a link to copy that looks like `https://github.com/<userame>/widelands.git`. ¶
3. Paste the link that you just copied to run `git clone https://github.com/<userame>/widelands.git` on your command line / in your terminal. This will pull your fork down onto your machine and check out the `master` branch. Your fork will be known as `origin` to the Git system. ¶
4. Repeat step 2 with the original repository on GitHub. The link will look like `https://github.com/widelands/widelands.git` ¶
5. Link up the original by running `git remote add upstream https://github.com/widelands/widelands.git`. This will now be known as `upstream` to the Git system. ¶

In principle, you can add as many forks as you want and call them anything you want. You can get a list by running `git remote -v`. ¶


# Working on and contributing code ¶

If you plan to be working on multiple branches at the same time, see [Checking out into subdirectories](https://www.widelands.org/wiki/edit/GitPrimer/#checking-out-into-subdirectories) - we haven't worked out the details of that one yet, so please feel free to contribute to this Wiki page. ¶

## 1. Create a branch ¶

You should always work in a separate branch for each feature and never on the `master` branch. For creating a branch, run `git checkout -b <branch_name>`.

## 2. Commit and upload your changes ¶

You should always keep in sync with upstream's master branch. Call `git pull upstream master` and follow the instructions. Once you feel comfortable with Git, you can also consider [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) instead. ¶

After [[BuildingWidelands]] and making your changes, you can do a local commit. ¶

1. You can see which files have changed by running `git status` and see a diff by running `git diff`. ¶
2. ** Note:* Unlike Bazaaar where you only need to `bzr add` new files, you will need to run `git add` for all the files that have any changes in them! This is the bit where we recommend using a GUI client. ¶
3. After running `git add` for your changes, you can commit them by running `git commit -m "Commit message"`. ¶
4. Finally, push your changes with `git push origin <branch_name>`. ¶

## 3. Get your changes into the game ¶

Once you are happy with your branch, it's time to hit the "Pull Request" button on GitHub, so that your branch will be merged into our `master` branch. ¶

* DOescribe what your change does ¶
* If your branch adresses any of our issues, mention the issue(s) ¶
* Your pull request and each subsequent push to your branch will trigger automated builds on [Travis](https://travis-ci.org/widelands/widelands/branches) and [AppVeyor](https://ci.appveyor.com/project/widelands-dev/widelands/history). Check out the protocols for these builds to see if they were successful and whether there are any new compiler warnings or [test failures to fix](https://www.widelands.org/wiki/RegressionTests/). ¶
* GitHub will also send you an e-mail when a reviewer adds a comment.

# Comparison with Bazaar ¶

Action | bzr | git ¶
-------- | -------- | -------- ¶
Switch to trunk | `cd ../trunk` | `git checkout master` ¶
Update trunk and merge into local branch | `cd ../trunk`; `bzr pull lp:widelands`; `cd ../<branch>`; `bzr merge ../trunk`; `bzr commit -m "Merged trunk."` | `git pull --rebase upstream master`; `git push origin <branch> --force` ¶
Show branches, with the current one highlighted | Use operating system to list directories | `git branch` ¶
Delete remote branch | Use Launchpad interface | `git push origin --delete <branch_name>` ¶
Delete local branch | Use operating system to delete directory | `git branch -d <branch_name>` ¶
Undo all changes | `bzr revert` | `git checkout .` ¶
Undo changes to a file | `bzr revert <file>` | `git checkout <file>` ¶
Get a remote branch and switch to it | `bzr branch <remote_branch_name> <new_local_branch>`; `cd <new_local_branch>` | `git checkout -b <new_local_branch> <remote_location>/<remote_branch_name>` ¶

See also [Merging in bzr: The git approach vs the bzr approach](http://toykeeper.net/tutorials/bzr-vs-git/) ¶

# Workflow ¶

## Getting the code ¶

[![fork_and_clone.png](/wlmedia/wlimages/fork_and_clone.png)](/wlmedia/wlimages/fork_and_clone.png) ¶

## Working on your code ¶

[![git_commit_cycle.png](/wlmedia/wlimages/git_commit_cycle.png)](/wlmedia/wlimages/git_commit_cycle.png) ¶

## Synchonizing with the main repository / master branch ¶

### Merging ¶

[![git_merge_forkflow.png](/wlmedia/wlimages/git_merge_forkflow.png)](/wlmedia/wlimages/git_merge_forkflow.png) ¶

### Rebasing ¶

[![git_rebase_forkflow.png](/wlmedia/wlimages/git_rebase_forkflow.png)](/wlmedia/wlimages/git_rebase_forkflow.png) ¶

# Checking out into subdirectories ¶

Since our bottleneck is compile time rather than disk space, we will want to be able to check out into subdirectories, just like Bazaar does it. There are 2 ways of doing this: ¶

1. Clone the full repository into a new directory and set up the remotes each time. This will support submodules (we are currently not using submodules, so don't worry about this). ¶
2. Use `git worktree` ([manual](https://git-scm.com/docs/git-worktree) [blog](https://blog.github.com/2015-07-29-git-2-5-including-multiple-worktrees-and-triangular-workflows/)). This command will create a separate copy of submodules too, but [can handle only 1 level](https://stackoverflow.com/questions/31871888/what-goes-wrong-when-using-git-worktree-with-git-submodules). ¶

# Useful Links ¶

* [Official git documentation + book](https://git-scm.com/doc) ¶
* [Getting started with GitHub](https://help.github.com/en/categories/getting-started-with-github)