old.kete.net.nz :Documentation

Topic: Working with Git Branches on Github

Topic type:
Topic

The steps to make, edit, add, commit, push, and pull work in a different branch to/from Github.

For more information / resources, please check out the collection of links on http://old.kete.net.nz/

When you want to work on code that will add functionality or fixing big bugs, then it's best not to push to the master branch. Create a branch where you can do your work seperate from master branch, but with the same functionality (editing, adding, commiting, pushing and pulling) as you would in the master branch.

A note about code in vendor/plugins: plugins may or may not be managed primarily from their own version control repositories and have their code pulled into Kete's code base. The Kete team uses a separate tool, called Piston, to pull in code from these external repositories. See this article for a good guide to how it is initially set up and the documentation for updating covers pulling new code from the external repository.

First create a github account if you haven't already and fork Kete.

Follow directions in http://old.kete.net.nz/site/topics/show/176-using-git-and-github.

Setting up the branch

Everything below assumes that you have a working clone of your account's fork of Kete from github, i.e.

$ git clone git@github.com:[your-github-account]/kete.git # you need to have submitted your ssh key for this to work...

To get started, create a new branch that relates to what you'll be working on. Because you cannot (at the time of writing) make a remote branch and track it right away, we'll have to take the long way of making a branch, pushing to the remote, removing the local branch and readding the remote branch.

$ git checkout -b enhancement_num_XXXX_your_intended_work

The branch name is structured so others can find out what that branch is for easily. It begins with the type of work (enhancement, bugfix, or refinement), followed by _ticketnumber_, for the ticket for your work is on Lighthouse, followed by 2-3 underscore separated words describing the work (e.g. basket_sort_settings)

Next, push the branch to the github (or other remote) repository. Just run the commands as outlined below (adjust the branch name to what you use).

$ git push origin enhancement_num_XXXX_your_intended_work
To git@github.com:[your-github-account]/kete.git
  * [new branch]    enhancement_num_XXXX_your_intended_work -> enhancement_num_XXXX_your_intended_work

When you create a branch locally, it doesn't setup a track of the remote branch. So to do that, first we go back to master, delete the branch locally, then readd the tracked branch.

$ git checkout master
$ git branch -D enhancement_num_XXXX_your_intended_work
$ git checkout --track -b enhancement_num_XXXX_your_intended_work origin/enhancement_num_XXXX_your_intended_work
$ git pull

Now you have a remote tracked branch that can be pulled from and pushed to.

Pushing to Github

If you want to change between branches available on your machine, run the following:

$ git branch
  enhancement_rt_num_XXXX_your_intended_work
* master
$ git checkout enhancement_num_XXXX_your_intended_work
Switched to branch "enhancement_num_XXXX_your_intended_work"
$ git branch
* enhancement_num_XXXX_your_intended_work
  master

Once you've completed the steps to set up and you've checked out into the right branch, pushing changes there is exactly the same as pushing changes to the master branch.

$ git status
# on branch enhancement_num_XXXX_your_intended_work
#            modified:   README
no changes added to commit
$ git add README
$ git commit -m "a message that describes what will be included in this commit"
$ git push

And you're done. People can now access your code if they need to.

Accessing and pulling changes

When someone wants to get your code, or you need to update the code, the following is what you'll use.

$ git checkout master
$ git checkout --track -b enhancement_num_XXXX_your_intended_work origin/enhancement_num_XXXX_your_intended_work
$ git pull

Merging changes from a branch to master

Either in a ticket for the issue or by sending a message to the kete account on github, you should request that your branch's code be reviewed and considered for merger into the master branch.

After Merging to Master

You'll want to clean out remote branches for non-releases, etc. when you are done merging them into master. Here's how:

$ git push origin :enhancement_num_xxxx_your_intended_work # removes remote branch from github
$ git branch -D enhancement_num_xxxx_your_intended_work    # removes local branch from your computer

Tracking 1-1-stable, or other previous release, in a Client Repository

Often you'll want to track 1-1-stable (or 1-2-stable, etc.) in a client repository so that the client's codebase is kept up to date. Instructions below detail how this can be done.

# Add a remote to track Github with
$ git remote add kete_github git://github.com:/[your-github-account]/kete.git

# Add a branch tracking the 1-1-stable branch on Github.com:
$ git fetch kete_github
$ git checkout --track -b 1-1-stable kete_github/1-1-stable

# Merge the 1-1-stable branch into master
$ git checkout master
$ git merge 1-1-stable -m "Merged 1-1-stable changes into master."

If you have any issues, please post a comment here.

Another option for tracking a remote branch in a Client Repository

# Add a remote to track Github with
$ git remote add kete_github git://github.com:kete/kete.git

# Fetch the contents of github
$ git fetch kete_github

# Merge in a specific branch from the (now fetched) remote
$ git merge kete_github/1-1-stable # Substitute the branch name as required..