How to Git

This page introduces Git (version control software) and GitHub (cloud-based hosting) and explains how we use them at Longhorn Racing Solar (LHRS). Our Github can be found here:

https://github.com/lhr-solar

What is Git?

Git is a version control system that tracks changes to files in a repository. Think of it as a history log for your code, letting you:

Save progress at different points using commits
Work on multiple branches of code in parallel
Merge code changes together safely

You can download Git here: https://git-scm.com/ .

What is GitHub?

GitHub is a platform that hosts Git repositories in the cloud. While Git can be used locally, GitHub makes it easy for us to:

Share code across the team
Collaborate on features without overwriting each other
Keep a secure, central version of our repositories

All Longhorn Racing Solar repositories are hosted on GitHub.

How to join the GitHub

To contribute to LHRS repositories, you need a GitHub account and access to our organization.

Steps to Join

Create a GitHub account if you don’t already have one: https://github.com/signup
Share your GitHub email and username with your LHRS team lead. They will have to invite you to the Github organization.
Organization access
- The GitHub admin will add you to the LHRS organization, which houses all our code repositories.
- All repositories are public, so anyone can view them.
- To make changes (push commits, create branches, open PRs), you must be a member of the organization.

✅ Once added, you’ll have full access to collaborate on LHRS projects and follow the Git workflow outlined in this guide.

Setting Up SSH Keys (Required)

Before you can interact with our repositories, you must configure SSH authentication. This prevents you from needing to type your GitHub username and password every time you clone, pull, or push.

How it works:

You generate a pair of cryptographic keys (public + private).
The public key is added to your GitHub account.
The private key stays on your computer.

👉 Follow GitHub’s official guide: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account .

Cloning a Repository

To work on LHRS code locally, you need to clone the repository.

git clone <repository-URL>

Finding the Repository SSH URL

Go to the repository on GitHub.
Click the green Code button (top-right).
Select the SSH tab.
Copy the link (it will look like git@github.com:lhr-solar/<repo>.git).

⚠️ Always use the SSH link instead of HTTPS.

Cloning Example

git clone git@github.com:lhr-solar/lhr-solar.github.io.git

This creates a local copy of the repository in whichever folder you run the command from.

How to Add Git to an Existing Project

Sometimes you already have a project folder on your computer that you want to start tracking with Git. Instead of cloning, you’ll initialize Git in place.

Steps

Navigate to your project folder
cd path/to/your/project
Initialize Git
git init
This creates a hidden .git folder where Git stores its history.
Add a remote repository
If the project should live in the LHRS GitHub organization, first create a new repository on GitHub (through the web UI). Then link it to your project:
git remote add origin <repo-ssh-url>
Stage and commit your files
git add -A git commit -m "Initial commit"
Push to GitHub
git branch -M main git push -u origin main

✅ Your local project is now version-controlled and connected to GitHub.

Staying Up to Date

Other LHRS members will push changes to GitHub. To sync your local copy:

git pull

Run this frequently—especially before creating a new branch or merging.

Working with Branches

Branches let us develop features in isolation, without breaking the main codebase.

Main branch → main (the latest official code)
Feature branches → Your own branch for a specific task or issue

Creating a Branch

git checkout -b <branch_name>

Switching Branches

git checkout <branch_name>

Listing Branches

git branch       # Local only  
git branch -a    # Local + remote

Committing & Pushing

Check Status

git status

Tells you which files are modified, staged, or untracked.

Stage Files for Commit

git add <file>       # Stage one file  
git add .            # Stage all changes in current folder (excludes deletions)  
git add -A           # Stage all changes across repo, including deletions  
git add -u           # Stage modifications and deletions, but not new untracked files

Commit Changes

git commit -m "Clear, descriptive message"

Push Changes

git push

For a new branch:

git push --set-upstream origin <branch_name>

Using .gitignore

A .gitignore file tells Git which files or folders to ignore when tracking changes. This is important because projects often generate temporary, build, or backup files that don’t belong in version control.

Why It Matters

Keeps the repository clean.
Prevents large/unnecessary files from bloating Git history.
Avoids committing sensitive or machine-specific files (like editor settings).

Example: Common Files to Ignore for KiCAD

Create a .gitignore file in your repo’s root directory and add patterns like:

# For PCBs designed using KiCad: https://www.kicad.org/
# Format documentation: https://kicad.org/help/file-formats/

# Temporary files
*.000
*.bak
*.bck
*.kicad_pcb-bak
*.kicad_sch-bak
*-backups
*.kicad_prl
*.sch-bak
*~
_autosave-*
*.tmp
*-save.pro
*-save.kicad_pcb
fp-info-cache
~*.lck
\#auto_saved_files#
*.log

# Netlist files (exported from Eeschema)
*.net

# Autorouter files (exported from Pcbnew)
*.dsn
*.ses

# Exported BOM files
*.xml
*.csv

#Mac Specific
.DS_Store

# JLCPCB Production Files
Production/

# Backups
*-backups/*

Adding a .gitignore

Create the file:
touch .gitignore
Add ignore patterns (see above).
Commit it like any other file:
git add .gitignore git commit -m "Add .gitignore"

👉 Tip: Once a file is tracked by Git, adding it to .gitignore won’t remove it from history. You need to untrack it first:

git rm --cached <file>

Merging & Resolving Conflicts

At LHRS, all feature branches are merged into main using GitHub Pull Requests (PRs). This ensures code is reviewed and approved before being added to the main branch.

Steps for Merging via GitHub

Push your feature branch to GitHub:
git push --set-upstream origin <your_branch>
Go to the repository on GitHub and open a Pull Request (PR) from your branch into main.
Assign reviewers and address any comments or requested changes.
Once all feedback is addressed, two team members must approve the PR before it can be merged.
After approval, merge the PR using GitHub’s Merge button.

Resolving Merge Conflicts

If your branch has conflicts with main, GitHub will notify you in the PR.
Conflicts must be resolved before the PR can be merged.
You can resolve conflicts using:
- GitHub’s web editor (directly in the PR)
- Local machine + git pull + git merge → push updates to the PR

⚡ Tip: VSCode’s merge editor is helpful if you prefer resolving conflicts locally.

Working with Submodules

Some LHRS repositories use Git submodules to include external code or shared libraries. Submodules require a few extra steps to set up and keep updated.

Adding a Submodule

To add a new submodule:

git submodule add <repo_url> <path/to/submodule>
git commit -m "Add submodule"

This links the external repository at the given path. Submodules must be committed like normal files.

Setting <path/to/submodule> is optional

Cloning a Repo with Submodules

If you’re cloning a repo for the first time and it contains submodules:

git clone --recurse-submodules <repo_url>

⚠️ If you forgot --recurse-submodules during clone:

git submodule update --init --recursive

Updating Submodules

Submodules don’t update automatically when you pull. To fetch the latest changes from submodules:

git submodule update --recursive --remote

This updates each submodule to the commit specified in the main repo.

Git Cheatsheet

Command	Description

Command	Description
`git clone <url>`	Copy repo to your machine
`git pull`	Fetch + merge updates from remote
`git add <file>`	Stage file for commit
`git commit -m "msg"`	Save staged changes
`git push`	Upload commits to GitHub
`git branch`	List local branches
`git checkout <branch>`	Switch branches
`git checkout -b <branch>`	Create + switch branch
`git merge <branch>`	Merge branch into current
`git status`	Show branch + file status
`git log --oneline`	View commit history
`git stash`	Temporarily save changes
`git stash pop`	Restore stashed changes

Additional Resources

✅ Now you’re ready to clone, branch, commit, push, and merge with LHRS repositories. Use git status often, and don’t forget to pull before starting new work