Git daily workflow (for these notes)

Keeping these notes in sync between two computers: pull, commit, push, git stash, and recovering when they fail. Two GitHub accounts on one machine: ssh-multiple-github-accounts.

The big picture

1 Pull2 Edit3 Add4 Commit5 Push

• Commit ≠ push. A commit is a local save point; a push sends save points to GitHub. Committing alone does not make notes visible on the other PC.
• Pull before you write. You always start from the newest version, which makes conflicts almost impossible.
• Stash is a shelf beside the bench, local only, never pushed.

1. The only two commands you need

cd ~/notes && git pull        # BEFORE you start writing, on every machine
./sync.sh "added apt notes"   # AFTER you finish writing

• Remember only these two and the system works. Why pull first: edit linux/apt.md at home, push, then edit the same file at work without pulling → git has two versions of one file and can’t know which you meant → merge conflict.

2. What the commands do

git status              # what changed since the last save; never destructive, run it whenever unsure
git pull                # download changes made on your other computer
git add -A              # mark all changes "include these in the next save"
git commit -m "msg"     # save a snapshot locally, with a description
git push                # upload your snapshots to GitHub
git log --oneline -10   # last 10 save points, newest first
git remote -v           # which GitHub repo this is linked to

3. When something goes wrong

“Your local changes would be overwritten by merge” → unsaved edits block the pull. Save, then pull:

git add -A && git commit -m "wip" && git pull --rebase

Merge conflict → you edited the same lines on both machines. Git marks the clash in the file:

<<<<<<< HEAD
the version from this computer
=======
the version from the other computer
>>>>>>> abc1234

• Open the file, delete the <<<<<<<, =======, >>>>>>> lines, keep the text you want, then:

git add -A && git rebase --continue

Undo the last commit but keep the edits:

git reset --soft HEAD~1

Get the GitHub version back: destroys local work

git fetch origin && git reset --hard origin/main permanently destroys your local uncommitted work. Only run it when you’re sure.

4. git stash: the workbench shelf

Something else needs the bench now: sweep half-finished work onto a shelf, do the other job, sweep it back. A shelf, not a filing cabinet: things left on it get forgotten.

git stash push -m "what this is"        # shelve all tracked modifications
git stash push -m "msg" -- path/to/file # shelve ONE file only
git stash push -u -m "msg"              # -u also shelves UNTRACKED files
 
git stash list                          # what's on the shelf
git stash show -p stash@{0}             # view a stash as a diff
 
git stash pop                           # apply the newest AND remove it
git stash apply                         # apply but KEEP it on the shelf
git stash pop stash@{2}                 # a specific one
 
git stash drop stash@{0}                # discard one   DESTRUCTIVE, no undo
git stash clear                         # discard ALL   DESTRUCTIVE, no undo

• git stash push is the modern form. Older guides say git stash save: deprecated, and it can’t take a pathspec.

Untracked files are NOT stashed by default

Only tracked files with modifications are shelved; a brand-new file stays put unless you add -u. Usually fine: untracked files move between branches freely, so they’re rarely what blocks you.

5. When to stash

a) Switching branches with modified tracked files. Git refuses rather than destroy your edit:

error: Your local changes to the following files would be overwritten by checkout:
    README.md
Aborting

git stash push -m "wip: readme index"
git switch main
# ...do the other thing...
git switch -                    # "-" = the branch I was just on
git stash pop

b) Pulling with uncommitted work:

git stash push -m "wip"
git pull
git stash pop

• Or skip the dance: git pull --rebase --autostash does exactly this sequence for you.

c) Started work on the wrong branch (especially main by mistake). git stash branch creates the branch, switches to it and pops the stash in one step:

git stash push -m "wip"
git stash branch feat/proper-branch-name

d) Testing whether your changes broke something:

git stash push -m "my changes"
# ...run the test - does it still fail without my edits?...
git stash pop

• A clean way to bisect your own work without committing anything.

6. When NOT to stash

Stash is not storage. For anything you’d be upset to lose, commit to a branch.

	commit on a branch	stash
Shows in git log	yes	no, invisible
Pushed to GitHub	yes	no, local only
Survives deleting the clone	yes	no, gone
Message you’ll understand later	yes	only with -m
Easy to forget for weeks	—	very

• Lives longer than the next hour? Commit it. A rough wip: half-done thing commit is fine (amend or squash later). An unfinished commit is recoverable; a forgotten stash usually isn’t.

A stash is a patch, not a snapshot

It stores the difference from the commit you were on, and pop re-applies it to the tree as it is now. Unchanged tree → applies silently. Same lines changed since → merge conflict, resolved as usual (edit the <<<<<<< markers, then git add). On conflict the stash is kept, so nothing is lost; drop it yourself once resolved.

7. Worked example (2026-08-29)

Notes were edited on the wrong branch; README.md then blocked the switch.

git stash push -m "vpn+ufw index entries" -- README.md   # shelve just that file
git switch main
git pull
git merge docs/ssh-keys-github
git push
git switch -c docs/vpn-and-firewall                      # branch BEFORE resuming
git stash pop                                            # edit returns, no conflict

• The pop was clean because the merge made main’s README.md byte-identical to the commit the stash was taken against, so the patch had exactly the context it expected.
• The real lesson isn’t the stash: branching first would have avoided it.