1.3 Save ROS code on GitHub

In this tutorial, we will create a ROS 2 workspace and store the project in a repository on GitHub.

ROS 2 has been designed with different layers. For users, the workspace is a folder that is the central location for organizing and developing your robot project. It contains all the code, data files, and configuration scripts.

ROS2 workspace structure

WorkSpace --- User workspace
    |--- build：temporary files during compiling
    |--- install：every package here has a sub installation directory
    |--- log：log files
    |--- src：the source code
        |-- C++_package_1
            |-- package.xml：meta information about the package
            |-- CMakeLists.txt：how to build the code within the package
            |-- src：the source code for the package
            |-- include/<package_name>：the public headers for the package
            |-- msg：messege interface files
            |-- srv：service interface files
            |-- action：action interface files
        |-- Python_package_1
            |-- package.xml：meta information about the package
            |-- setup.py：instructions for how to install the package
            |-- setup.cfg： set it when has executables, so ros2 run can find
            |-- resource/<package_name>：marker file for the package
            |-- test：related test files
            |-- <package_name>：a directory with the same name as your package, used by ROS 2 tools to find the package, contains __init__.py
        |-- other_packages...

Create a workspace

Open a terminal, and type the first two lines of command to create your workspace. The src folder inside the workspace is where all your code will go for your robot.

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
# git clone a repo or create a package
ros2 pkg create --build-type ament_cmake --license Apache-2.0 mec_mobile
ros2 pkg create --build-type ament_python --license Apache-2.0 <package_name>
# optional arguments --node-name and --license. 

We don’t need any code in our workspace now, just run the command below to build the workspace.

cd ~/ros2_ws
colcon build
colcon build --packages-select package_name --symlink-install 
# --symlink-install saves rebuild every time you tweak python scripts

This colcon build command needs to be run in the root of your workspace whenever you make additions or changes to the code. Type following command after colcon build:

dir

You will see three folders that are automatically created when you run the colcon build:

• build: This is where ROS 2 temporarily stores files while it’s compiling.

• install: The finished, ready-to-use parts of your robot’s software are placed.

• log: Keeps track of what happened when you built your code.

We can run the following command to make sure this workspace will be found any time we open a new terminal window.

echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

Git and Github

It's always a good idea to keep code backed up and version controlled. Using Git with an online service like Github is an easy way. Git is also a useful tool for multiple developers working on a project, or developing on multiple machines. Here I assume you already got a GitHub account.

Install Git

The first thing you need to do is install Git. Open a new terminal window, and type:

sudo apt-get update
sudo apt-get install git -y

Check the git version you have.

git --version

Configure Git

Configure your git username and email.

git config --global user.name "JohnSmith"
git config --global user.email "[e-mail]"
git config --global init.defaultBranch main

We'll use SSH to authenticate. So if you haven't got that set up already, take a look here.

Connecting to GitHub with SSH

If you want to not have to use a username and password every time you run “git push”, you can use SSH keys. Here is the process:

1. Generate an SSH key pair (if you don’t already have one) by running:

ssh-keygen -t ed25519 -C "[e-mail]"
# This creates a new SSH key, using the provided email as a label.

When you get prompted for a password or saving location, just keep pressing Enter, which will accept the default.

1. Start the ssh-agent in the background.

eval "$(ssh-agent -s)"

1. Add your SSH private key to the ssh-agent:

ssh-add ~/.ssh/id_ed25519

1. Copy the SSH public key to your clipboard.

cat ~/.ssh/id_ed25519.pub
# Then select and copy the contents of the id_ed25519.pub file

1. Go to your GitHub account “Settings” by clicking your profile icon in the upper right.

1. In the "Access" section of the sidebar, click SSH and GPG keys. Then click New SSH key or Add SSH key.

2. In the "Key" field, paste the copied key as an “Authentication Key”. Also add a title such as laptop.

3. Click Add SSH key.

Test the SSH:

1. Go back to the main page of your repository on GitHub. Copy the SSH URL of the repo.

1. Back to your Ubuntu Linux terminal window, and moving to the directory of your repository, then run git clone + ssh. For example:

cd  ~/ros2_ws/src/my_package1/
git clone COPYED_SSH

Switch your repository’s remote URL to SSH

Go to your Ubuntu Linux terminal window, and moving to the directory of your repository. For example:

cd  ~/ros2_ws/src/mec_mobile/
git remote set-url origin [e-mail]:rbtlabs/mec_mobile.git

To confirm everything is setup properly, type:

git pull

If you get asked about the authenticity of the host, just type yes and press Enter.

Create the Remote Repository on GitHub

Go to GitHub and log in. Click on the “+” icon in the upper right corner and select “New repository.”

Give the package a name (usually same as in ROS), choose to make it public or private, and then we skip the "Initialize" options and hit "Create Repository".

Push the package to the remote repo​

Now we need to push our local content to this repo. Open a terminal in your ros project directory:

cd ~/ros2_ws/src/mec_mobile/

We can run the following commands with our username and repository name substituted. If you've never used Git on this computer before, you may also need to set a username and email address (it will tell you how).

git init
git add .
git commit -m "First Commit"
git branch -M main
git remote add origin [e-mail]:<GITHUB_USERNAME>/<REPO_NAME>.git
git push -u origin main

These commands:

• Initialize git for the directory

• Stage the whole directory (ready to be committed)

• Create a commit with a message

• Create a main branch

• Set the URL link for the cloud repo to push to, and give it the name origin

• Push the main branch to the origin repo

Origin refers to your GitHub repository, and main is the name of your branch. The terminal will respond to let us know it has been pushed.

Now if you go back to GitHub, you can see your repository.

Git Command Overview

When you make changes to your code on your computer, and want to get these code changes saved to GitHub, here is how you do it:

git add . 
# This command picks up all your new code changes and gets them ready to be saved.

git commit -m "description of changes" 
# This command saves the changes on your computer with a message for what you did.

git push 
# This command sends all your saved changes to GitHub.

You’ll repeat these three steps each time you want to update your code on GitHub.

And if you’re working with other people, you should always download their changes first using git fetch, git status, and then git pull (one command right after the other) before you start working.

git fetch checks GitHub to see what changes exist – it’s like looking at a list of updates available but not downloading them yet. It tells you what’s different between your code and GitHub’s code.

git status shows you exactly what’s different between your local code and the code on GitHub after you’ve fetched. It’s like comparing your version with GitHub’s version to see what’s changed.

git pull actually downloads those changes from GitHub to your computer, bringing your local code up to date. It’s like clicking “download” on those updates you found with fetch and status.

These three commands help you safely check for and get any updates before you start working, which helps avoid conflicts with other people’s code changes.