spacehardwarehandbook-public

Introduction

I get it. You’re smart. You’re a successful scientist. You’re a brilliant engineer. You’re saving the world. But this git thing, it’s a WTFBBQ!?!?

Git was written by Linus Torvalds. Yeah, the Linux guy. But more than a Linux guy, Linus is a file systems guy. And file systems guys think a bit different from the rest of us. And that makes git a little trickier.

Quick note for SVN Users

If you’ve used the subversion revision control system (svn) before, it shares many of its commands with git. But all of those commands mean new things in git. So your old knowledge will be of no use to you.

What’s a Revision Control System

A Revision Control System (RCS) tracks all changes to a single folder through time… and across multiple users who all occupy different space. git is the latest (greatest?) RCS that does these things.

I’m not here to defend git. You’re obviously here because someone is making you use it. ;-)

I will note, however, that once most users climb the learning curve, they like it better than the alternatives.

Some terminology

Repository - A repository is a folder. The initial copy lives on a server somewhere in the cloud. (GitLab, GitHub, Bitbucket, etc., they’re all servers. Some are free.)

Fork: A copy of a repository in your account on the server.

Clone - A clone is your copy of the repository folder. It lives on your computer or some account you have access to.

Branch - A version of your copy of your folder. With git you can create as many branches as you like. Have a ball. Each one gets a unique name that represents the stuff you’re changing. Just making sure you get this. A version of a folder is called a branch. Seriously. Please re-read.

Checkout - The operation of choosing the current branch (version) of your local repository clone (folder).

Only one Branch at a time - So you’ve cloned the repository (folder) to your local computer. And that repository (folder) has lots of branches (versions). Only one branch (version) can be active inside that folder at a time. You need to re-read this item.

MAGIC: Remember we said Linus Torvalds was a file systems guy? This is why. Say the branch (version) named “banana” contains a new file named “sundae.txt”. If you switch branches (versions) away from “banana” “sundae.txt” will disappear. It will reappear when you switch back to “banana”. Crazy, right?

Prerequisites

Question 1: “Do I even have git installed on my computer?”

Pop into a unix/linux terminal and type which git. If it spits out a path, you’re good. If not, you’ll need to install it. If you’re on Windows, reach out for help.

This tutorial will cover the basics of command-line git. You may want to investigate any number of the free git clients out there. The rules are the same though. You’ll still need to understand git to use them.

See GitHub Desktop Client or Git Tower Client.

Question 2: Security.

You’ll need a private and a public key set up. The private key will remain on your computer and the public key will go into your github account here. You’ll literally paste it in there. See the pictures below.

If you don’t have an SSH Key, see these instructions.

Don’t ignore setting up your ssh key. If you don’t do this, you will have a bad time. Who wants that?

GitHub

GitHub is a bit different from other git repositories. When you fork (copy) the repository, you get a copy of the repository in your GitHub account. Weird right? The copy is what you’ll pull down to your computer.

Step 1, Getting your copy of the repository to your computer

In your browser, go to the space coronograph design documents repository.
Push the “Fork” button menu. It’s named “Fork”. It’s got a little dealey on it like this:

Go to your account and check out your own private copy of the repository. This is the account you’ll party on with your edits.

Step 2, Editing

For starters, you can’t really edit well right on the GitHub web site. So we need to clone (download) your copy of the repository (in your account) to your computer.
Open your terminal program and go to some folder where you want your clone to go. Your home directory is a good choice.
Finally we get to clone. Click these buttons to copy the SSH URL to your clipboard:

In to terminal type `git clone .
You’re done.

Step 3, Partying on the repository

You’ve got a folder. Have fun. But…
If you’re a beginner:
- Don’t rename folders
- Don’t move files
- Don’t move folders.
You’re done.

Step 4, Sending your changes back to GitHub.

All this time git was tracking all of your changes behind your back. Crazy, right? Now we have to tell git which changes you want to keep. So:

In terminal `cd .
Utter git status. This will reveal a list of files that have been created or changed. For each change you have one of two choices. And this is a hard wall. All files must be considered to continue.

Revert the file.

git checkout filename where filename is the name as it appeared in the list above.
Accept the changes.

git add filename where filename is the name as it appeared in the list above.

THe next step is to commit your change: git commit -m "I like ice cream sundaes."
Utter git push.
You’re done locally!

Step 5, Asking Ewan to merge your changes back

Go to the original space coronograph design documents repository web page.
Create a new pull request.

Note: “Why pull request?” You’re basically making a request to Ewan to pull, inspect, and accept your changes. It’s ridiculous, I know.

Setup your pull request

Create it.
You’re done!