diff --git a/Overview.md b/Overview.md index 2db5d21..8232a3b 100644 --- a/Overview.md +++ b/Overview.md @@ -33,6 +33,7 @@ 3. [reverted-merge](reverted-merge/README.md) - We revert a merge, but, after fixes are added to the merged branch, we want the changes from merge and the new fixes. 4. [save-my-commit](save-my-commit/README.md) - Should you accidentally or on purpose delete a commit, go here to try and save it. You will use the reflog. 5. [detached-head](detached-head/README.md) - git complains that you are in a "You are in 'detached HEAD' state". What do you do? +6. [force-with-lease](force-with-lease/README.md) - You amended a commit you had already pushed, and now the remote refuses it. Force pushing safely turns out to be harder than `--force-with-lease` suggests. ## Katas On Advanced features diff --git a/force-with-lease/README.md b/force-with-lease/README.md new file mode 100644 index 0000000..4f182df --- /dev/null +++ b/force-with-lease/README.md @@ -0,0 +1,102 @@ +# Force pushing without deleting a colleague's work + +You pushed a commit with a typo in the message. Amending it gives the commit a new ID, so +the remote refuses your next push. The new commit is not a fast-forward from the old one. + +To get the amended commit onto the remote you have to force push. This exercise shows three +ways to do that. Two of them can delete a colleague's work without telling you. + +## Setup + +1. Run `source setup.sh` (or `.\setup.ps1` in PowerShell) + +You get a `remote/` folder that takes the place of GitHub, and an `exercise/` clone with two +commits in it, both already pushed. The second one says `Add lgoin feature`. + +To start over at any point, go back to the top folder and run the setup again: + +```bash +$ cd .. +$ source setup.sh +``` + +## Part 1: Fix a typo in a commit you already pushed + +1. Run `git log --oneline` and find the typo. +2. Fix it: `git commit --amend -m "Add login feature"` +3. Run `git push`. It is rejected with `non-fast-forward`. +4. Run `git push --force-with-lease`. It works. + +That is the normal case. Nobody else had pushed, so there was no other work to lose. + +## Part 2: A colleague pushes and your force push is blocked + +1. Start over: `cd ..` then `source setup.sh` +2. Amend the message again: `git commit --amend -m "Add login feature"` +3. A colleague pushes an urgent fix: `./colleague-pushes-a-fix.sh` + (or `.\colleague-pushes-a-fix.ps1` in PowerShell) +4. Run `git push --force-with-lease` + +The push is rejected with `stale info`. Your `origin/master` still points at the commit you +last saw, but the branch on the remote has moved on. Git compared the two and refused. + +## Part 3: Run git fetch, push again + +Do what most people do when they see `stale info`. Update your copy of the remote and try again. + +1. Run `git fetch` +2. Run `git push --force-with-lease` again, exactly the same command. +3. It succeeds. +4. Go back to the top folder and run `./verify.sh` (or `.\verify.ps1`). + +Your colleague's fix is gone from the remote. It was deleted by the command that is usually +described as the safe one. Try to work out why before reading on. + +> `--force-with-lease` never compared your push against the remote. It compared it against +> **your own copy** of the remote, the `origin/master` ref. `git fetch` updated that copy, +> so the check passed, even though you had not read a single line of what arrived. +> `git pull`, your editor's automatic fetch and most git GUIs update it too, on a timer. + +## Part 4: Find the deleted commit again + +The commit is still in the remote repository. Nothing points to it any more, but the remote +keeps a record of where its branch pointed before: + +```bash +$ git -C remote reflog master +``` + +1. Find the entry from just before your force push. +2. That is how an overwritten branch is recovered, but only if somebody notices, and only + before the server runs garbage collection and removes the commit for good. + +## Part 5: Block the push with a second flag + +1. Start over: `cd ..` then `source setup.sh` +2. Amend, run `./colleague-pushes-a-fix.sh`, then `git fetch`. The same steps as before. +3. This time: `git push --force-with-lease --force-if-includes` + +The push is rejected with `remote ref updated since checkout`. Run `./verify.sh` to confirm +that your colleague's fix is still there. + +`--force-if-includes` adds one more requirement. The commit at the tip of the remote branch +must appear in the reflog of the branch you are rewriting. In practice that means you have to +merge or rebase their work into yours. Fetching on its own is not enough. + +To use it every time, make it the default and add a short alias: + +```bash +$ git config --global push.useForceIfIncludes true +$ git config --global alias.repush "push --force-with-lease --force-if-includes" +``` + +> :bulb: Note: git's documentation says `--force-if-includes` is implied by a bare +> `--force-with-lease`. On git 2.52 that is not what happens. Part 3 uses exactly that form +> and still deletes your colleague's fix. Set the config explicitly. + +## Commands you used + +- `git push --force-with-lease` +- `git push --force-with-lease --force-if-includes` +- `git commit --amend` +- `git -C remote reflog master` diff --git a/force-with-lease/colleague-pushes-a-fix.ps1 b/force-with-lease/colleague-pushes-a-fix.ps1 new file mode 100644 index 0000000..3e6cd31 --- /dev/null +++ b/force-with-lease/colleague-pushes-a-fix.ps1 @@ -0,0 +1,28 @@ +# Plays the part of a colleague who pushes an urgent fix to origin while you +# are busy rewriting your own history. Your clone is deliberately left unaware. +# +# Run it from inside the exercise repository: +# .\colleague-pushes-a-fix.ps1 + +$remote = (Resolve-Path "$PSScriptRoot\..\remote").Path +$work = Join-Path ([System.IO.Path]::GetTempPath()) ("colleague-" + [guid]::NewGuid()) + +git clone -q $remote $work +Push-Location $work + +git config user.name "Colleague" +git config user.email "colleague@example.com" +git config commit.gpgsign false + +# A separate file, so that integrating this work never conflicts with yours. +Set-Content -Value "def reject_empty(password):" -Path fix.py +Add-Content -Value " if not password: raise ValueError('empty password')" -Path fix.py +git add fix.py +git commit -q -m "Fix crash on empty password (URGENT)" +git push -q origin master + +Pop-Location +Remove-Item $work -Recurse -Force + +Write-Output "Your colleague just pushed 'Fix crash on empty password (URGENT)' to origin." +Write-Output "Your clone has not been told about it." diff --git a/force-with-lease/colleague-pushes-a-fix.sh b/force-with-lease/colleague-pushes-a-fix.sh new file mode 100644 index 0000000..0c6571f --- /dev/null +++ b/force-with-lease/colleague-pushes-a-fix.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +# Plays the part of a colleague who pushes an urgent fix to origin while you +# are busy rewriting your own history. Your clone is deliberately left unaware. +# +# Run it from inside the exercise repository: +# ./colleague-pushes-a-fix.sh + +set -e + +REMOTE=$(cd "$(dirname "$0")/../remote" && pwd) +WORKDIR=$(mktemp -d) + +git clone -q "$REMOTE" "$WORKDIR/colleague" +cd "$WORKDIR/colleague" + +git config user.name "Colleague" +git config user.email "colleague@example.com" +git config commit.gpgsign false + +# A separate file, so that integrating this work never conflicts with yours. +echo "def reject_empty(password):" > fix.py +echo " if not password: raise ValueError('empty password')" >> fix.py +git add fix.py +git commit -q -m "Fix crash on empty password (URGENT)" +git push -q origin master + +cd / +rm -rf "$WORKDIR" + +echo "Your colleague just pushed 'Fix crash on empty password (URGENT)' to origin." +echo "Your clone has not been told about it." diff --git a/force-with-lease/setup.ps1 b/force-with-lease/setup.ps1 new file mode 100644 index 0000000..beb7ca8 --- /dev/null +++ b/force-with-lease/setup.ps1 @@ -0,0 +1,46 @@ +# Builds the exercise: a bare repository standing in for GitHub, and a clone of +# it with two commits already pushed - the second one carrying a typo. +# +# Run it from the repository root: +# .\setup.ps1 + +# Start from a clean slate. +if (Test-Path .\remote) { + Remove-Item .\remote -Recurse -Force -ErrorAction:Stop +} +if (Test-Path .\exercise) { + Remove-Item .\exercise -Recurse -Force -ErrorAction:Stop +} + +# The stand-in for GitHub. +git -c init.defaultBranch=master init --bare remote + +# Your clone of it. +git clone ./remote exercise +Set-Location exercise + +# Distinguish the setup commits from yours, and never sign them. +git config --local user.name "exercise setup bot" +git config --local user.email "setup-bot@example.com" +git config --local commit.gpgsign false + +# Keep a reflog in the bare remote, so a clobbered commit can still be found. +git -C ..\remote config core.logAllRefUpdates true + +Set-Content -Value "print('hello')" -Path app.py +git add app.py +git commit -m "Add app" +git push -u origin master + +Add-Content -Value "print('login')" -Path app.py +git add app.py +git commit -m "Add lgoin feature" +git push + +# The script that plays the part of a colleague pushing while you work. +Copy-Item ..\colleague-pushes-a-fix.ps1 colleague-pushes-a-fix.ps1 + +# From here on the commits are yours, so hand the identity back. Signing stays +# off, so a signing prompt cannot derail the exercise. +git config --local --unset user.name +git config --local --unset user.email diff --git a/force-with-lease/setup.sh b/force-with-lease/setup.sh new file mode 100644 index 0000000..5ad566d --- /dev/null +++ b/force-with-lease/setup.sh @@ -0,0 +1,44 @@ +#!/bin/bash + +# Builds the exercise: a bare repository standing in for GitHub, and a clone of +# it with two commits already pushed - the second one carrying a typo. +# +# Run it from the repository root, with source, so that you are left inside the +# exercise repository: +# source setup.sh + +# Start from a clean slate. +rm -rf remote/ exercise/ + +# The stand-in for GitHub. +git -c init.defaultBranch=master init --bare remote + +# Your clone of it. +git clone ./remote exercise +cd exercise + +# Distinguish the setup commits from yours, and never sign them. +git config --local user.name "exercise setup bot" +git config --local user.email "setup-bot@example.com" +git config --local commit.gpgsign false + +# Keep a reflog in the bare remote, so a clobbered commit can still be found. +git -C ../remote config core.logAllRefUpdates true + +echo "print('hello')" > app.py +git add app.py +git commit -m "Add app" +git push -u origin master + +echo "print('login')" >> app.py +git add app.py +git commit -m "Add lgoin feature" +git push + +# The script that plays the part of a colleague pushing while you work. +cp ../colleague-pushes-a-fix.sh colleague-pushes-a-fix.sh + +# From here on the commits are yours, so hand the identity back. Signing stays +# off, so a signing prompt cannot derail the exercise. +git config --local --unset user.name +git config --local --unset user.email diff --git a/force-with-lease/verify.ps1 b/force-with-lease/verify.ps1 new file mode 100644 index 0000000..bf9fdf3 --- /dev/null +++ b/force-with-lease/verify.ps1 @@ -0,0 +1,14 @@ +if (-not (Test-Path .\remote)) { + Write-Output "There is no remote\ folder - run .\setup.ps1 first." + exit 1 +} + +if (@(git -C remote log --oneline master | Select-String "Fix crash on empty password").Count -gt 0) { + Write-Output "Your colleague's fix is safe on origin." + exit 0 +} + +Write-Output "Your colleague's fix is gone from origin - you clobbered it." +Write-Output "It is not lost yet. Find it again with:" +Write-Output " git -C remote reflog master" +exit 1 diff --git a/force-with-lease/verify.sh b/force-with-lease/verify.sh new file mode 100644 index 0000000..8859bd7 --- /dev/null +++ b/force-with-lease/verify.sh @@ -0,0 +1,19 @@ +#! /usr/bin/env sh + +# Run from the top folder: +# ./verify.sh + +if [ ! -d remote ]; then + echo "There is no remote/ folder - run 'source setup.sh' first." + exit 1 +fi + +if git -C remote log --oneline master | grep -q "Fix crash on empty password"; then + echo "Your colleague's fix is safe on origin." + exit 0 +fi + +echo "Your colleague's fix is gone from origin - you clobbered it." +echo "It is not lost yet. Find it again with:" +echo " git -C remote reflog master" +exit 1