Git : Basic Usage

This section will briefly describe the most important tools that the git software provide to developers and how we recommend using them. For further tools and customizations, check the sidebar for other sections dedicated to the usage of git.

Repository setup

You will first need to create your own fork (a repository hosted on github) of the code by clicking in the "Fork" button that appears in the upper right corner of the screen. Then you need to clone that repository in your working machine by running:

$ git clone https://github.com/[your_username]/lio.git [workdir_name]

You can check the exact link to use as source by going to the page of your fork and clicking in the green button that says "Clone or Download". Then, you should set up a remote that points to the original distribution. Enter the working directory you just created and run:

$ git remote add upstream https://github.com/MALBECC/lio.git
$ git remote -vv
origin      https://github.com/[your_username]/lio.git (fetch)
origin      https://github.com/[your_username]/lio.git (push)
upstream    https://github.com/MALBECC/lio.git (fetch)
upstream    https://github.com/MALBECC/lio.git (push)

Branch setup

It's advisable that any modification you wish to make on the code should be through a separate branch. So first you need to create that local branch from the source branch you wish to use as starting point (usually develop):

$ git checkout develop
$ git checkout -b [work_branch]
$ git branch -vv
develop          ae24a00  [origin/develop] Description of last commit in develop.
master           ae12c12  [origin/master] Description of last commit in master.
[work_branch]    ab04b15  Description of last commit in develop.

You may notice that the develop and master branches are linked to the branches that exist in your git repository, but your new branch is not (in particular, because there is no work_branch only exists in your local repository). To create that remote branch in your git repository and link it to your local one, run:

$ git push -u origin [work_branch]

You are now ready to start working in your branch.

You can now start making modifications on your copy of the code. You can check files you changed with git status. You can add all modified files that your wish to keep with git add [file_name], and once you have a status you wish to keep, you can run git commit to save them (you will be asked to provide a description for the commit). Try not to make trivial commits or gigantic ones; use them to save significant modifications. For more detailed on how to work with git, you can check the other sections we have here.

Updating changes

As you are working on your contributions, others will be doing so as well. When they incorporate their changes in the official fork, you will need to update your own copy. First you need to get the last up to date version of develop. You can also update the develop copy in your remote fork as well.

$ git checkout develop
$ git pull --ff-only upstream develop
$ git push origin develop

Now you will need to rebase your work over the updated develop. For this, you will run:

$ git checkout [work_branch]
$ git rebase develop

You may need to resolve some conflicts as git tries to apply your modifications over the updated base branch. Once you do, you should update the copy of your branch that exists on your github fork, but since you just basically "re-wrote" all your work, you will need to force the changes. Always do forced operations with caution.

$ git push -f origin [work_branch]

Once you have finished, and as long as your modifications are based on the most up-to-date version of develop, you can request that your changes be incorporated on the official code by performing a pull request from github. Go to your fork, click on the "New Pull Request" button and set up the appropriate repositories/branches. Be aware that once this is open, any modifications you push to the branch in the github repository will be included in the pull request (you might actually be requested to make some changes this way).