Source Control Best Practices

Introduction

This page highlights source control considerations commonly encountered when contributing to ROS 2 projects. It is not intended to replace Git documentation. Instead, it focuses on ROS-specific recommendations and references to external resources where appropriate.

Avoid committing generated and temporary files

ROS 2 workspaces generate build artifacts that should generally not be committed to source control.

Sources of generated, temporary, and backup files

Colcon workspace artifacts

Common workspace artifacts include:

build/
install/
log/

The build/, install/, and log/ directories are generated by colcon build as part of a ROS 2 workspace. These directories are typically created at the workspace level rather than inside individual repositories.

If these directories appear within a repository (e.g. by accidentally calling colcon build in a wrong directory), they should not be committed to source control.

Python-generated files

Python generates several temporary files, including the __pycache__/ directory and files ending with *.pyc, *.pyo, and *.pyd when you run the program. None of these files should ever be committed to a repository.

IDE configuration files

Editors and IDEs often generate project-specific or user-specific configuration files.

Common examples include:

.vscode/
.idea/

Many ROS 2 repositories ignore editor-specific files such as .vscode/ and .idea/. Contributors should avoid committing personal editor configuration unless it is explicitly required by the repository.

Editor temporary and backup files

Some editors like Vim create backup files ending with ~ (for example, test.py~) and temporary files ending with *.swp, *.swo, and similar. These should never be committed to the repository.

Operating system files

Operating systems may generate metadata files such as .DS_Store (macOS) and Thumbs.db (Windows). These files should never be committed to a repository.

Before committing changes, review the files included in a commit. Ensure that generated and temporary files have not been added accidentally.

Gitignore placement options

Repository .gitignore

Use the following rule of thumb when deciding whether a file belongs in a repository-specific .gitignore or your global .gitignore.

If the file will be present on every developer’s computer, put it in the repository .gitignore.

Global .gitignore

A global gitignore can help prevent accidentally committing files that are unrelated to a repository, such as operating system metadata files or personal editor configuration.

Git supports configuring a global excludes file through the core.excludesfile configuration option.

For example:

$ git config --global core.excludesfile ~/.gitignore_global

A global gitignore is useful for excluding files that are specific to a developer’s machine or editor and are not intended to be committed to any repository.

Credential helpers

When contributing to ROS 2 repositories, contributors will often interact with Git hosting services such as GitHub.

SSH keys and Git credential helpers can simplify authentication. Avoid repeatedly entering credentials when pushing changes or interacting with remote repositories.

Rather than duplicating setup instructions here, refer to the official GitHub and Git documentation for recommended configuration steps.

Developing on shared robots

When developing on a shared robot or other remote system, never copy your private SSH keys there and never run a remote SSH agent or credential helper that could cache your keys and make them available to others. Instead, use a local SSH agent on your private machine and use ssh -A to temporarily forward this agent to the remote end. Using a forwarded SSH agent makes your SSH keys available on the remote machine and it also relieves you from repeatedly entering your SSH key passphrase. If all developers log in as the same user, there is a risk that someone else could reuse your forwarded agent, so try to limit the amount of time spent in an ssh -A shell to the very minimum. Refer to the official Git SSH documentation for setup instructions.

If the remote machine is trusted, you can also set up a (read-only) deploy key or deploy token so that it has access to your private repos. If you need to push from this machine, use the SSH agent forwarding described above.

Additional resources

Example ROS 2 .gitignore files include: