path: root/Documentation/git-push.txt
diff options
authorÆvar Arnfjörð Bjarmason <>2017-04-19 09:22:03 (GMT)
committerJunio C Hamano <>2017-04-20 01:53:06 (GMT)
commitf17d642d3b0fa64879d59b311e596949f2a1f6d2 (patch)
treedf003ca2ee3da78cd623fb4baef92a7a2934c3d5 /Documentation/git-push.txt
parent49800c940790cc7465d1b03e08d472ffd8684808 (diff)
push: document & test --force-with-lease with multiple remotes
Document & test for cases where there are two remotes pointing to the same URL, and a background fetch & subsequent `git push --force-with-lease` shouldn't clobber un-updated references we haven't fetched. Some editors like Microsoft's VSC have a feature to auto-fetch in the background, this bypasses the protections offered by --force-with-lease & --force-with-lease=<refname>, as noted in the documentation being added here. See the 'Tools that do an automatic fetch defeat "git push --force-with-lease"' (<>) git mailing list thread for more details. Jakub Narębski suggested this method of adding another remote to bypass this edge case, document that & add a test for it. Signed-off-by: Ævar Arnfjörð Bjarmason <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/git-push.txt')
1 files changed, 41 insertions, 0 deletions
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 1624a35..0a63966 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -217,6 +217,47 @@ with this feature.
"--no-force-with-lease" will cancel all the previous --force-with-lease on the
command line.
+A general note on safety: supplying this option without an expected
+value, i.e. as `--force-with-lease` or `--force-with-lease=<refname>`
+interacts very badly with anything that implicitly runs `git fetch` on
+the remote to be pushed to in the background, e.g. `git fetch origin`
+on your repository in a cronjob.
+The protection it offers over `--force` is ensuring that subsequent
+changes your work wasn't based on aren't clobbered, but this is
+trivially defeated if some background process is updating refs in the
+background. We don't have anything except the remote tracking info to
+go by as a heuristic for refs you're expected to have seen & are
+willing to clobber.
+If your editor or some other system is running `git fetch` in the
+background for you a way to mitigate this is to simply set up another
+ git remote add origin-push $(git config remote.origin.url)
+ git fetch origin-push
+Now when the background process runs `git fetch origin` the references
+on `origin-push` won't be updated, and thus commands like:
+ git push --force-with-lease origin-push
+Will fail unless you manually run `git fetch origin-push`. This method
+is of course entirely defeated by something that runs `git fetch
+--all`, in that case you'd need to either disable it or do something
+more tedious like:
+ git fetch # update 'master' from remote
+ git tag base master # mark our base point
+ git rebase -i master # rewrite some commits
+ git push --force-with-lease=master:base master:master
+I.e. create a `base` tag for versions of the upstream code that you've
+seen and are willing to overwrite, then rewrite history, and finally
+force push changes to `master` if the remote version is still at
+`base`, regardless of what your local `remotes/origin/master` has been
+updated to in the background.