|Version 8 (modified by magnate, 23 months ago) (diff)|
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:
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 your changes 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 git does not like people undoing things so read up on git stash if you need to switch branches and don't want to either commit or lose the current changes.)
If you are a member of "team angband" on github, please read Policy/GitMaster before making changes to the official angband repo.
So what do I do if I get out of sync with a remote I'm tracking?
This typically happens when you're engrossed in working on your commit and haven't noticed that someone else has pushed an update to the branch you're working on in the meantime. So you finish testing your work, commit it and to 'git push remotename branchname', only to get told
To email@example.com:angband/angband.git ! [rejected] staging -> staging (non-fast-forward) error: failed to push some refs to 'firstname.lastname@example.org:angband/angband.git' To prevent you from losing history, non-fast-forward updates were rejected Merge the remote changes (e.g. 'git pull') before pushing again. See the 'Note about fast-forwards' section of 'git push --help' for details.
Argh. You don't want to lose your changes, but you also don't want to do a non-fast-forward merge and risk the wrath of takk ... so try this:
git fetch remotename git checkout remotename/branchname git checkout -b newbranch git cherry-pick your-commit-id git push remotename newbranch:branchname
That creates a new copy of the branch you're tracking, adds your commit without recursing, and pushes it upstream as if you'd done it right in the first place. All that's left is to tidy up your local repo: delete the old messed-up branch ('git branch -D branchname') and rename the new one to match the one you're tracking ('git branch -m newbranch branchname').
Other general tips
Don't be afraid to create and delete lots of branches. They're totally expendable, and a new branch is a fresh start.
Always update your local copy of the official repository (git fetch official) before pushing your work. If possible, use "git rebase official/staging" to ensure that your changes are on top of the very latest commits from the staging branch - that will make them easier to merge, and is much neater than merging official branches into your branches and having the devteam merge them back again. If you are nervous about trying rebase on a branch with lots of your hard work in it, create a new copy of that branch first - so if the rebase goes horribly wrong, your original branch is untouched.
When submitting pull requests on github, please ensure that you choose only the commits relevant to this request - try and avoid choosing merge commits or commits which are part of another pull request.