Skip to content

Workflow

Jump to bottom
pagojo edited this page Mar 1, 2012 · 6 revisions

This is a simple workflow. I show you:

  • How to fork a repository and clone it locally
  • Pull in upstream changes
  • Make a change using a topic branch
  • Push your local branch to your fork on GitHub
  • Create a pull request
  • Add some extra commit that will be picked up by the same pull request
  • Accept the pull request and merge it
  • Delete the local and remote branch when you have to fork a repository.

Fork a repository and clone it locally

I am going to fork thessaloniki/rb into amiridis/rb.

I will open a terminal and clone my fork locally:

$ git clone [email protected]:amiridis/rb.git
Cloning into rb...
remote: Counting objects: 92, done.
remote: Compressing objects: 100% (69/69), done.
remote: Total 92 (delta 16), reused 83 (delta 7)
Receiving objects: 100% (92/92), 10.06 MiB | 1019 KiB/s, done.
Resolving deltas: 100% (16/16), done.

$ cd rb
rb (master=) $

Now I want to set up my upstream remote. I do this once:

rb (master=) $ git remote add upstream git://github.com/thessaloniki/rb.git

Pull in upstream changes

Now I can fetch and merge upstream changes before I start working on something new. I do that as follows:

rb (master=) $ git fetch upstream
From git://github.com/thessaloniki/rb
 * [new branch]      master     -> upstream/master
rb (master=) $ git merge upstream/master 
Already up-to-date.

Now my local clone is all synced with the parent repository thessaloniki/rb. If I there were any changes I also want to push them to my fork on GitHub:

rb (master=) $ git push origin master

Make a change using a local branch

If I examine the repository I see there is a file called README.md.

rb (master=) $ ls
README.md meetups   resources

I want to add some text to it to prompt people to visit the wiki of thessaloniki.rb. I always create a new local branch to do my changes. I do that as follows:

rb (master=) $ git checkout -b prompt_about_wiki
Switched to a new branch 'prompt_about_wiki'
rb (prompt_about_wiki) $

Notice that I use one command to both create the branch (-b) and checkout the new branch (i.e. switch to it).

Instead of that I could have done:

git branch prompt_about_wiki
git checkout prompt_about_wiki

Now it is safe to start doing changes. I will edit README.md and add some text:

Here is the change:

rb (prompt_about_wiki) $ git status
# On branch prompt_about_wiki
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   README.md
#
no changes added to commit (use "git add" and/or "git commit -a")

I will now add and commit:

rb (prompt_about_wiki *) $ git add .
rb (prompt_about_wiki +) $ git commit -m "Prompt users to visit our wiki"
[prompt_about_wiki 85a4419] Prompt users to visit our wiki
 1 files changed, 6 insertions(+), 1 deletions(-)

Push your local branch to your fork on GitHub

I am ready to push my local branch to the remote repository (my fork):

rb (prompt_about_wiki) $ git push origin prompt_about_wiki 
Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 376 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
To [email protected]:amiridis/rb.git
 * [new branch]      prompt_about_wiki -> prompt_about_wiki

Create a pull request

I can now visit my fork on GitHub and see the new branch:

I create a pull request:

If you check the commits tab of the pull request, you will see there is only one commit, the commit I did.

Add some extra commit that will be picked up by the same pull request

Sometimes, the pull request is not accepted immediately and the owners of the parent repository ask for some changes, or we detect something we don't like, or we just work incrementally until we are sure everything is good and can be merged.

Adding new commits is easy. You just go back to your local branch and add more commits and push them back. The pull request will automatically pick them up and include them in the list.

For example, lets say I wanted to change the link to our wiki and put a label on it:

Commit and push my change:

rb (prompt_about_wiki *%) $ git add .
rb (prompt_about_wiki +) $ git commit -m "Wiki link is a label"
[prompt_about_wiki 4b7cadc] Wiki link is a label
 2 files changed, 1 insertions(+), 1 deletions(-)
 create mode 100644 .README.md.swp
rb (prompt_about_wiki) $ git push origin prompt_about_wiki 
Counting objects: 6, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 757 bytes, done.
Total 4 (delta 1), reused 0 (delta 0)
To [email protected]:amiridis/rb.git
   85a4419..4b7cadc  prompt_about_wiki -> prompt_about_wiki

Now my pull request has picked the commit and looks like this:

Accept the pull request and merge it

This is performed by the owners of the parent repository. Here I am both the owner and the one who created the pull request:

Confirm merge

Done

Delete the local and remote branch when you have to fork a repository

Now that everything is fine and our pull request was accepted and merged, I don't need the branch anymore. I am going to delete it both from the local repository and the remote one:

rb (prompt_about_wiki) $ git checkout master
Switched to branch 'master'
rb (master=) $ git branch -d prompt_about_wiki 
error: The branch 'prompt_about_wiki' is not fully merged.
If you are sure you want to delete it, run 'git branch -D prompt_about_wiki'.
rb (master=) $ git fetch upstream
remote: Counting objects: 1, done.
remote: Total 1 (delta 0), reused 1 (delta 0)
Unpacking objects: 100% (1/1), done.
From git://github.com/thessaloniki/rb
   b55a9df..817d54c  master     -> upstream/master
rb (master=) $ git merge upstream/master 
Updating b55a9df..817d54c
Fast-forward
 .README.md.swp |  Bin 0 -> 12288 bytes
 README.md      |    7 ++++++-
 2 files changed, 6 insertions(+), 1 deletions(-)
 create mode 100644 .README.md.swp
rb (master>) $ git branch -d prompt_about_wiki 
Deleted branch prompt_about_wiki (was 4b7cadc).
rb (master>) $ git push origin :prompt_about_wiki
To [email protected]:amiridis/rb.git
 - [deleted]         prompt_about_wiki

Notice:

  • I tried to delete it but it protected me saying: The branch 'prompt_about_wiki' is not fully merged. This just means that we haven't pulled in upstream changes to sync our master branch.
  • I do that and then it lets me delete my local branch
  • Finally, I also delete the remote branch using that weird syntax git push origin :prompt_about_wiki

Tada!! The workflow ends here. For new changes you just start over with pulling in upstream changes in case something new happened, creating a new local branch, work, push, pull request, add more commits if you like, have your pull request accepted, delete your local and remote branch, done!

Clone this wiki locally