Add a short tutorial on correct setup of a global .gitignore

[peci1]

Issue Type

• 🐛 Bug / Problem
• ✏️ Typo / Grammar
• 📖 Outdated Content
• 🚀 Enhancement

Generated by Generative AI

no

Distribution

any

Description

As surfaced in e.g. https://github.com/ros2/rmw_fastrtps/pull/855/files#r2547924882 , at least beginner users have often problems when using git. One of the problems is committing files that should not be commited, like build/logs/install folders, .vscode folder and similar.

Although not directly ROS-related, I think that having a short tutorial on proper Git setup would be nice. It could also mention the use of credential helpers, how to create SSH keys and such.

Affected Pages/Sections

No response

Screenshots or Examples (if applicable)

No response

Suggested Fix

I think this tutorial could be created as a part of the ongoing documentation improvement effort.

Additional Context

No response

[SuperJappie08]

When adding such an example for VSCode, it might be important to specify that they need to ignore the .vscode/settings.json specificily.

Since there are certain contents of the .vscode folder people would want to commit, such as tasks.json.

(I'm not an active VSCode user, but I can imagine the confusion it can cause with beginners if they want to add something but forget they set something like this up.)

(An example for the GitHub gitignore templates)
https://github.com/github/gitignore/blob/86922aee426c32ffb6098f9a38c42da75169501e/VisualStudio.gitignore#L410-L415

[peci1]

Since there are certain contents of the .vscode folder people would want to commit, such as tasks.json.

That depends on what you want to achieve. In the case of "public" ROS packages (i.e. packages meant for broad community), the whole .vscode folder should be ignored. In case you work for a company that dictates the use of VSCode and wants developers to share their development environments, then yes, some parts of the .vscode folder might be indeed wanted in the repo. I think this is common to all IDEs that make config folders in the project, e.g. .idea for Jetbrains IDEs etc. But each developer knows which tools he/she uses and thus should know which folders should be excluded.

[SuperJappie08]

You are right, but it might be nice to make a distinction in such a tutorial for two usescases:

• Absolute ROS Beginner as a user
• Core ROS Development starter guide

This could sort of be a side note along the lines of:

In Core ROS repositories, one should ignore editor-specific files and folders.
This ignoring needs to be done at local repo/user level.

EDIT: Formatting

[ros-discourse]

This issue has been mentioned on Open Robotics Discourse. There might be relevant details there:

https://discourse.openrobotics.org/t/ros-news-for-the-week-of-november-17th-2025/51103/1

[wjwwood]

From the issue triage meeting: I put this on the agenda for the next ROS PMC meeting.

[mjcarroll]

From the PMC meeting we discussed that we wouldn't want to maintain parallel documentation about how gitignores work or editor-specific configurations.

However, it may be helpful to introduce a documentation page that has references to these concepts as well as ROS-specific considerations, which is something that we previously had on the ros wiki.

I'm going to mark this help wanted if someone gets to it before I do.