Difference between revisions of "Maintaining a github fork"

Latest revision as of 13:45, 4 March 2014

If you are not yet fluent in git, the following instructions may help you with preparing a contribution using a github fork. These instructions assume that you want to keep your local master branch clean and synchronized with the main krb5 master branch, and prepare your contributions on topic branches.

To begin, create a github account if you don't already have one. Visit https://github.com/krb5/krb5 and click the "Fork" button to create a github fork.

Make a local clone of the main github krb5 repository with (replacing YOURNAME with your github username):

   git clone git@github.com:krb5/krb5.git
   cd krb5

In this clone, add a remote for your github fork. (This remote can have any name you want, but we will assume you want to name it with your github username.)

   git remote add YOURNAME git@github.com:YOURNAME/krb5.git
   git fetch YOURNAME

You can keep your local clone's master branch up to date with respect to the main krb5 master branch with:

   git checkout master
   git pull origin master

Before making any changes, start a topic branch with (using "mangos" as an example name for the branch):

   git checkout -b mangos master

After making changes, make sure to "git add" any new files and then run:

   git commit -a
   <enter your commit message>
   git push YOURNAME mangos

If your contribution fits naturally in one commit, you should now be ready to make a pull request from your github fork to the upstream krb5 repository using the github web site. If we have feedback on your pull request and you want to update your change, you can:

   git checkout mangos
   <make your changes>
   git commit --amend -a
   <edit your commit message if necessary>
   git push YOURNAME +mangos

The plus sign in the final command is necessary because you're overwriting the history of your mangos branch. This is normal for topic branches which aren't yet part of the established history of a project.

After you begin (or finish) work on your topic branch, changes will probably have been made to the main krb5 master branch. To keep up with these changes, you can update your master branch (as described above), then rebase your topic branch onto the updated master branch and then synchronize that to your github fork:

   git rebase master mangos
   git push YOURNAME +mangos

If your contribution naturally breaks down into multiple logical commits, then you will likely need to familiarize yourself with git's tools for editing branch history, probably by learning how to use "git rebase -i". As above, use "git push YOURNAME +mangos" to update your github fork's copy of the topic branch after you are done editing its history.

If you want to delete your topic branch in the local repository and github fork, you can do so with:

   git branch -D mangos
   git push YOURNAME :mangos

(Read the second command as "push <empty branchname> onto the mangos branch", which causes it to be deleted.)