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.
- Main differences to bazaar
- Installing Git
- Getting the Source Code
- Working on and contributing code
- Comparison with Bazaar
- Checking out into subdirectories
- Using ssh instead of https
- Checking out a branch from somebody else's fork
- Checkout out and tracking a remote branch
- Useful Links and Tutorials
Main differences to bazaar
When using bazaar, you probably have each branch in it's own directory. When using git, you have only one directory. git handles all branches in this directory and changing to a branch is done with the command
git checkout BRANCHNAME. This command applies the changes made in BRANCHNAME to the files in this directory. E.g. the command
git checkout master revert all files in this directory to the state of the master branch.
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 --depth 1 on the command line and you're done.
1. Create a fork
- Visit 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.
- Hit the "Fork" button. This will create a new Git repository on GitHub at
<username>/widelandsthat links back to
widelands/widelandson 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. We will also be using the "depth" parameter to speed things up - if you want the full commit history, just leave it out.
- Open a command line / terminal and
cdto where you want to clone widelands.
<username>/widelandson GitHub and locate the green "Clone or download" button. This will give you a link to copy that looks like
- Paste the link that you just copied to run
git clone https://github.com/<userame>/widelands.git --depth 500on your command line / in your terminal. This will pull your fork down onto your machine and check out the
masterbranch. Your fork will be known as
originto the Git system.
- Repeat step 2 with the original repository on GitHub. The link will look like
https://github.com/widelands/widelands.git --depth 500
- Link up the original by running
git remote add upstream https://github.com/widelands/widelands.git. This will now be known as
upstreamto 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.
Note: If you don't need the whole git history, you can create a shallow clone by calling
git clone https://github.com/<userame>/widelands.git --depth 1
Working on and contributing code
If you plan to be working on multiple branches at the same time, see 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 instead.
After BuildingWidelands and making your changes, you can do a local commit.
- You can see which files have changed by running
git statusand see a diff by running
- Note: Unlike Bazaaar where you only need to
bzr addnew files, you will need to run
git addfor all the files that have any changes in them! This is the bit where we recommend using a GUI client.
- After running
git addfor your changes, you can commit them by running
git commit -m "Commit message". Reference the issue that your working on with
#, e.g. "Fixes #123". This will link your branch to issue No. 123 in the GitHub issue tracker.
- Finally, push your changes with
git push origin <branch_name>.
Note: If you did not add any new files, you cann add and commit at the same time by running
git commit -am "Commit message".
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
- Describe 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 and AppVeyor. 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.
- GitHub will also send you an e-mail when a reviewer adds a comment.
Comparison with Bazaar
|Switch to trunk||
|Update trunk and merge into local branch||
|Show branches, with the current one highlighted||Use operating system to list directories||
|Delete remote branch||Use Launchpad interface||
|Delete local branch||Use operating system to delete directory||
|Undo all changes||
|Undo changes to a file||
|Get a remote branch and switch to it||
Getting the code
Working on your code
Synchonizing with the main repository / master branch
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:
- 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). This will be very time/bandwith consumig as the whole repo will be transfered again. Instead of cloning every time, you can also duplicate your master directory manually (
cp -r widelands <branchname>) which is usually faster and requires no bandwidth.
git worktree(manual blog). This command will create a separate copy of submodules too, but can handle only 1 level.
Using ssh instead of https
Tired of typing your pasword all the time? If so, this section is for you.
- Upload the public key to your settings.
- Once provided you can use ssh instead of https for every GitHub related command e.g.
git clone email@example.com:widelands/widelands.git
- The GitHub GUI provides the needed path when you click on "clone or download" on the repository page
Checking out a branch from somebody else's fork
$ git clone https://github.com/widelands/widelands.git --depth 1 $ cd widelands/ $ git remote add niftyfork https://github.com/niftyfork/widelands.git $ git fetch niftyfork --depth 1 $ git checkout niftybranch
The last message you see should be:
Branch 'niftybranch' set up to track remote branch 'niftybranch' from 'niftyfork'. Switched to a new branch 'niftybranch'
And this is what the commands mean:
$ git clone https://github.com/widelands/widelands.git --depth 1 $ cd widelands/
Clone the main Widelands repository and change into its directory. You only need to do this if you haven't already.
--depth 1 means you only fetch the latest revision, which will speed things up. YOu can omit that if you want to get the complete commit history.
$ git remote add niftyfork https://github.com/niftyfork/widelands.git
Register niftyfork's fork and call it "niftyfork"
$ git fetch niftyfork --depth 1
Register what's in niftyfork's fork. Again,
--depth 1 will speed things up. Git should tell you about the branches that it has found at this point.
$ git checkout niftybranch
Switch to the branch.
If you want to change forks for your local branch, call
git branch -u otherniftyfork/niftybranch
Checkout out and tracking a remote branch
This is how to checkout a remote branch from a specific fork and register it as the push and pull location for the branch. First, you get the information about the branches in the fork and their status:
$ git fetch niftyfork
Then you switch to the branch while telling it to track the remote source:
git checkout -t niftyfork/niftybranch
Now you can push and pull by simply calling:
git push git pull