Git & GitHub

This chapter is the muscle‑memory playbook: minimal theory, maximal commands.
By the end you can clone, branch, commit, rebase, and open a pull‑request that sails through CI.

1. First‑time config

git config --global user.name  "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase true    # rebase by default
git config --global color.ui auto

user.name and user.email stamp every commit; GitHub shows them in blame views. The defaults above keep your history linear and readable.

2. Cloning a repo

git clone git@github.com:stratorys/project.git
cd project

git clone creates a working directory, a .git folder, and a remote named origin pointing at GitHub.

3. Branching workflow

git checkout -b feat/login‑oauth # create & switch
git checkout main   # switch to an existing branch

Branches are cheap pointers; create one per task, push early, delete when merged. Upstream rules:

• prefix feat/, fix/, chore/, hotfix/
• Keep them rebased on main to avoid diamond graphs.

4. Commit hygiene

Follow Conventional Commits:

feat(auth): add OAuth2 PKCE flow

BODY: rationale, links, screenshots if UI.
BREAKING CHANGE: drops legacy /v1 token endpoint

The spec enables automatic changelogs and semantic version bumps. Aim for focused commits; if your diff is >300 lines, split it.

5. Syncing with main

git checkout main
git pull origin main
git checkout - # `-` is shorthand for previous branch
git rebase main

rebase rewrites your branch atop the latest main so the merge commit stays clean.

6. Remotes & pushing

git remote add origin git@github.com:stratorys/project.git
git push -u origin feat/login‑oauth

-u sets up upstream tracking so future git push / git pull need no extra flags.

7. Opening a pull request

On GitHub: Choose your branch → New pull request → fill template → create.

CLI alternative:

gh pr create --fill
gh pr checkout 123   # review someone else’s PR

gh pr checkout grabs the branch locally for testing. ([GitHub CLI][11])

Quick‑ref commands

git status
git add . # stage all changes
git commit -m "fix: add OAuth2 PKCE flow"
git commit -m "fix: add OAuth2 PKCE flow" --amend # amend last commit
git log --oneline --graph --decorate # view commit history
git diff # view unstaged changes
git diff --cached # view staged changes
git diff HEAD # view all changes since last commit
git reset HEAD~1 # undo last commit (keep changes)
git pull origin main # pull changes from remote
git push origin main # push changes to remote