wiki:GitUsage

Version 1 (modified by magnate, 9 years ago) (diff)

First draft

This page is intended to give you the information you need to get started with using git to make your own changes to the angband source. It assumes that you have a working version of git installed (version 1.5.3 or newer), but it is merely a quick guide and is not intended to replace the git manual at http://www.kernel.org/pub/software/scm/git/docs/user-manual.html.

To create a local copy of the official angband repository, use git clone git://github.com/angband/angband.git. But if you want to participate in development, it is best not to do this straight away. Instead, get an account at http://github.com, go to the official angband/angband repository and click Fork. This will create a new repository called git://github.com/yourlogin/angband. This is the one you should clone locally using git clone git://github.com/yourlogin/angband.git.

This will create a local repository with four branches. Use git branch -a to see them:

  • master
  • origin/master
  • origin/staging
  • origin/integration

Do NOT do your work in your master branch: this is asking for trouble. Create a new branch using git checkout -b newbranch, and do your work there. Use git commit -a to commit it to your new branch and then autogen/configure/make to test them.

Once you have tested your commits to your satisfaction, you can share them. Assuming you have created a new branch and made your changes as described above, you can publish your changes to the world by using git push origin newbranch - this will make your new branch appear on github for others to test. (It is advisable, but not essential, to use ssh keys for access to github.)

Do not worry about the staging or integration branches: they are irrelevant to your development activity. You can delete them from your fork with impunity if you are tidy-minded.

Keep your thinking clear: separate your work into different branches for different things. Create a branch called 'docs' if you want to work on some docs. Create one called 'stores' if you want to make changes to stores. Etc. There is no limit to the number of branches you can have, and you can use git checkout branchname to switch between branches at any time. (Ideally you should commit any changes in the current branch before switching branches, but read up on git stash if you need to switch branches and don't want to commit or lose the current changes.)

Angband devteam policy

If you are part of "team angband" on github, please read this bit carefully before making any changes to the official angband/angband repo. Assuming your local repo has as its origin your own github repo, you'll need to add a new remote to track the official one: git remote add official git@github.com:angband/angband.git (this url assumes you are using ssh access and have configured your local ssh config accordingly). After a git fetch official you will then see the official/master, official/staging and official/integration branches, as well as all the origin/ branches of your own github repo.

Ignore the official/integration branch - this is used by github to action things from the "Fork queue", so we should not confuse those activities with our manual commits.

Make a local copy of the official/staging branch: git checkout official/staging followed by git checkout -b staging. Keep this branch up-to-date: every time you see that the official repo has been updated, do git fetch official followed by git checkout staging and then git merge official/master. This will ensure that your local staging branch is in sync with the official master.

Similarly, keep your local master up-to-date with the official master as well: git checkout master and git merge official/master.

If you are ready to push a tested set of your changes to the official repo (let's say you're working in "mybranch" locally), first push them to staging by using git checkout staging followed by git merge mybranch. This will bring the changes from mybranch into your local copy of staging. Depending on when you last merged official changes into mybranch, you may wish to compile and test again in staging. When you're happy that nothing is broken, push from your local staging branch into the offical repo's staging branch with git push official staging.

Once this is done, send a pull request to the rest of team angband to ask somebody to test your latest changes in staging.

If you are the one to action a pull request and are satisfied that these changes work, you can then propagate them to the official master: git checkout master, git merge staging and git push official master. The dev team is now big enough that we should resist propagating our own staged changes except in emergencies.