> For the complete documentation index, see [llms.txt](https://avionics.rocketcommand.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://avionics.rocketcommand.org/guides/using-git-version-control.md).

# Using Git Version Control

Git is a version control protocol invented by the legend Linus Torvalds to help him develop the Linux kernel. We use it for the equally cool task of organizing and collaborating on our design files and codebase to help us develop rocket systems. Specifically, it allows us to:

1. Visualize a full history of every change, who made it, and why
2. Have separate people contribute to different parts of the codebase, even within the same file, at the same time
3. Keep everything in a central online work area and recover files at certain points in time if need be
4. Review changes before merging them into the central work area

### Terminology

Before any of this makes sense, a few terms you'll see constantly:

<table data-first-column-sticky data-search="true"><thead><tr><th width="175.77734375">Term</th><th>Definition</th></tr></thead><tbody><tr><td>Repository (repo)</td><td>The project itself. All its files plus the full history of every change ever made to them. The history is encoded in a way you won't directly see.</td></tr><tr><td>Commit</td><td>A saved snapshot of changes, with a message explaining what changed and why. Think of it as a checkpoint you can always come back to.</td></tr><tr><td>Branch</td><td>An independent line of work, split off from the main codebase, which is also a branch.</td></tr><tr><td>Merge</td><td>Combining a branch's changes back into another branch, usually main, once they've been reviewed.</td></tr><tr><td>Local</td><td>The copy of the repo living on your own computer. Changes here don't affect anyone else until you push them.</td></tr><tr><td>Remote</td><td>The copy of the repo hosted online (for us, on GitHub) that everyone syncs with.</td></tr><tr><td>Push / Pull</td><td>Sending your local commits up to the remote (push), or pulling other people's commits down to your local copy (pull).</td></tr><tr><td>Pull Request (PR)</td><td>A request to merge one branch into another, opened on GitHb so others can review it first.</td></tr><tr><td>GitHub</td><td>Git is the tool that tracks changes. GitHub is a website that hosts your git repos in the cloud and adds collaboration features on top, like PRs and code review. You could use git without GitHub, but we use both together.</td></tr></tbody></table>

### Getting Started

If you're new to git, here's the minimum you need before your first contribution:

1. **Install git** and set up a GitHub account if you don't have one. You can check if you have git installed by entering `git` in your terminal shell.
2. **Clone the repo** you'll be working in. Each project has repositories for hardware, software, and industrial design on GitHub, This downloads a local copy:

```bash
git clone repo-url
```

You can find the repo URL on GitHub underneath the Code dropdown:

<figure><img src="/files/E4gCXH2mU5Ru94chwdH9" alt=""><figcaption></figcaption></figure>

3. **Set your identity** so your commits are attributed correctly:

<pre class="language-bash"><code class="lang-bash"><strong>git config --global user.name "Your Name"
</strong>git config --global user.email "your@email.com"
</code></pre>

### Typical Workflow

Do all your development in feature branches, create a PR, then the DRI will merge your changes into main if approved.

1. Never commit directly to main, to checkout an existing branch or create a new branch to work in:

```bash
git checkout -b branch-name
```

2. Make any changes to the minimum set of files that would need changing in your IDE, KiCad, SolidWorks, etc.
3. Commit frequently as you go since small, focused commits are easier to review and easier to revert if something breaks.

```bash
## First, it's helpful to check the status of your files
git status
## Next, selectively add the files or add them all
git add .
## Lastly, commit with a brief, helpful message
git commit -m "fixed bug in X by implementing Y"
```

4. When you're ready for review, or just want to backup your branch online, push your local commits to remote:

```bash
git push -u origin branch-name
```

5. Head to the GitHub page for the repo, and create a PR from the Pull Requests tab at the top. Add helpful information, tag your DRI, and submit.
6. Await an approved merge or request for further changes from your DRI. If you're waiting long, ping your DRI again and a lead.

### Good Habits

1. **Pull before you branch** or restart work in a branch. Starting from a stale main is the #1 cause of painful merge conflicts.
2. **Keep PRs small.** A focused PR gets reviewed faster and more carefully than a huge one.
3. **Don't force-push to shared branches.** If you're not sure whether a branch is shared, ask before you force-push.
4. **Use `git status`** before and after you do any git operation. It never hurts and always keeps you in the loop.
5. **Use `git help` or `git help <command>`** to figure out the right way to use something. The internet is also plenty experienced with git.

### Reference

<table><thead><tr><th width="249.08203125">Task</th><th>Command</th></tr></thead><tbody><tr><td>Clone a repo</td><td><code>git clone &#x3C;url></code></td></tr><tr><td>Check status</td><td><code>git status</code></td></tr><tr><td>Create + switch to a branch</td><td><code>git checkout -b branch-name</code></td></tr><tr><td>Stage changes</td><td><code>git add &#x3C;file></code> or <code>git add .</code></td></tr><tr><td>Commit</td><td><code>git commit -m "message"</code></td></tr><tr><td>Push a new branch</td><td><code>git push -u origin branch-name</code></td></tr><tr><td>Push after that</td><td><code>git push</code></td></tr><tr><td>Pull latest changes</td><td><code>git pull</code></td></tr><tr><td>Switch branches</td><td><code>git checkout branch-name</code></td></tr><tr><td>See commit history</td><td><code>git log --oneline</code></td></tr><tr><td>Undo uncommitted changes to a file</td><td><code>git checkout -- &#x3C;file></code></td></tr><tr><td>Merge conflicts happened</td><td>Open the conflicting file, resolve the <code>&#x3C;&#x3C;&#x3C;&#x3C;&#x3C;&#x3C;&#x3C;</code> markers, then <code>git add</code> + <code>git commit</code></td></tr></tbody></table>

Remember Git is very forgiving, so don't worry too much about nuking the repository to the point it's unrecoverable. If you're ever stuck, pause and get help from your DRI or a lead.