~/git-visually

Git, visually

Every git command is really a question about where a block of work lives — on your machine, or in the cloud — and whether the two agree. Each situation below gives you the one-line answer first, then the reasoning.

$git add . && git commit -m "message"

"I edited a file and want it saved as a permanent step in history."

stage, then commit

working directory
staged
local history

Edit, then add, then commit — three separate steps, three separate reasons to pause.

Why two steps: add lets you choose exactly which changes go into the next commit — useful when you've edited several files but only want to save some of them.

$git fetch then look, or git pull to grab it now

"I want to see what's changed on the remote, but I'm not ready to bring it into my work yet."

fetch, or pull?

remote (origin)
local (your branch)

Fetch downloads. Pull downloads and merges in one move.

The difference: fetch is read-only — it lets you look before you touch anything. pull is fetch immediately followed by merge. If you want to review incoming changes first, fetch then merge. If you trust the remote, pull.

$git merge origin/main or git rebase origin/main

"Someone pushed two commits to main while I was building a feature locally. My branch and main have diverged."

merge, or rebase?

Diagram comparing git merge and git rebase Shows how a diverged local branch is reconciled with main, either by creating a merge commit or by replaying local commits on top of main.

merge

Ties the two histories together with a new merge commit. Nothing is rewritten.

  • Safe on shared branches
  • Exact history is preserved, parallel work stays visible
  • Adds an extra merge commit to the log

rebase

Replays your commits one by one on top of the new main.

  • Produces a clean, linear history
  • Rewrites your commit hashes — never rebase commits others already pulled
  • Good for tidying a local feature branch before sharing it
$git stash ... later: git stash pop

"I'm mid-edit, but I need to switch branches to fix something urgent, and I'm not ready to commit this half-finished work."

commit it anyway, or stash it?

working directory
stash

Stashing tucks the edit away — your directory looks clean again, safe to switch branches.

Why not just commit it: a commit should be a complete, meaningful step. Stashing keeps unfinished work out of history entirely, in a separate pocket, until you pop it back.

$git reset --hard HEAD~1 or git revert HEAD

"My last commit was a mistake. I want it gone."

reset, or revert?

local history

reset

Moves your branch pointer backward, as if the commit never happened.

  • Rewrites history — risky if already pushed
  • Fine for commits that only exist locally

revert

Adds a new commit that undoes the changes. History stays intact.

  • Safe on shared or already-pushed branches
  • Leaves a clear record that something was undone, and why

Rule of thumb: if the commit is already on a shared remote, revert it. If it's still only on your machine, reset is fine.

$git pull then git push — not --force

"I ran git push and got: ! [rejected] main -> main (non-fast-forward)."

force push, or something else?

what happened

The remote has commits your local branch doesn't have — usually because someone else pushed first. Git refuses to push, because doing so would silently erase their work.

the fix

git pull (or fetch + rebase) to bring the missing commits in first, resolve any conflicts, then push again. This is exactly the merge vs rebase decision from above.

Avoid git push --force unless you're certain no one else's work is on that remote branch — it overwrites remote history with yours, discarding theirs. --force-with-lease is the safer version: it refuses to overwrite if the remote moved since you last checked.

$git merge → edit the file → git add && git commit

"Local and remote both changed the same line of the same file. Git can't guess which one you want."

merging into a conflict

auth.js — local vs remote

Merge two branches that touched the same line, and git stops to ask you which version is right.

Resolving: git leaves <<<<<<< / ======= / >>>>>>> markers right in the file. Edit it down to what it should actually say, remove the markers, then add and commit to finish the merge.

$git cherry-pick <commit-hash>

"There's one useful fix sitting on a branch I don't want to fully merge."

cherry-pick a single commit

other-branch
main (your branch)

B2 has a fix you want, but B1 and B3 you don't. Cherry-pick copies just that one commit.

Note: the copy gets a brand new commit hash on main — it's a duplicate of the change, not a move. B2 still exists on other-branch too.

$git tag v1.0.0

"I want to mark this exact commit as a release, so I can always come back to it by name instead of a hash."

tag a commit

main

Click a commit to tag it. A tag is just a permanent, human-readable pointer — it never moves on its own.

$echo "node_modules/" >> .gitignore

"There are build files and secrets in this folder that should never be tracked or pushed."

stop git from seeing a file

working directory

node_modules/ and .env are untracked — git sees them and will offer to add them. Ignoring hides them from git entirely.

Careful: .gitignore only stops untracked files from being picked up. A file already committed keeps being tracked until you explicitly remove it with git rm --cached.

$git blame auth.js

"This line looks wrong. Who wrote it, and in which commit?"

trace a line back to its commit

auth.js

Every line traces back to the commit that last touched it — even if that commit is months old.

$git checkout <commit-hash> then git switch -c fix-me

"I checked out an old commit directly, not a branch — git is warning me about a detached HEAD."

where did my new commit go?

main

HEAD is pointing straight at C2, not at the main branch. Any new commit here isn't on a branch at all.

The trap: switch back to main without creating a branch first, and that new commit becomes unreachable — git won't delete it right away, but nothing points to it anymore.

$git rebase -i HEAD~3

"I made three messy 'wip' commits while figuring something out. I want one clean commit before sharing this branch."

squash commits together

feature branch

Interactive rebase lets you reorder, edit, or squash past commits before anyone else sees them.

$git bisect start → bisect bad / bisect good

"Something broke, somewhere in the last 8 commits. I don't want to test all 8 by hand."

binary-search the history

history — testing commit

Mark the current commit good or bad. Bisect keeps halving the range until only one commit is left.

Why it's fast: each answer halves the search space. 8 commits take at most 3 checks instead of 8 — the gap widens fast on real histories with hundreds of commits.

$git push origin fix-typo → open a pull request on the web

"I don't have write access to this project, but I want to contribute a fix."

fork, then pull request

Diagram of the fork and pull request workflow Shows an upstream repository, your fork as a cloud copy of it, your local clone, and a pull request flowing from your fork back to upstream. upstream (their repo) main your fork (cloud copy) main fork your local clone fix-typo clone push pull request — asking upstream to merge it

The shape of it: you never push directly to upstream. Fork it (your own cloud copy), clone your fork locally, commit and push to your fork, then open a pull request asking the project's owners to pull your commits into their main.

$git submodule add <url> libs/shared

"This project needs to include another entire git repository inside it — not copy its files, but reference its exact version."

a repo inside a repo

Diagram of a submodule as a repository nested inside another repository An outer repository contains a pointer to a specific commit of an inner repository, rather than a copy of its files. your-app/ (outer repo) src/ your own files libs/shared/ pointer → commit a1b2c3d shared-lib.git its own repo, elsewhere

What's actually stored: not the inner repo's files, just its URL and one exact commit hash. Anyone who clones your-app runs git submodule update --init to fetch that exact version.

Quick reference

Everything else, in plain terms.

git status

What's staged, changed, or untracked right now.

git diff

Line-by-line detail of what changed, not committed yet.

git branch

Creates a separate line of history to work on without touching main.

git checkout / switch

Moves you to a different branch or commit.

git clone

Copies an entire remote repository to your machine for the first time.

git init

Turns the current folder into a new, empty git repository.

git log

The full list of commits, newest or oldest first.

git remote -v

Shows which remote URLs your local repo is connected to.

Further down the rabbit hole

Not covered above, but worth knowing exists.

git reflog

A log of everywhere HEAD has pointed — can recover commits after a bad reset.

git worktree

Check out two branches at once, in two folders, from one repo.

git config

Set user.name, user.email, and custom command aliases.

git remote add upstream

Track more than one remote — e.g. your fork and the original project.

.gitattributes

Rules for line endings, binary files, and how diffs are shown.

git rerere

Remembers how you resolved a conflict, and reuses it next time it recurs.

git clone --depth / sparse-checkout

Clone partial history or partial folders — useful on huge repos.

git subtree

Like a submodule, but the other repo's files are actually copied in.

git commit -S

Sign a commit with GPG or SSH to prove it really came from you.

git lfs

Tracks large binary files (video, datasets) without bloating the repo.

git hooks

Scripts that run automatically on commit or push — e.g. pre-commit checks.

bare repo

The version-history-only copy that lives on a server, with no working files.