Skip to content

git setup

Jump to bottom
Martin Shetty edited this page Sep 4, 2023 · 6 revisions

Overview

In order to contribute to the technical side of this project, you will need to track and save all progress using git. This page explains how to set up and configure git on your machine.

You should definitely read the below, but we do have a couple of videos that walk you through how to use git for mechanical and electrical engineering tasks that may be helpful:

Important concepts to differentiate:

  • git is a version control system. It is a protocol and set of software tools for tracking and merging changes among many collaborators. It is a general tool used by many projects.
  • git repository is a specific project, containing multiple files/folders/directories of tracked content, different versions thereof. The repository can be hosted on a server and all contributors can have copies ("clones") of it on their individual machines. RespiraWorks/Ventilator is a repository. In short parlance a repository is often referred to as "repo".
  • GitHub is a web service that hosts many repositories. It happens to be free, and it provides a number of services on top of acting as a server for our repository. It provides a system of tickets/issues to track our tasks, and it displays the contents of our repository in a fairly reader-friendly way in your web browser. It also hosts this wiki you are reading. These are all functionalities on top of and separate from git as the version control system.

The process looks like this Windows Users:

  • Configure useful options in Windows.
  • Install Notepad++ or another preferred text editor.
  • Download and install Git for Windows (not Git Desktop!).
  • Configure your name and email in git.
  • Get a GitHub account and ask an admin to add you to the org, details on the home page of the wiki.
  • Generate SSH keys.
  • Associate your new SSH key to your account on GitHub.
  • Edit your .bashrc script so you don't have to authenticate incessantly.
  • Clone the repository

The process looks like this for Unix (Linux/Mac) Users:

  • Configure your name and email in git.
  • Install git-lfs
  • Get a GitHub account and ask an admin to add you to the org, details on the home page of the wiki.
  • Generate SSH keys.
  • Associate your new SSH key to your account on GitHub.
  • Edit your .bashrc script so you don't have to authenticate incessantly.
  • Clone the repository

Recommended actions for Windows users before installing git

  • In Windows, open any explorer window and go to View > Options > Change folder and search options
    • In the View tab, under Advanced settings, uncheck the box for Hide extensions for known file types
    • Click OK to close the window.
    • This will allow you to see and edit the extensions on filenames.
  • Install a text editor so that you can select it during the git installer wizard.
    • If you don't have a personally-preferred text editor, we recommend Notepad++.
    • Otherwise the default in vim, and if you know what vim is, you probably prefer something else :).

Installing git locally

In order to work with the repository, you will need to install the git tool on your machine. How you do this will depend on the type of operating system you are using.

Operating system Installation method
Linux sudo apt install git git-lfs or something like that
macOS brew install git git-lfs or something like that
Windows Download and install Git for Windows. DO NOT install the "GitHub Desktop" app.
  • (Windows users) Install with the all default settings, except for the default editor, which should be set to Notepadd++, or your preferred editor.

Upon installing these, you should have access to the git command in your command line terminal. In case of Windows, this will be via the included git bash terminal utility.

Git Bash Tips:

  • (Windows only) you can access git bash from within any directory by right-clicking in the file browser
  • use TAB to autocomplete a command, at least up to any point of ambiguity
  • use up arrow key to bring up previously used commands
  • you can copy-paste commands into the terminal from the various wikis and guides you may read, but be careful to not include the end-of-line return character which might cause it to run the command before you get a chance to modify it as per your needs
  • also, be careful you only copy-paste stuff you understand, lest you risk your cybersecurity...

Configure your name and email address in git

  • This is required to make commits
  • You can use any name and email you want
  • Configure this by running the following commands in bash, replacing [email protected] and Your Name with your own.
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Unix Users: Install Git-lfs

  • Note that on non-Windows systems you need to explicitly install git-lfs. You can read more about the why and what to do if you forgot here.
  • Once git-lfs is installed, users should run:
git lfs install

Default editor in Windows (if you didn't select it during the git install process)

Git for Windows will by default use vim as default text editor. If you ever do a rebase or end up having to resolve merge conflicts, it will make you use it. A lot of human beings don't feel that vim is made for them. Unless you already know what vim is, it is highly advised you change your default editor to something like Notepad++.

In git bash terminal, run the following command:

git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"

where you can substitute the notepad++ executable with a path to whatever your editor of choice may be.

GitHub configuration

You should do the following:

  • Create a GitHub account
  • Share your GitHub username with someone on the team to be added to our organization
  • Configure ssh authentication for GitHub

Setting up SSH keys

To securely submit changes to the GitHub server, you need to configure ssh authentication keys.

GitHub provides adequate instructions on how to do this. Make sure you follow the entire manual including "Testing your ssh connection" to make sure your setup was successful.

Windows Users: bash script to prevent ssh credentials fatigue

If you are authenticating using ssh in Windows, you may find that git bash asks for your password multiple times on every occasion you pick your nose. This is understandably annoying. If your ssh credentials do not unlock nuclear launch codes and/or you are otherwise not overly paranoid, you can make it so that you only authenticate once every time you open the git bash terminal. The solution is a script you can add to your .bashrc file, provided about two posts down in this forum thread.

In case the forums look scary, here is a summary.

If you do not have a .bashrc file in your home directory, you need to create it. You can do this by running the following commands in git bash:

cd
touch .bashrc

Now you should find the file in your home directory. Open it with a text editor. Now paste this script into it:

env=~/.ssh/agent.env

agent_load_env () { test -f "$env" && . "$env" >| /dev/null ; }

agent_start () {
    (umask 077; ssh-agent >| "$env")
    . "$env" >| /dev/null ; }

agent_load_env

# agent_run_state: 0=agent running w/ key; 1=agent w/o key; 2= agent not running
agent_run_state=$(ssh-add -l >| /dev/null 2>&1; echo $?)

if [ ! "$SSH_AUTH_SOCK" ] || [ $agent_run_state = 2 ]; then
    agent_start
    ssh-add
elif [ "$SSH_AUTH_SOCK" ] && [ $agent_run_state = 1 ]; then
    ssh-add
fi

unset env

Save the file and restart your git bash terminal.

Cloning the repository

  • You are now ready to clone the repository (make a local copy on your computer that you can work on)
  • Before you do any work on the repository, remind yourself of our Contributor Workflow.
    • We do not allow committing directly to master.
    • All work must be done on a branch and should implement only one feature or fix.
    • Branches must be approved on a Pull Request before being merged into master.
  • Did you install git-lfs? If not, go back and do that first.
  • Clone the repository by running the following command in bash:
git clone [email protected]:RespiraWorks/Ventilator.git

What's next?

If you are new to git, you might find it useful to read the git cheat sheet.

Otherwise, go back to the main wiki page and continue reading any other relevant guides.

Clone this wiki locally