Git and vcstool

Git records changes to files over time. It enables you to inspect history, develop work on branches, and collaborate through a remote service such as GitHub.

Git concepts

Term	Meaning
Repository	A project and its Git history
Commit	A saved snapshot with a message
Branch	A named line of development
Remote	A repository stored elsewhere, such as on GitHub
Working tree	The files currently checked out
Staging area	Changes selected for the next commit

Configure your identity

Git stores an author name and email in every commit:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Inspect the configuration:

git config --global --list

Clone a repository

git clone https://github.com/ros-industrial/ros2_i_training.git
cd ros2_i_training

Typical workflow

Check the current state:

git status

Create and switch to a branch:

git switch -c workshop-notes

Inspect unstaged changes:

git diff

Select changes and create a commit:

git add notes.txt
git commit -m "Add workshop notes"

Inspect the history:

git log --oneline

Download changes from the remote and upload local commits:

git pull
git push

Pushing requires permission to the remote repository. When contributing through a fork, push the branch to your fork and open a pull request against the upstream repository.

HTTPS and SSH remotes

An HTTPS remote looks like:

https://github.com/ros-industrial/ros2_i_training.git

An SSH remote looks like:

git@github.com:ros-industrial/ros2_i_training.git

HTTPS is simple for read-only access. SSH is convenient for regular authenticated pushes after an SSH key has been configured.

Inspect the configured remotes:

git remote -v

Change the URL of the remote named origin:

git remote set-url origin git@github.com:ros-industrial/ros2_i_training.git

Good habits

Run git status frequently.
Work on a branch rather than directly on main.
Keep commits focused on one logical change.
Write commit messages that explain the change.
Review git diff before committing.
Pull recent upstream changes before beginning new work.

Git exercise

This exercise uses a new local repository and does not require GitHub access:

mkdir -p ~/ros2_workshop/git_exercise
cd ~/ros2_workshop/git_exercise
git init
git switch -c workshop-notes
touch notes.txt
git status
git add notes.txt
git commit -m "Add workshop notes"
git log --oneline

If Git refuses to create the commit, configure your author name and email as shown earlier on this page.

Managing several repositories with vcstool

A ROS 2 workspace can depend on several Git repositories. vcstool reads a .repos file and checks out each repository at the requested branch, tag, or commit.

Install it if necessary:

sudo apt update
sudo apt install python3-vcstool

Example dependencies.repos:

repositories:
  example_interfaces:
    type: git
    url: https://github.com/ros2/example_interfaces.git
    version: jazzy

Import the repositories into a workspace:

mkdir -p dev_ws/src
cd dev_ws
vcs import src < dependencies.repos

Inspect their versions and local changes:

vcs status src

The space before < is optional to Bash but is kept here for readability. The operator redirects the contents of dependencies.repos into vcs import.