***** Updated version of this blog post is posted here: How to Save Your ROS 2 Project on GitHub *****

In this tutorial, I will show you how to store your ROS 2 project in a repository on GitHub.

In case you’re not familiar with GitHub, GitHub is an online platform specifically designed for software development. It offers several key functionalities:

• Version control: This allows developers to track changes made to code over time. Imagine it like a time machine for your code, letting you revert to previous versions if necessary.
• Code storage: GitHub acts as a secure and centralized location to store and manage code projects. Think of it like a cloud storage specifically for your code.
• Collaboration: Teams can work together on projects by sharing code, discussing changes, and merging different contributions seamlessly.
• Open-source contribution: GitHub is a hub for open-source projects, where developers can publicly share their code, contribute to existing projects, and learn from others.

Prerequisites

• You have created a ROS 2 workspace.
• You have created a ROS 2 package.

I have created a ROS 2 workspace that has a folder called mycobot_ros2 (i.e. /home/ubuntu/ros2_ws/src/mycobot_ros2).

Inside the mycobot_ros2 folder, I have two ROS 2 packages, mycobot_description and mycobot_ros2. You can see the complete repository here on GitHub.

Directions

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

Check the git version you have.

git --version

Configure Git

Configure your git username and email.

git config --global user.name "John Doe"
git config --global user.email "johndoe@example.com"
git config --global init.defaultBranch main

Initialize Git

Move to inside your project folder.

cd  ~/ros2_ws/src/mycobot_ros2/

Initialize the folder as a Git repository by running:

git init

Add and Commit the Files to Your Local Repository

Add the files in your folder to the repository with the following command:

git add .

Commit your staged files to your local repository with:

git commit -m "Initial commit"

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.”

Name your repository, add a description (optional), and choose whether the repository will be public or private.

Click “Create repository.”

Link the Local Repository to the Remote Repository

After creating your repository on GitHub, you’ll get a URL for that repository. Link your local repository to GitHub with:

git remote add origin <repository-URL>

Log in to your GitHub account.

Generate your personal access token. Read about how to do this here.

Finally, push your code from your local repository to GitHub with:

git branch --set-upstream-to=origin/main main

The command git branch –set-upstream-to=origin/main main links your local branch named “main” with its corresponding remote tracking branch “origin/main” on GitHub. This establishes a connection between the two branches, making it easier to keep them in sync in the future.

git push origin main --force

Type your GitHub username and personal access token.

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

Let’s add our LICENSE file again.

Go to your repository’s main page on GitHub.

Click on the “Add file” button on the top right corner.

Choose “Create new file”.

In the file name field, type LICENSE or LICENSE.md (all uppercase).

Click on “Choose a license template”.

Click OK when it asks about unsaved changes.

On the left side of the page, review the available licenses and select the one you want to use.

You can optionally add your name, year, and any additional comments in the file content below the chosen license text.

Click Review and Submit.

Click “Commit changes” (twice) to create the license file and add it to your repository.

Now make sure we get these changes locally.

Open a terminal window, and type:

git branch --set-upstream-to=origin/main main

git fetch

git status

git pull

I want GitHub to ignore the .vscode/ folder in the future.

touch .gitignore

Open the .gitignore file in a text editor.

gedit .gitignore

Add the following line to the file:

.vscode/

Save and close the file. This line tells Git to ignore the .vscode directory, meaning any files or subdirectories within .vscode/ will not be tracked or committed.

git add .gitignore

git commit -m "Add .gitignore to exclude .vscode directory"

git push 

git rm -r --cached .vscode

git commit -m "Stop tracking .vscode directory"

Remove the Need to Use a Username and Password

If you want to not have to use a username and password every time you run “git push”, you can use SSH keys. This page has the instructions on how to do that.

Here is the process…

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

ssh-keygen -t ed25519 -C "your_email@example.com"

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

Start the ssh-agent in the background.

eval "$(ssh-agent -s)"

Add your SSH private key to the ssh-agent:

ssh-add ~/.ssh/id_ed25519

Add the SSH public key to your Git server.

cat ~/.ssh/id_ed25519.pub

Copy the entire result to your clipboard by highlighting everything and copying it.

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

Look for “SSH and GPG keys”.

Add a new SSH key, pasting the copied key there.

Go back to the main page of your repository on GitHub and find the SSH URL by clicking the green button labeled “Code”.

Copy the SSH URL that is in there.

Switch your repository’s remote URL to SSH by going to your Ubuntu Linux terminal window, and moving to the directory of your repository.

cd <path to your your local repository>

git remote set-url origin git@github.com:username/repository.git

That’s it!

Using SSH keys is a more secure and convenient method for machines where you regularly push changes, as it doesn’t require entering your credentials after the initial setup.