Basic usage of git

There is this fancy mega application hosted on github called megaapp that you would like to contribute to. It’s perfect but there’s just this little feature missing to make it even more perfect.

This is how we would tackle this.

Login to you Github account and navigate to the project you would like to fork, megaapp in our example.

Click on the the fork button, as depicted in the image below:

If you are a member of several projects on github.com, github is going to ask you into which project you would like to clone this repository.

After selecting the project or your personal account, github is going to clone the repository into the project you selected. For this example I’m going to use my personal github account "tosmi".

Next we are going to clone our fork from Step 1: Fork the repository on github.com to our workstation and start working on the new feature.

After forking the upstream project you are redirect to your personal copy of the project. Click on the "Clone or download" button and select the link. You can choose between SSH and HTTPS protocols for downloading the project. We are going to use SSH.

Copy the link into a terminal and execute the git clone command:

Change into the directory of the project you downloaded in Step 2: Clone the repository to you workstation

Now we create a feature branch with a short name that describes our new feature:

Because we would like to add a new option to megaapp we call this feature branch addoption.

We are also prefixing the feature branch with our github username so that it is clear for the upstream project maintainer(s) who is contributing this.

How you name you branches is opinionated, so we would search for upstream project guidelines and if there are none maybe look at some existing pull request how other people are naming there branches. If we find no clue upstream we sticking with <github username>/<branch name>.

We can now start adding our mega feature to the project.

Before we can commit our changes, we have to place the changes made in the so called index or staging area:

If we would like to place all of our changes onto the index we could execute

After adding our changes to the Git index we can commit with

This will open our favorite editor and we can type a commit message. The first line should be a short description of our change, probably not longer than 70 to 80 characters. After two newlines we can enter a detailed explanation of your changes.

This is an example commit message

After saving the message and we have successfully created a commit.

There is also the option to add the commit comment directly on the command line

We execute

to push our local changes to the forked repository hosted on github.com.

We navigate to our personal project page of the forked repository on github. For the fork we are using in this example this is http://github.com/tosmi/megaapp.

Github is going to show us a button "Compare & pull request":

After clicking on that button we are able to review the changes we would like to include in this pull request.

If we are happy with our changes we click on "Create pull request". The upstream owner of the repository will get notified and we can see our open pull request on the upstream project page under "Pull requests".

If there are CI test configured for that project they will start to run and we can see if our pull request is going to pass all test configured.

Sometimes a upstream project maintainer asks you to rebase your work on the current upstream master branch. The following steps explain the basic workflow.

First we are going to create a new remote location of our repository called upstream. Upstream points to the upstream project repository. We will not push to this location, in most cases this is not possible because you do not have write access to a remote upstream repository. It is just used for pulling upstream changes in our forked repository.

Execute the following commands to add the upstream repository as a new remote location and display all remote locations currently defined.

As we hopefully implemented our new feature in feature branch, we can pull changes from the upstream master branch into our local copy of the master branch. Remember we are using a feature branch and master should be kept clean from local changes.

So now we have this older copy of the upstream master branch checked out and we would like to update it to the latest and greatest from the upstream master branch.

With the pull command above you pulled all changes from the upstream master branch into you local copy of master. Just to be sure let’s display all available branches, local and remote ones.

Branches with a name remote/<remote name>/<branch name> are remote branches that git knows about. Origin points to our forked repository and is also the default location for push operations.

So finally to rebase our feature branch to the upstream master branch we first need to checkout our feature branch via

Now we are able to rebase our changes to upstream master. Git basically pulls in all changes from the master branch and re-applies the changes we did in our feature branch.

There might be merge conflicts when git tries to apply you changes from your feature branch. You have to fix those changes, git add the fixed files and execute git rebase continue. Luckily this is not the case for your megafeature.

As we have successfully rebased our feature branch to upstream master we can now try to push changes made to our forked github repository.

Oh, this fails of course! The reason is that our local feature branch and the remote feature branch have a different commit history. The remote feature branch is missing the commits from master that we applied when rebasing on the current master branch.

So let’s try again, this time using the --force-with-lease option. You could also use -f or --force but --force-with-lease will stop you if someone else (our you) has modified the remote feature branch meanwhile. If you push with -f or --force anyways you might loose changes.

But as no one modified the remote feature branch while we did our rebase the force push goes through.

Our merge request (if we opened one already) is now updated to the latest upstream master branch and merging our feature should be a breeze. You might notify the upstream project maintainer that you feature branch is up to date and ready for merging

When working with upstream projects it might be that a project maintainer requests that you rework your git history before he is willing to merge your changes. For example this could be that case if you have plenty of commits with very small changes (e.g. fixed typos).

The general rule is that one commit should implement one change. This is not a hard rule, but usually works.

Let’s look at an example. For the implementation of our new feature that we would like to bring upstream we have the following commit history

We have updated README.md in the repository but there a three commits for this little change. Before bringing this upstream in our pull request, we would like to convert those three commits into a single one and also make the commit message a little more meaningful.

We execute the following command to start reworking our commit history

Git will drop us into our beloved editor (vi in this case), under Linux you could change the editor git uses by modifying the $EDITOR environment variable. We are going to see the following output:

Git automatically selected commit id bf2ef3c as the basis for our rebase. We could also have specified the commit id where we would like to start our rebase operation e.g.

In our editor of choice we can now tell git what it should do with the selected commits. Please go ahead and read the helpfull explanation text in comments (prefixed with '#') to get a better understanding of the operations supported.

In our case we would like to squash the last commits. So we change the lines with pick to squash until it looks like the following:

We would like to squash commits 0a5221d and 0e60d12 onto commit bf2ef3c. Keep in mind that git actually reverses the order of commits. So 0a5221d is the last commit we added.

If we save the file and quit our editor (I’m using vi here), git drops us into another buffer where we can finally modify the commits

We can see all three commit message and we are going to modify those messages until we are happy

When we are happy with new commit message we just save and quit our editor. Git will now rewirte the history and when we take look at the commit history again we will see our changes:

We only have commit 91d1ae2 now , which includes all three changes from the commits before.

So it’s OK to change the commit history of a feature branch that only you are using, but be careful when working on branches more than one developer is using.