Git Essentials on fffelipe's world wide web

Repository

Mon, 01 Jan 0001 00:00:00 +0000

git init # new project here
git clone <url> # copy a remote repo from GitHub

Run init for a fresh project, clone to start working on something that already lives on GitHub.

The Three States

Mon, 01 Jan 0001 00:00:00 +0000

edit → git add → git commit

This is the mental model for everything else. Staging lets you commit a curated subset of your changes.

Working tree

Mon, 01 Jan 0001 00:00:00 +0000

It is your visible project folder: source files, notes, images, configs, and anything else not hidden inside Git internals.

Example: after editing index.html, that file is changed in the working tree, but Git has not stored that change in history yet.

Staging area

Mon, 01 Jan 0001 00:00:00 +0000

Use git add <file> to stage changes. Only staged changes are included when you run git commit.

Real-world example: you fixed a typo and also started a big refactor. Stage only the typo fix so you can commit it separately and keep history clean.

Commit

Mon, 01 Jan 0001 00:00:00 +0000

git add src/auth.js
git commit -m "Validate email on signup"

Keep commits small and focused on one logical change. Good messages explain why, not what.

git status

Mon, 01 Jan 0001 00:00:00 +0000

git status

Your most-used command. Run it constantly to stay oriented.

git log

Mon, 01 Jan 0001 00:00:00 +0000

git log --oneline --graph --decorate

Find when a bug was introduced or understand how a file evolved. The flags above give a compact, readable view.

git diff

Mon, 01 Jan 0001 00:00:00 +0000

git diff # unstaged changes
git diff --staged # what would commit
git diff main..feature # between branches

Always review the diff before committing: it catches stray console.logs and accidental edits.

Branch

Mon, 01 Jan 0001 00:00:00 +0000

git switch -c feature-auth # create + switch
git switch main # back to main
git branch -d feature-auth # delete

One branch per feature or fix. Keep main always deployable: it should reflect what is in production.

Merge

Mon, 01 Jan 0001 00:00:00 +0000

git switch main
git merge feature-auth

On GitHub, merging usually happens through the PR “Merge” button rather than locally: that way CI and review approval are enforced.

Merge Conflict

Mon, 01 Jan 0001 00:00:00 +0000

# open files with <<<<<<< markers
# edit to keep what you want
git add <file>
git commit

Most editors highlight conflicts and offer “accept current/incoming/both” buttons. Test before committing the resolution.

git switch

Mon, 01 Jan 0001 00:00:00 +0000

Examples:

git switch main
git switch -c feature/login

Real-world example: switch from main to a feature branch before starting work so your changes are isolated from production-ready code.

Rebase

Mon, 01 Jan 0001 00:00:00 +0000

git switch feature-x
git rebase main

Used to keep your feature branch up-to-date with main. Don’t rebase branches others are working on; it rewrites history.

HEAD

Mon, 01 Jan 0001 00:00:00 +0000

Most of the time, HEAD points to the current branch, and the branch points to the latest commit on that branch.

Real-world example: if you are on main, new commits move main forward, and HEAD follows along because it points at main.

Remote

Mon, 01 Jan 0001 00:00:00 +0000

git remote -v # list remotes
git remote add origin <url>

origin is the conventional name for your primary remote. Most projects only need one; forks add a second called upstream.

Push

Mon, 01 Jan 0001 00:00:00 +0000

git push # if upstream is set
git push -u origin feature-x # first push of a new branch

-u sets the upstream so future push/pull work without arguments. After this, your branch shows up on GitHub.

Pull

Mon, 01 Jan 0001 00:00:00 +0000

git pull
git pull --rebase # avoids extra merge commits

Run before starting work each day. --rebase keeps history cleaner on shared branches.

Fetch

Mon, 01 Jan 0001 00:00:00 +0000

git fetch origin
git log origin/main # see what you'd be merging

Use when you want to inspect remote changes before deciding to merge or rebase.

Pull Request

Mon, 01 Jan 0001 00:00:00 +0000

# After pushing your branch:
gh pr create --fill # uses last commit as title/body
gh pr view --web # open in browser
gh pr list
gh pr checkout 142 # review someone else's PR locally

PRs are where code review and CI run. Most teams use squash-merge to keep main’s history one commit per PR.

.gitignore

Mon, 01 Jan 0001 00:00:00 +0000

# .gitignore
node_modules/
.env
*.log
.DS_Store
dist/

Add on day one. Never commit secrets, dependencies, or build output. GitHub provides language-specific templates when you create a repo.

git stash

Mon, 01 Jan 0001 00:00:00 +0000

git stash -u # save WIP, including new files
git switch hotfix
# ...do urgent work...
git switch feature-x
git stash pop # restore WIP

Perfect for the “I need to fix prod right now” moment. The -u flag matters: without it, untracked files won’t be saved.

Undo Changes

Mon, 01 Jan 0001 00:00:00 +0000

git restore file.js # discard local edits
git restore --staged file.js # unstage
git reset --soft HEAD~1 # undo last commit, keep changes
git reset --hard HEAD~1 # ⚠️ delete last commit + changes

--soft is safe and useful for amending. --hard is destructive: only use it locally, never on pushed commits.

gh CLI

Mon, 01 Jan 0001 00:00:00 +0000

gh auth login # one-time setup
gh repo clone owner/name
gh pr create --fill
gh pr checkout 42
gh issue list --assignee @me
gh run watch # follow CI for current commit

Saves the trip to the browser for most PR and CI tasks. Once authenticated, it also handles SSH/HTTPS credentials transparently.

origin

Mon, 01 Jan 0001 00:00:00 +0000

origin is just a nickname, not a special server. You can rename it or add more remotes.

Real-world example: origin/main means “the last fetched state of the main branch on the remote named origin.”

Daily Push Flow

Mon, 01 Jan 0001 00:00:00 +0000

# 1. Start from a fresh main
git switch main
git pull

# 2. Create a branch for your work
git switch -c feat/email-validation

# 3. Make changes, then commit in logical chunks
git add src/auth.js
git diff --staged # review before committing
git commit -m "Validate email format on signup"

# 4. Push and open a PR
git push -u origin feat/email-validation
gh pr create --fill

Always branch from an up-to-date main. Push early (even on rough work) so teammates can see progress and CI runs sooner. The PR is where review and merging happen, not your local machine.

Sync Branch with Main

Mon, 01 Jan 0001 00:00:00 +0000

# 1. Update your local main
git switch main
git pull

# 2. Replay your feature work on top of latest main
git switch feat/email-validation
git rebase main

# 3. If there are conflicts, edit the files, then:
git add <resolved-files>
git rebase --continue

# 4. Push the rewritten branch
git push --force-with-lease

--force-with-lease is the safe variant of --force: it refuses to overwrite commits you haven’t seen. If you prefer to avoid history rewrites, git merge main into your branch works too, but creates an extra merge commit.

Code Review Iteration

Mon, 01 Jan 0001 00:00:00 +0000

# Option A: separate commits (easier to follow review thread)
git add src/auth.js
git commit -m "Address review: trim whitespace"
git push

# Option B: amend previous commit (cleaner final history)
git add src/auth.js
git commit --amend --no-edit
git push --force-with-lease

Option A is friendlier for reviewers: they can see exactly what changed since their last review. Option B is fine if your team squash-merges anyway, since intermediate commits get collapsed at merge time.

Hotfix While Mid-Feature

Mon, 01 Jan 0001 00:00:00 +0000

# 1. Stash WIP, including any new untracked files
git stash -u

# 2. Branch off latest main
git switch main
git pull
git switch -c hotfix/payment-timeout

# 3. Fix, commit, push, open PR
git commit -am "Increase payment gateway timeout"
git push -u origin hotfix/payment-timeout
gh pr create --fill

# 4. Once merged, resume your feature work
git switch feat/email-validation
git stash pop

Hotfixes branch from main, not from your feature branch, because you don’t want to ship half-done feature code with the fix. The -u on stash is critical: without it, brand-new files vanish when you switch branches.

Fork & Stay in Sync

Mon, 01 Jan 0001 00:00:00 +0000

# 1. Click "Fork" on GitHub, then clone your fork
git clone git@github.com:you/their-project.git
cd their-project

# 2. Add the original repo as 'upstream'
git remote add upstream git@github.com:them/their-project.git
git remote -v

# 3. Periodically pull updates from upstream
git fetch upstream
git switch main
git merge upstream/main
git push # update your fork

# 4. Make changes on a branch, push to your fork, open PR upstream
git switch -c fix/typo-in-readme
# ...edit, commit, push...
gh pr create --fill

Two remotes: origin is your fork, upstream is the original repo. PRs go from a branch on your fork to upstream’s main. Keep your fork’s main in sync with upstream so new branches start from the latest code.

Undo a Pushed Commit

Mon, 01 Jan 0001 00:00:00 +0000

# 1. Find the bad commit
git log --oneline

# 2. Create a new commit that undoes it
git revert <commit-hash>

# 3. Push the revert
git push

revert is safe on shared branches: it adds a new commit instead of erasing the old one. Avoid git reset --hard + --force on any branch others may have pulled; you’ll cause confusion and lost work.

Revert

Mon, 01 Jan 0001 00:00:00 +0000

Revert is safe for shared branches because it does not rewrite history. It adds another commit saying “undo that change.”

Real-world example: if a commit on main broke production, revert it so everyone sees the fix as a normal new commit.

Git Essentials on fffelipe's world wide web

Repository

The Three States

Working tree

Staging area

Commit

git status

git log

git diff

Branch

Merge

Merge Conflict

git switch

Rebase

HEAD

Remote

Push

Pull

Fetch

Pull Request

.gitignore

git stash

Undo Changes

Tags

gh CLI

origin

Daily Push Flow

Sync Branch with Main

Code Review Iteration

Hotfix While Mid-Feature

Fork & Stay in Sync

Undo a Pushed Commit

Revert