Working on Git and GitHub

Prerequisites:

1. You need to know what git and GitHub are. You don’t need to know how to use them (that’s what this is about), but you do need to know what they are.

2. You need to know how to run commands from the command line on your laptop, and you need to know basic commands like cd ~.

In this document, stuff surrounded by “<” and “>” are things you need to supply, without the “<” and “>”. Don’t type them in. It won’t work. In general, you should copy the commands below, paste them in, edit them to supply your stuff, then press enter to run them. Don’t copy the whole set. Just do one line at a time.

Initial Setup

1. Sign up on GitHub.

2. Make sure your laptop has git on it.

Per-repository Setup

The Drop Bears has several repositories on GitHub, each for a functional area of the software. Each repository is independent of the others. To work on any one of them, you need to set up a local “clone” of the repository. There are many ways to do this. The following is the way we want you to do it when working on The Drop Bears software.

1. Grab a local copy of the repo:

cd ~/code  # (or wherever you want to put your Drop Bears code)

git clone git@github.com:thedropbears/<repo>.git

You can get the above URL from the GitHub UI, by pressing the <> Code button.

Day to Day Git Recipes

What is the current state of my working copy? / I forgot what I need to do next.

git status

Starting on a new feature

First make sure that you are in the repo: 

cd <path/to/repo>

Next make sure you are on the default branch:

git switch main

Update this branch to reflect the latest version on GitHub:

git pull --ff-only

Think of a name for a new branch where you will do your work, and create a branch for your feature:

git switch -c <feature>

As an example:

git switch -c shooter-target-tracking

You are now ready to start work, editing files and adding new ones.

Pushing Your Work to GitHub

When you think you have something ready, test it thoroughly. How you test depends on the code.

Once all tests pass, you have to “stage” your work, then commit it:

git add -A

This stages all modified and new files to be committed by the next commit. You can’t do a commit unless all modified or new files are staged. If there are new files you don’t want to commit, get rid of them or your commit will fail.

Alternatively you can be explicit about which files you want to commit:

git add <files...>

Once you are ready to commit your changes (saving your work to git):

git commit

This will pop up an editor window for you to type in a description of the commit. The first line will be used in logs so make it clear what this commit is about. A quicker way to add just a short line is to use the following command instead (you do need the quotes):

git commit -m "<your one-line summary here>"

Please ensure your commit message summary (the first line) is short (preferably less than 50 characters) and descriptive (please don't be xkcd 1296: Git Commit). Most editors will help you with this. For more information about how a commit message is formatted: https://commit.style

Your work is now committed, but still only on your machine.

Next make sure that upstream hasn’t changed out from under you. This is very important; don’t skip it!

git pull origin main --rebase

This might result in conflicts if you have edited a file that someone else has changed on the main branch since you started. If so, see Resolving Conflicts below. Otherwise, your branch may have been updated with other changes from main. In either case, make sure to test your code!

You are finally ready to push your changes up to GitHub:

git push origin <feature>

This pushes your changes to GitHub, in a new branch using the name from earlier. It also prints out a URL on GitHub. Go there and create a “pull request” (PR), asking for review from a mentor or lead. Make sure to give a more complete description here of the entire change. The reviewers will receive an email asking for a review. The system will also fire off a “Continuous Integration” (CI) build. That runs all the available tests with your patch on top of the current main branch.

The system won’t let you “merge” your changes into main branch until the CI has passed all tests and at least one reviewer has approved.

But realistically your reviewer(s) will request that you make some changes. You can discuss these back and forth on GitHub, but usually the right thing to do is to do what the reviewer asks. So you make those changes in your code on your machine, and test them. So now you have to go through the cycle again, but a little differently because this is still the same pull request.

You stage and commit locally just like before:

git add <...>

git commit or git commit -m "<your one-line summary here>"

git pull origin main

(Someone may have gotten other changes in while you were waiting for the review. Again, resolve any conflicts following Resolving Conflicts below.)

Now you are going to push, but this time right into the same branch you made when you pushed the first time:

git push --force-with-lease

This will restart the CI tests.

Once your code has been approved and the tests all pass, push the big green “Squash and Merge” button on GitHub, and your code will become part of the main branch.

Resolving Conflicts

When developing software as a team, people sometimes edit the same bits of the same file at the same time. Whoever lands their change in first will cause a conflict for the other person when they try to push their change.

You may encounter this when you do a git pull. When that happens, the system first tries to resolve the conflicts automatically, which it can do if the changes are on completely different parts of the file, or the command will fail with some instructions telling you to resolve the conflicts yourself, then resume the rebase. Always read the output carefully to see what’s happened and which files need to be fixed, if any.

When files do need to be fixed, you can either edit them in your usual editor or use a merge tool such as meld. The following assumes you are doing it in your editor.

In the file you will find the conflicting areas looking something like this:

<<<<<<< Updated upstream
alphabet = "air bat cap drum each fin gust harp sit jake crunch look made near odd peck \
||||||| constructed merge base
alphabet = "air bat cap drum each fin gust harp sit jail crunch look made near odd peck \
=======
alphabet = "air bat cap drum each fin gust harp sit jury crunch look made near odd pit \
>>>>>>> Stashed changes

You need to figure out how your change interacts with the other person’s change and decide what these lines should look like in the final version. Edit so that it looks that way and remove all the lines with lots of ======. Then run the tests. Once the tests pass, tell git that you’ve resolved the conflicts:

git add <files...>

Then, depending on whether you’re rebasing or not:

git commit

git rebase --continue

The right command to use will be in the instructions you get for resolving the merge conflict.
It will also be shown in git status.

That’s it. You have now synchronised your work on top of the current state of the main branch.

I screwed up; what do I do?

https://ohshitgit.com is an excellent cheatsheet in a pickle.

If all else fails, see xkcd 1597: Git.