GitForLunarDevs

Latest revision as of 22:54, 9 June 2013

GITHUB work flow

Requirements a github account and a mindset to use git and github. To be able to push changes to github it is recommended by github to use https. But some prefer using ssh authentication keys. See https://help.github.com/articles/generating-ssh-keys Have your git config setup correct with your user.name and user.email

git config --global user.name "John Doe"
git config --global user.name "john@doe.net"

Personal repo to work in

To be able to send pull requests you need a personal repo on github which is a fork of the repo you want to work on.

On github navigate to https://github.com/lunar-linux and select the repo you wan to work on. click on the fork button near top right. Now you have your personal repo in github. Next step is to create a clone the repo to you pc. On github select your repo and you can see the pull url you need to use to have read+write access

git clone git@github.com/<username>/<reponame>

For more information see https://help.github.com/articles/fork-a-repo

note: all the next command assume you are in your local repo directory.

This repo is up to date with lunar-linux repo only because you just forked it. So the next step is to setup a upstream branch to help with keeping your repo up to date.

git remote add upstream git://github.com/lunar-linux/<reponame>
git checkout -b upstream_master upstream/master

note: with git checkout you can switch between branches. So, you'll end up in the upstream_master branch. To switch back to master: git checkout master

Keeping your personal repo up to date

After some time commits will have been push to lunar-linux/<reponame> and you want to have them in you repo too. This is where the upstream_master branch comes in useful.

git checkout upstream_master
git pull

note: In this guide there are a lot of git checkout <branchname> this it not required if you are already in that branch.

note: Git could complain it you try to switch to another branch if you have local modifications. If you are switching temporarily you can use git stash to store your changes.

git stash
<...>
git checkout <WIP branch>
git stash pop

Now that your upstream_master is up to date you need to get these changes in your other branches. That would be at least master. But you can repeat these instructions for every branch you have. Just replace master with <branchname> and optionally replace upstream_master with master.

git checkout master
git merge upstream_master

Now you have this locally you can push this to you personal github.

git checkout master
git push

Working with branches

For the pull requests it is easier if you work with a concept called feature branches. In this concept you don't make changes directly into master, but rather you create a branch and make your changes there. These changes can contain one or more commits. Unless you work with local only branches you won't merge these branches back into master yourself. These branches will be merged back into master when they are pulled into lunar-linux/<repo> and you update your personal repo.

lunar-linux master:  --- A ---- D --- [BC]M --- E ------------
                          \           /          \
personal dev branch:       \   B --- C            \
                            \ /                    \
local master:        ------ [A] ------------------ [BDCME] ---

A-E are normal commits. M is a merge commit. Commits between [] is only pulled objects. This doesn't change these commits.

note: This means you can have multiple branches in parallel with all unrelated changes. Sometimes you need to have an extra local branch to merge multiple branches in to test some interactions. Since local branches can just be deleted with no fuzz, this can save you from polluting your master branch.

note: One feature branch doesn't mean one module change. This could contain multiple modules. These module changes are mostly related. Like changes to all dependencies when you bump a module.

Creating a development branch

There are two types of development branches. Local and remote branches. Local branches only exist in your local repo. These are just for you and you can handle them as you like. Remote branches are branches on your personal github. These branches are public and might be used by others. This has some limitations but that is out of the scope of this guide.

To create a remote branch you must first create it locally. It is most common to start a branch from your up to date local master.

git checkout master
git checkout -b <branchname>

Now you end up in you new branch. Make you changes commit them. Make some more commits, maybe. Now you want your local branch to be on your personal github for the first time for this branch.

git checkout <branchname>
git push --set-upstream origin <local-branchname>:<remote-branchname>

note: In many cases you want the local and remote branch name to be the same.

On the remote branch you can send a pull request or others can see what you have done so far. If your branch is not complete and you made some extra commits on the branch in your local repo. You want to push these changes to your personal github too.

git checkout <branchname>
git push

Working with pull requests

It is preferred to send pull request even if you have access to lunar-linux/<repo>. By sending a pull request there is another developer looking at your changes. And if you have some doubts you can add a comment to the pull request.

There is no point in sending pull requests is you are going to accept them your self. This will only generate extra noise. For small changes you can omit a pull request. For bigger changes let another developer pull in your request.

Sending a pull request

The easiest way to set a pull request in github is using feature branches. On github in you personal repo. Select the branch you want. And click on the pull request button on the top right. You will be prompted with a form and some fields might already be filled. You can add some extra description if care needs to be taken for the merge for example. With the commits and changes button you can see what your pull request will contain. When you're ready click the send pull request button on the bottom right. For more information see https://help.github.com/articles/using-pull-requests

Now wait for the pull request to be merged into lunar-linux/<repo> or be rejected.

Removing a development branch

When you are done with a branch. It was pulled into lunar-linux/<repo> or you discontinued the feature. You want to delete the branch. To delete a remote branch you need to push the branch with a : in front if it's name.

git push origin :<branchname>

note: If a request is successfully pulled github will provide a button at the bottom of the pull request to delete your remove branch.

After removing a remote branch the local branch still exists. If you are also done with you local branch you can delete it too.

git branch -d <branchname>

What branches do I have?

You can see all your remote branches on github. You can also use you local git to list them.

Show your local branches.

git branch

Show your remote branches.

git branch -r

Reference

• https://help.github.com/articles/fork-a-repo
• https://help.github.com/articles/using-pull-requests