Skip to main content
Learn best practices for using Git with your ROS2 workspace to track changes and collaborate effectively.

​
What to commit

Commit these files and directories to version control:
  • Source code in src/ directory
  • Configuration files
  • Custom launch files
  • Documentation files
  • Package manifests (package.xml)
  • Build configuration (CMakeLists.txt, setup.py)

​
What not to commit

Do not commit these generated directories:
  • build/ - Build artifacts
  • install/ - Installed binaries
  • log/ - Build logs
  • .vscode/ - Workspace files (already in .gitignore)
  • Temporary files
These directories are automatically excluded by the .gitignore file in the project.

​
Git workflow for custom packages

​
Initial setup

1

Navigate to workspace

cd /workspace/turtlebot3_ws
2

Initialize Git repository

If not already initialized:
git init
3

Add remote repository

git remote add origin <your-repository-url>

​
Committing changes

1

Check status

git status
Review which files have changed.
2

Stage changes

Add specific files:
git add src/my_package/
Or add all changes in src:
git add src/
3

Commit changes

git commit -m "Add custom navigation package"
4

Push to remote

git push origin main

​
Managing TurtleBot3 source packages

The TurtleBot3 packages are cloned from upstream repositories in post-create.sh: 
git clone -b jazzy https://github.com/ROBOTIS-GIT/DynamixelSDK.git
git clone -b jazzy https://github.com/ROBOTIS-GIT/turtlebot3_msgs.git
git clone -b jazzy https://github.com/ROBOTIS-GIT/turtlebot3.git
git clone -b jazzy https://github.com/ROBOTIS-GIT/turtlebot3_simulations.git

​
Working with upstream packages

If you modify TurtleBot3 source packages:
1

Navigate to package directory

cd /workspace/turtlebot3_ws/src/turtlebot3
2

Create a feature branch

git checkout -b my-feature
3

Make and commit changes

git add .
git commit -m "Modify robot configuration"
4

Push to your fork

Fork the repository on GitHub first, then:
git remote add myfork <your-fork-url>
git push myfork my-feature

​
Ignoring build artifacts

The project includes a .gitignore file that excludes: 
build/
install/
log/
.vscode/
Verify ignored files: 
git status --ignored

​
Branching strategy

​
Feature branches

Create separate branches for new features: 
git checkout -b feature/autonomous-navigation
Develop and test your feature, then merge: 
git checkout main
git merge feature/autonomous-navigation

​
Experiment branches

For experimental work that might be discarded: 
git checkout -b experiment/new-sensor
If the experiment fails, simply delete the branch: 
git checkout main
git branch -D experiment/new-sensor

​
Cloning your workspace

To clone your workspace on a new machine:
1

Clone the repository

git clone <your-repository-url> turtlebot3_jazzy_devcontainer
cd turtlebot3_jazzy_devcontainer
2

Open in VS Code

code .
3

Reopen in container

Press F1 → “Dev Containers: Reopen in Container”The post-create.sh script will clone TurtleBot3 packages and post-start.sh will build the workspace automatically.

​
Handling package.xml files

Package manifests should always be committed. They contain:
  • Package metadata
  • Dependencies
  • Maintainer information
  • License information
Example commit: 
git add src/my_package/package.xml
git commit -m "Update package dependencies"

​
Checking repository verification

The post-create.sh script verifies package integrity: 
PACKAGE_COUNT=$(find src/ -name "package.xml" 2>/dev/null | wc -l)
echo "Verified $PACKAGE_COUNT package.xml files"
This ensures all packages have proper manifests before building.

​
Best practices summary

  • Commit source code frequently with descriptive messages
  • Never commit build/, install/, or log/ directories
  • Use branches for features and experiments
  • Keep package.xml and build files in version control
  • Document changes in commit messages
  • Fork upstream packages before modifying them
  • Test builds before pushing to remote

Build docs developers (and LLMs) love

Get started for freeTalk to us