Git Usage

Commits

A commit is a saved state of your repository. You should make a commit every time you complete a task (e.g. Add per-path auto choosers, Fix joystick inputs inversion, Tune chassis heading PID gains). This helps keep track of when new code is added. When you add changes through smaller, focused commits, you can isolate when a bug is introduced and easily roll back to a working state. See this article on atomic commits for more information.

Writing descriptive commit messages make it easy to see exactly what changed. Avoid focusing on how you made the change (that’s what the diff is for). Instead, highlight the what and why. By convention, commit messages are concise, begin with a capital letter, don’t use punctuation, and are in the imperative mood. If you want to include more information in a commit message, consider using the commit body.

Compare the following examples of good vs bad commit messages:

Good Commit Messages	Bad Commit Messages
Complete a single task	Include logic changes, formatting fixes, and refactors in one commit
Use the imperative mood: “Refactor swerve drive logic”	Are past tense, lowercase, or punctuated: “refactored swerve drive logic.”
Specific and provide context: “Fix swerve drive limiter bug for reliable drive control”	Are vague: “Fix bug” or “WIP”

For more on writing good commit messages, see this article. Standardized specifications such as Conventional Commits are also good ways to keep commit messages organized.

Branches

The main branch is where the working, tested version of the code lives during the build season. When multiple programmers are working on different changes, creating separate development branches can help prevent merge conflicts. For example, creating a seprate branch for vision code ensures that the code on the drivetrain branch isn’t affected. Making branches for each competition helps isolate fixes and ensures that code is still reviewed before merging to main.

To maintain a branch, you must stay up to date with main. A merge and a rebase are both ways of integrating changes from one branch into another, but they do it differently. A merge combines branches by creating a new merge commit that connects their histories. This is useful for shared branches where multiple developers are contributing simultaneously or merging a branch into main. A rebase rewrites the history of your branch sequentially and results in a clean, linear history. This is useful for a branch that only exists locally. Never rebase commits that have already been pushed to the remote repository, as this results in diverged commit histories.

• To merge: git fetch then git merge origin/main
• To rebase: git fetch then git rebase origin/main

It is a good practice to push to your branch frequently to back up your work in the remote repository and make it visible to other programmers using git push.

Repositories

Creating a new repository for different major projects or new seasons is a helpful way to keep track of projects. Repositories should have names that represent the purpose of its code, like “2026-rebuilt”, “2026-kitbot”, and “2026-offseason-turret”.

Clients

A Git client provides an interface for interacting with a Git repository.

For new Git users, GitHub Desktop is recommended because it presents a simple, graphical way to manage a Git repository. Creating a commit is as easy as selecting files, writing the commit message in a text box, and clicking a button.

Source control in VSCode also offers a simple interface for Git.

lazygit is an intermediate option that retains much of the power of Git’s command-line interface while being intuitive to use.

Git’s command-line interface is the most raw and powerful Git client. However, it may be difficult to learn.

Additional Resources

An in-depth tutorial can be found at the official Git website.

A guide for correcting common mistakes can be found at the Git flight rules repository.