GitHub cheat sheet

Terms, browser paths, and commands for beginners

The GitHub terms that the workshop uses, where to find each one in the browser, and the matching git and gh commands.
TipTwo routes: browser and command line

Each exercise has a browser route and a command-line route. Both routes reach the same result, and you can change the route at any step. The browser route needs no software. The command-line route needs git and gh: see Prepare the command line.

Version control: why and how

Why use version control

A thesis grows over months. The text, the data, and the code change many times, and later you must explain what changed and why. File names such as thesis_final_v3_new.docx do not answer that question.

Version control records each change as a commit: a saved state of the files, with the author, the date, and a message that explains the change. The list of all commits is the history. With the history, you can:

  • compare two states of a file and see each changed line;
  • go back to an earlier state when a change was wrong;
  • show your supervisor or a later reuser how the text and the data came about;
  • cite one exact state of the work, for example the state that you submitted;
  • work on a branch and keep the agreed version on main unchanged until a review.

A copy of the repository on GitHub is also a backup. It is not long-term preservation: see What GitHub cannot guarantee.

Git and GitHub

Git is the version-control program. It keeps the history in a hidden folder .git inside the project folder. Every copy of a repository holds the full history, so git works on your computer without the internet.

GitHub is a service that hosts git repositories. It adds the tools that this course uses for planning and review: Issues, pull requests, Projects, releases, and Actions.

When you edit a file in the browser, GitHub runs git for you. One click on Commit changes does what three commands do on the command line: git add, git commit, and git push.

How a change travels

On the command line, a change passes through four places. You decide when it moves to the next place.

flowchart LR
    W["<b>Working folder</b><br/>the files you edit"] -- "git add" --> S["<b>Staging area</b><br/>the changes for the next commit"]
    S -- "git commit" --> L["<b>Local repository</b><br/>the history on your computer"]
    L -- "git push" --> G["<b>GitHub</b><br/>the shared copy"]
    G -- "git pull" --> W

The staging area lets you put related changes into one commit and leave other changes for later. A pull request then moves the commits of your branch into main on GitHub.

One complete change on the command line looks like this. The text after # explains each line.

gh repo clone OWNER/projm-thesis      # once: copy the repository to your computer
cd projm-thesis                       # go into the project folder
git pull                              # get the latest state from GitHub
git switch -c docs/scope              # start a branch
                                      # now edit README.md in a text editor
git status                            # list the changed files
git diff                              # show each changed line
git add README.md                     # put the change into the staging area
git commit -m "docs: add the scope"   # save a commit with a message
git push -u origin docs/scope         # send the branch to GitHub
gh pr create --fill                   # propose the change as a pull request

Setup explains how to install git and gh. The task tables below give the browser action for each command.

Good habits

  • Put one logical change into one commit. A small commit is easy to review and to undo.
  • Write a message that says what changed and why. This course uses prefixes such as docs: and fix: from Conventional Commits.
  • Pull before you start. Push when you stop.
  • Never commit passwords, access tokens, or personal data. The history keeps a file even after you delete it.
  • List the files that git must ignore, such as exports and temporary files, in .gitignore.
  • Keep large binary files, such as scans or videos, out of the repository. GitHub blocks files larger than 100 MiB. Deposit large files in a data repository and link them.

Learn more: About version control and What is Git? (Pro Git) · About Git · Ignoring files · About large files on GitHub

GitHub in one picture

GitHub keeps two things together: the files of a project and the plan for the work. A repository holds the files and their history. Issues and a Project hold the plan. A pull request connects the two: it changes the files, and it closes the Issue that asked for the change.

flowchart TB
    T["<b>Template</b><br/>a starting point"] -- "Use this template" --> M
    subgraph REPO ["Your repository"]
        M["<b>main</b> branch<br/>the agreed version"]
        B["<b>your branch</b><br/>work in progress"]
        M -- "create a branch" --> B
        B -- "pull request → review → merge" --> M
        M -- "tag v0.1.0" --> R["<b>Release</b><br/>a named version"]
    end
    I["<b>Issue</b><br/>what to do, and is it done?"]
    P["<b>Project</b><br/>backlog, board, roadmap"]
    B -. "Closes #12" .-> I
    P -- "shows" --> I
    style REPO fill:#f2f1ee,stroke:#8f8d88,color:#0b0b0b

Terms

Files and history

Term What it is Where in the browser
Repository The home of one project on GitHub. It holds the files, their full history, the Issues, and the pull requests. github.com/OWNER/NAME
README The file README.md. GitHub shows it on the start page of the repository. It tells a visitor what the repository is. Start page, below the file list
Markdown A simple text format, for example **bold**, # Heading, or - [ ] task. README files, Issues, and pull requests use it. Every text box on GitHub; click Preview
Commit A saved change to one or more files, with a message, an author, and a date. The history of a repository is a list of commits. Commit changes… after you edit a file; History on a file
Branch A separate line of work. You change files on a branch without changing main. Branch menu above the file list (it shows main)
Default branch The branch that holds the agreed version, usually main. Visitors see it first. Branch menu
Clone A copy of a repository on your own computer, made with git. The command-line route starts with it; the browser route does not need it. Code button → Local

Learn more: About repositories · About READMEs · About branches

Working together

Term What it is Where in the browser
Pull request A proposal to bring the commits of one branch into another branch, usually main. Others can comment and review before the merge. Short form: PR. Pull requests tab
Review A human check of a pull request. The reviewer comments, approves, or requests changes. Pull request → Files changed → Submit review
Merge The step that adds the commits of a pull request to the target branch. Pull request → Merge pull request
Collaborator A person with write access to your repository. Access to a Project is a separate setting. Settings → Collaborators
Template A repository that others use as a starting point. The new repository gets the files, but not the history. It has no connection to the template. Use this template button
Fork Your own copy of another person’s repository. It stays connected to the original, so you can propose changes back with a pull request. Fork button, top right of a repository

Template or fork? Use a template to start your own project, as in X1. Use a fork to contribute to another person’s project, for example to correct this course.

Learn more: About pull requests · About forks · Creating a repository from a template

Planning

Term What it is Where in the browser
Issue One piece of work or one question, with a title, a description, and a discussion. You close it when it is done. Issues tab
Sub-issue An Issue that is part of a larger Issue, its parent. Parent Issue → Create sub-issue
Epic A large Issue that groups the sub-issues for one substantial outcome. GitHub has no epic type; this course uses the label kind:epic. Issues tab, filter label:kind:epic
Label A coloured tag on Issues and pull requests, for example kind:task. You can filter by label. Issues → Labels
Milestone A group of Issues with one due date, for example “Registration submitted”. Issues → Milestones
Dependency A “blocked by” relation: one Issue waits for another. It is not a parent-child relation. Issue sidebar → Relationships
Project A planning tool that belongs to your account. It shows Issues from one or more repositories as a table, a board, or a roadmap. Its visibility is separate from the repository. Projects tab of the repository
View One saved way to look at a Project: a table, a board, or a roadmap, with its own filters. Tabs at the top of the Project
Field A column in a Project, for example Status, Priority, or Target date. Project table header → +
Project workflow A built-in automation of a Project, for example “when an Issue closes, set the Status to Done”. Project … → Workflows

Learn more: About issues · About Projects · About milestones

Sharing

Term What it is Where in the browser
Visibility Public means that everyone can see it. Private means that only the people you invite can see it. A repository and a Project each have their own setting. Repository: Settings → General → Danger Zone. Project: … → Settings
Tag A name for one commit, for example v0.1.0. Releases or Tags
Release A tagged version with notes and downloadable archives. It is not a long-term archive. Releases, right column of the start page
GitHub Actions workflow A script that GitHub runs on its servers, for example to build a website. It lives in .github/workflows/. It is not the same as a Project workflow. Actions tab
GitHub Pages A website service that publishes files from a repository. Settings → Pages

Learn more: About releases · Setting repository visibility · Understanding GitHub Actions · GitHub glossary

Tasks in the browser, in git, and in gh

git is the version-control program on your computer. gh is the GitHub command-line tool. To install them and sign in, follow Prepare the command line. Replace OWNER, NAME, and the numbers with your own values. Each exercise gives the exact commands in its Command line tab.

Repository and files

Task Browser Command
Create a repository from the template Template page → Use this template → Create a new repository gh repo create my-thesis --template maehr/open-research-data-template --private --clone
Copy a repository to your computer Code → Local gh repo clone OWNER/NAME
See what changed History on a file git status and git log --oneline
Create a branch Branch menu → type a name → Create branch git switch -c docs/scope
Save a change Edit a file → Commit changes… git add README.md then git commit -m "docs: add the scope"
Upload the branch Happens with the commit git push -u origin docs/scope
Get the latest main Not needed git switch main then git pull
Open the repository in the browser — gh browse

Pull requests

Task Browser Command
Open a pull request Compare & pull request gh pr create --fill
Review a pull request Files changed → Submit review gh pr review --approve or gh pr review --comment --body "Checked the criteria"
Merge a pull request Merge pull request → Confirm merge gh pr merge --squash --delete-branch

Issues and Projects

Task Browser Command
Create a label Issues → Labels → New label gh label create kind:task --description "Sub-issue with one output"
Create an Issue Issues → New issue gh issue create --title "E01 Scope the thesis and register it" --label kind:epic
Create a sub-issue Parent Issue → Create sub-issue gh issue create --title "E01-T2 Write the research question and scope" --label kind:task --parent 1
List Issues Issues tab gh issue list --label kind:task
Find the number of an Issue by its ID Issues tab → search for the ID Define the helper issue as in X3. Then issue E01-T3 prints the number, and $(issue E01-T3) puts it into a command
Close an Issue Close issue gh issue close 3 --comment "Done, see #5"
Mark an Issue as blocked Issue sidebar → Relationships → Mark as blocked by gh issue edit 5 --add-blocked-by 3
Create a milestone Issues → Milestones → New milestone gh api repos/{owner}/{repo}/milestones -f title="M1 Registration submitted" -f due_on=2026-12-01T12:00:00Z
Set the milestone of an Issue Issue sidebar → Milestone gh issue edit 3 --milestone "M1 Registration submitted"
Start work on an Issue Issue sidebar → Development → Create a branch gh issue develop 3 --checkout
Copy the showcase Project Project … → Make a copy gh project copy 11 --source-owner maehr --target-owner @me --title "PROJM thesis plan"
Link a Project to a repository Repository Projects tab → Link a project gh project link 12, in the folder of the repository (without --owner @me)
Change the visibility of a Project Project … → Settings → Visibility gh project edit 12 --owner @me --visibility PUBLIC
Add an Issue to a Project Project table → + → # gh issue edit 1 --add-project "PROJM thesis plan"
Open a Project in the browser Projects tab gh project view 12 --owner @me --web
Create a release Create a new release gh release create v0.1.0-demo --title "Demo release" --notes "Synthetic data only"

Markdown for Issues and pull requests

## Heading
**bold** and _italic_
- [ ] an open task
- [x] a completed task
[link text](https://example.org)
@username     mentions a person
#12           links Issue or pull request 12
Closes #12    in a pull request: closes Issue 12 when the pull request merges

Learn more: Basic writing and formatting syntax · Linking a pull request to an issue · Git documentation · GitHub CLI manual

Back to top