Git Guide

EHW Git Guide

This is the git guide for the embedded hardware subteam of MRover.

Overview

This wiki is located in the mrover/mrover-electrical repository on github which serves as the central location for storing all of our board schematics, designs, and component libraries. Each branch corresponds to a separate board, driver, or test software and each brach name should be preprended with 'board/', 'driver/' or 'test/' respectively. We are not overly strict with formatting for commit messages / contributions, just use common sense.

Setup

Download git and add an SSH Key and GPG Signing Key (recommended) to github.

Usage -- Boards

If you've used git before, you are likely familiar with the traditional fork, merge, approve pull-request methodology of contributing to projects. This is not the process we follow. Due to difficulties working with altium save files, we instead recommend keeping two instances of this repository on disc. One which tracks the board-specific branch (ie. board/bdcmc) and another which tracks your personal branch off of the board-specific branch. This personal branch should have your uniqname appended to the end (ie. board/bdcmc/mcprisk).

Make all changes to your personal branch and after completing changes, pull the latest changes to the main board specific branch. Then, open both projects in altium and copy your additions into the main board branch. This is an unfortunately painstaking process; however, it is necessary when multiple people are working on the same project simultaneously. This process can be bypassed and all changes make directly to the main board branch if you are the sole contributor to the board.

# All commands to be run from a git bash shell 
# (or equivalent actions taken with your preferred method)

### First, create all required directories
cd <desired-directory> # ie. ~/Documents/MRover
mkdir <board-specific-repo-name> # ie. board_bdcmc
mkdir <personal-repo-name> # ie. board_bdcmc_mcprisk

### Then initialize the git repositories
cd <board-specific-repo-name>
git clone [email protected]:umrover/mrover-electrical.git
git checkout <board-specific-repo-name> # ie. board/bdcmc
cd ..

cd <personal-repo-name>
git clone [email protected]:umrover/mrover-electrical.git
git checkout <board-specific-repo-name> # ie. board/bdcmc
git branch <personal-repo-name> # ie. board/bdcmc/mcprisk

### After making and syncing changes, push them to github
cd <desired-directory>/<board-specific-repo-name>
# check for new changes
# if new changes exist, you will have to re-merge all of
# your changes into the main branch again by opening both
# altium projects simultaneously. (if your change was more
# intensive, consider creating a copy of the board-specific
# repository with your changes, overwriting your changes with
# a 'git restore .', copying your altium files back into the
# repo folder, then pulling the current repo into another
# directory and manually copying the required changes from
# that into the board-specific-repo with your changes.
# (yeah it kinda sucks, if you have a better method, please 
# update this guide!)
git pull board-specific-repo-name
git add <all-files-to-track> # typically just use git add .
git commit # optional -S option for signing commits (recommended)
           # optional -m "<text>" option for short commit messages
           # (otherwise it will open in the text editor of your
           # choice, defaulting to vim)
git push # and specify to track a specific branch if needed via 
         # 'git push --set-upstream origin <branch-name>'

Usage -- Drivers and Test Software

Since these softwares are not overly intensive, we do not maintain a strict contribution guideline. The ideal method would be to submit a pull-request from a forked repository or personal branch (ie. driver/*/uniqname), but if that seems overkill for the project in question, it probably is - just make a new commit with a detailed commit message for any changes directly to the main test/driver-specific branch. As always, be sure to check for and merge any commits in the target branch before pushing.

cd <desired-directory> # ie. ~/Documents/MRover
mkdir <specific-repo-name> # ie. driver/tja1042
git clone [email protected]:umrover/mrover-electrical.git
git checkout <specific-repo-name> 
# make changes
git pull # And correct any merge conflicts
git add .
git commit # optional -S option for signing commits (recommended)
           # optional -m "<text>" option for short commit messages
git push # and specify to track a specific branch if needed via 
         # 'git push --set-upstream origin <branch-name>'

Notes

• Make sure you are using an appropriate .gitignore file to ignore unneccessary files!
• Consider using a graphical git interface like lazygit.