Git basics

Everything you need for your first contribution, and nothing you do not. You can follow this on any operating system.

Tell Git who you are

Do this once, ever. Git stamps your name on every commit you make.

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

Use the same email as your GitHub account, or your commits will not be linked to your profile.

1. Fork the project

On the project's GitHub page, click Fork in the top right. You now have your own copy at github.com/YOUR-USERNAME/project-name.

You can do anything you like to your fork. The original is untouched.

2. Clone your fork

Cloning downloads your fork onto your computer.

git clone https://github.com/YOUR-USERNAME/project-name.git
cd project-name

Add the original as "upstream"

This lets you pull in changes other people have made since you forked.

git remote add upstream https://github.com/ORIGINAL-OWNER/project-name.git
git remote -v

You should see origin (your fork) and upstream (the original).

3. Make a branch

Never work directly on main. A branch keeps your change separate and makes it easy to work on more than one thing.

git checkout -b feat/add-my-name

Naming your branch

4. Make your change

Edit the file in whatever editor you like. Then see what Git noticed:

git status
git diff

git status lists which files changed. git diff shows exactly what changed inside them.

5. Commit

A commit is a saved snapshot with a message explaining why.

git add contributors/your-username.json
git commit -m "feat: add your-username to the contributor wall"

Writing a good commit message

fix: footer link pointed at the wrong page

The footer link pointed at a page that no longer exists.
Updated it to the current one.

Closes #42

Format: type: what changed, lowercase, present tense. Types are feat, fix, docs, test, ci, chore.

6. Push

git push origin feat/add-my-name

Your branch is now on GitHub, in your fork.

7. Open the pull request

Go to your fork on GitHub. There will be a "Compare & pull request" button. Click it, fill in the template, and make sure your description contains Closes #<issue-number>.

Then wait. A maintainer replies within 48 hours.

Keeping your fork up to date

Before starting anything new, pull in what has changed:

git checkout main
git pull upstream main
git push origin main

When something goes wrong

I committed to main by mistake

git branch feat/my-work
git reset --hard upstream/main
git checkout feat/my-work

Your work is safe on the new branch.

I need to undo my last commit but keep the changes

git reset --soft HEAD~1

I want to throw away my changes to a file

git restore path/to/file

This cannot be undone. Be sure.

Git says I have a merge conflict

Two people changed the same lines. Git marks the spot in the file:

<<<<<<< HEAD
your version
=======
their version
>>>>>>> upstream/main

Edit the file so it reads how it should, delete all three marker lines, then:

git add the-file
git commit

I am completely lost

Two commands that tell you where you are:

git status
git log --oneline -10

And if you would rather have a person: come to a PR Debug Clinic, Monday 12 or Wednesday 21 October. Station A is entirely for Git problems and everyone there has had the same one.