Git basics

Note: This guide assumes you use the Git CLI, but if you use a graphical client or an IDE integration, it still applies.

It also assumes you've read the Getting started section and already have Git configured and know about the clone sub-command.

Main commands

These are the most important Git commands you need to know about:

git pull

Downloads the changes from the remote repository for your current branch

git checkout -b <branch_name>

Creates a new branch from the state of your local copy with the given name. Whenever you intend to work on a change or feature for Max, you must work on a branch.

Branch names must follow this standard: module-storyNumber-changeName, where storyNumber is the story number in the module's Taiga board. An example of a branch name would be: InputManager-21-controllerDetectionFix

git switch <branch_name>

Change which branch you're currently editing. This will update the contents of your local directory to reflect that of the latest change on the branch.

git add <files>

Tells git that you want to add the changes you made on the provided files to your next commit. <files> is a list that can contain glob patters, for example **/*.h to add all the header files in all the directories.

git commit -m "<message>"

Creates a snapshot in time of the current state of your local copy of the repository. You should make commits often, with every small change being a commit, even if it does not compile at that point or if the feature or fix are not fully implemented.

Write commit messages in the imperative form, so they make sense if they're read as "This commit will <message>". For example: "This commit will Add Lambertian diffusion", "This commit will Fix overly long echo". Thus, messages like Removed unused code would not make sense in the phrase, so they're incorrect.

git push

This sends your change history for your current branch to the remote repository. You can push after every commit, but it's not strictly necessary, you can push whenever you need your changes to be on the remote.

You should only ever push to branches you created. In order for your changes to be part of Max, you'll first have to create a merge request and get it reviewed (explained in the following section).