Working on my projects

Here a step-by-step guide to work on git for some projects I maintain.

This guide assumes:

• you like Linux, you USE Linux
• you know how to work with the terminal
• the instructions are based on Ubuntu, but they should be easily used on other systems.
  The main difference could be the application to install code. apt-get for Ubuntu, yum for Red Hat/CentOS, ecc.
• you know how to set up a cross compiler for different microcontroller under Linux

Introduction

The most important thing to remember working with git, is that normally ALL the operations are LOCAL to your machine !
Only few specific and explicitly called operations operate on a remote server, in our case, github.

Specifically :

• The first time, when we clone the project from github
• Every time we want to update our code from github
• Every time we want to save our work on github

First time

git Installation

The first time we want to clone the project from github.
How we do that ?
First of all we must have git on our machine.
So if you don't already installed it, open a terminal and type :

• sudo apt-get update
• sudo apt-get install git

(note, I'm using for this article, the git version 1.9.1 on a Ubuntu 14.04 LTS)

After the installation, is better to set it up with some basic info :

• git config --global user.name "your name"
• git config --global user.email "youremail@domain.com"
• git config --list will show the configuration for your git

For example :

git config --global user.name "John Smith"

git config --global user.email "jsmith@mystery.com"

I'm not sure if is valid for every type of operation, but it is possible github will require a SSH key in order to clone/update a project.
In that case I strongly recommend to follow this brief tutorial about how to generate and deploy an ssh key with github.

At this point you are ready to clone the project from github !

Clone a project

Cloning is the act that duplicate on your hard drive what is present in a remote git repository, in this case github.
The cloning is strongly suggested in case you want to collaborate to the project.
Cloning the project recreate on your local machine the project and it's history and allows to merge it back on github if you do modifications.

First of all create or go on a directory that will host the project.

For example, create a directory called SteveProjects on your home environment :

• cd ~
• mkdir SteveProjects
• cd SteveProjects

Now is possible to use git to clone a project, with the command :

• git clone URL_repository

That's it !

On your directory Projects, will exist a directory called as the project name, containing the project.

Download a project

In case you are not interested to collaborate to the project but wants to have the project on your machine, or in case you don't want to install git or generate SSH keys, from github is possible to download the project as a zip file.

Update project

Now that you have the project on your machine, to keep it updated is even easier.

Simply go in the project directory and issue the command : git pull

• cd ~/Projects/project_name
• git pull

That's it !  If the code on the github is changed, it will be updated on your machine

Working on the project

Commit the project

If you want to collaborate to a project, you can modify the code on your machine, and keep track of the modifications locally, using git.
Issuing the command git status returns the status of the modifications made to the code.

Every time you modify a file, git status will indicate a modification.
Every time you will have to add it with:

git add file_name

git add * will add all the modified files.

Then it will be possible to commit the file with:

git commit file_name

All these operations are LOCAL to your machine !

If you are a registered collaborator to the project (ask me), then you should be able to "push" your modifications in the github with:

git push

Working protocol

In order to reduce the conflict between developer, I suggest this protocol:

1. Clone the project
   git clone URL_of_github_project
2. Create a branch
   git checkout -b branch_name
3. Work on your modifications, add and commit regularly
4. When is time to push the modifications:
   git push origin branch_name
5. If allowed, merge the branch on the master.