Git HowTo

This page will get you started using Git.

Before you Begin

Git is exquisitely documented. Before you start using git take the time to read the first two sections of the manual here:

https://git-scm.com/documentation

The "Getting Started" and "Git Basics" sections are essential reading for anyone that wants to participate in the swarmathon.

Take Control of Your GitHub Identity

GitHub identifies you by your SSH key. Generate one with the command below. It's okay to leave the key's password blank, but you can add one if you like. Leave all other fields empty.

$ ssh-keygen -t rsa -b 4096 

Generating public/private rsa key pair.

Enter file in which to save the key (/home/robot/.ssh/id_rsa):

Enter passphrase (empty for no passphrase):

Enter same passphrase again:

Your identification has been saved in /home/robot/.ssh/id_rsa.

Your public key has been saved in /home/robot/.ssh/id_rsa.pub.

The key fingerprint is:

d8:e6:d9:0e:55:39:82:e0:1c:e9:cf:b8:85:11:81:d0 robot@swarmathon-builder

The key's randomart image is:

+--[ RSA 4096]----+

|  .o .+o         |

|    Eooo .   .   |

|     .o.. . +    |

|      oo   o .   |

|      .*S .      |

|      oo++       |

|       o+ .      |

|      .  o       |

|          .      |

+-----------------+

Now you have to upload your key to GitHub. There are instructions here:

https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/#platform-linux

Use Cabrillo's Repository

The flash key you received was made before there was a private repository for Cabrillo. This section will show you how to change the remote repository to Cabrillo's. First, check to see what remote you are currently using:

$ cd ~/rover_workspace 

$ git remote -v 

origin https://github.com/BCLab-UNM/Swarmathon-ROS.git (fetch)

origin https://github.com/BCLab-UNM/Swarmathon-ROS.git (push)

The remote repositories shown above are the main remotes. Switch to Cabrillo's remote with the commands below:

$ git remote remove origin

$ git remote add origin git@github.com:BCLab-UNM/Swarmathon-Cabrillo.git

$ git remote -v 

origin git@github.com:BCLab-UNM/Swarmathon-Cabrillo.git (fetch)

origin git@github.com:BCLab-UNM/Swarmathon-Cabrillo.git (push)

Now your repository's remote is set to Cabrillo and you're ready to work. Be sure to:

$ git fetch origin

$ git branch -d master

$ git checkout -b master origin/master

Create Your Own Branch

You should create a branch for yourself. You can do anything you want in your own branch. When your ready to test your branch the project's integrators will help you test and integrate your code. The first step is to create your branch locally:

$ git branch <replace-this-with-your-name>

Now check out your personal branch:

$ git checkout <replace-this-with-your-name>

Now push your new branch to Cabrillo's main repository

$ git push --set-upstream origin <replace-this-with-your-name>

You're now ready to work!

While You Work

While you're working you can see what files you've changed with this command:

$ git status

On branch mike

Your branch is up-to-date with 'origin/mike'.

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)

  (commit or discard the untracked or modified content in submodules)

modified: launch/achilles.launch

modified: run.sh

modified: src/ublox (untracked content)

no changes added to commit (use "git add" and/or "git commit -a")

You can see from the output that I have changed two files;

1. launch/achilles.launch
2. run.sh

The 'ublox' directory will always seem modified, you can ignore it. You should check in your changes often. Checking in your changes and pushing them into GitHub will protect you from data loss. Here's how to do it. For each file you've changed run the command:

$ git add <file-that-has-changed>

With your files added the git status command will change. For example:

$ git add launch/achilles.launch 

$ git add run.sh 

$ git status

On branch mike

Your branch is up-to-date with 'origin/mike'.

Changes to be committed:

  (use "git reset HEAD <file>..." to unstage)

modified: launch/achilles.launch

modified: run.sh

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)

  (commit or discard the untracked or modified content in submodules)

modified: src/ublox (untracked content)

Now git is telling you that your changes are ready to commit. You can commit them with the command:

$ git commit 

This will take you to a text editor. Type your message and save it with Ctrl-O. Exit the editor with Ctrl-X. Your changes are now committed to your local repository. Push them to GitHub with the command:

$ git push 

Now your changes are saved!