diff mbox series

[v3,6/7] doc: add reference for "--[no-]force-if-includes"

Message ID 20200913145413.18351-7-shrinidhi.kaushik@gmail.com
State Superseded
Headers show
Series push: add "--[no-]force-if-includes" | expand

Commit Message

Srinidhi Kaushik Sept. 13, 2020, 2:54 p.m. UTC
Add documentation for using the new option; append notes for
"--force-with-lease" about using the new option to prevent
unintended remote overwrites when being used in setups where a
tool implicitly updates remote-tracking refs in the background.

Signed-off-by: Srinidhi Kaushik <shrinidhi.kaushik@gmail.com>
---
 Documentation/config/advice.txt |  9 ++++++---
 Documentation/git-push.txt      | 19 +++++++++++++++++++
 2 files changed, 25 insertions(+), 3 deletions(-)

Comments

Junio C Hamano Sept. 14, 2020, 9:01 p.m. UTC | #1
Srinidhi Kaushik <shrinidhi.kaushik@gmail.com> writes:

> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 3b8053447e..b40fe7e7cf 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -320,6 +320,12 @@ 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.
> ++
> +Alternatively, specifying `--force-if-includes` an an ancillary option along
> +with `--force-with-lease[=<refname>[:expect]]` (when "<refname>" or "<expect>"
> +values are unspecified) at the time of `push` will verify if updates from the
> +remote-tracking refs that may have been implicitly updated in the background
> +are integrated locally before allowing a forced update.

You cannot omit <refname> without omitting <expect>, so

	... with "--force-with-lease[=<refname>]" (i.e. without
	saying what exact commit the ref on the remote side must be
	pointing at, or which refs on the remote side are being
	protected) at the time of ...

would be more appropriate.

> +--[no-]force-if-includes::
> +	Force an update only if the tip of the remote-tracking ref
> +	has been integrated locally.
> ++
> +This option verifies if the tip of the remote-tracking ref on which
> +a local branch has based on (for a rewrite), is reachable from at
> +least one of the `reflog` entries of the local branch about to be

If we take the "we don't have to look at a local branch's reflog;
just check HEAD's and rebase will automatically be handled without
expensive merge-base" approach, then

    ... if the tip of the remote-tracking ref was once checked out
    to the working tree (for a rewrite) by seeing if it appears in
    the reflog of "HEAD" ...
Srinidhi Kaushik Sept. 16, 2020, 5:35 a.m. UTC | #2
Hi Junio,

On 09/14/2020 14:01, Junio C Hamano wrote:
> Srinidhi Kaushik <shrinidhi.kaushik@gmail.com> writes:
> 
> > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> > index 3b8053447e..b40fe7e7cf 100644
> > --- a/Documentation/git-push.txt
> > +++ b/Documentation/git-push.txt
> > @@ -320,6 +320,12 @@ 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.
> > ++
> > +Alternatively, specifying `--force-if-includes` an an ancillary option along
> > +with `--force-with-lease[=<refname>[:expect]]` (when "<refname>" or "<expect>"
> > +values are unspecified) at the time of `push` will verify if updates from the
> > +remote-tracking refs that may have been implicitly updated in the background
> > +are integrated locally before allowing a forced update.
> 
> You cannot omit <refname> without omitting <expect>, so
> 
> 	... with "--force-with-lease[=<refname>]" (i.e. without
> 	saying what exact commit the ref on the remote side must be
> 	pointing at, or which refs on the remote side are being
> 	protected) at the time of ...
> 
> would be more appropriate.

OK, that makes sense, will update.
 
> > +--[no-]force-if-includes::
> > +	Force an update only if the tip of the remote-tracking ref
> > +	has been integrated locally.
> > ++
> > +This option verifies if the tip of the remote-tracking ref on which
> > +a local branch has based on (for a rewrite), is reachable from at
> > +least one of the `reflog` entries of the local branch about to be
> 
> If we take the "we don't have to look at a local branch's reflog;
> just check HEAD's and rebase will automatically be handled without
> expensive merge-base" approach, then
> 
>     ... if the tip of the remote-tracking ref was once checked out
>     to the working tree (for a rewrite) by seeing if it appears in
>     the reflog of "HEAD" ...
> 

Right, as mentioned in the other thread, we can go with this route,
will change in the next series.

Thanks.
diff mbox series

Patch

diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index bdd37c3eaa..acbd0c09aa 100644
--- a/Documentation/config/advice.txt
+++ b/Documentation/config/advice.txt
@@ -10,9 +10,8 @@  advice.*::
 		that the check is disabled.
 	pushUpdateRejected::
 		Set this variable to 'false' if you want to disable
-		'pushNonFFCurrent',
-		'pushNonFFMatching', 'pushAlreadyExists',
-		'pushFetchFirst', and 'pushNeedsForce'
+		'pushNonFFCurrent', 'pushNonFFMatching', 'pushAlreadyExists',
+		'pushFetchFirst', 'pushNeedsForce', and 'pushRefNeedsUpdate'
 		simultaneously.
 	pushNonFFCurrent::
 		Advice shown when linkgit:git-push[1] fails due to a
@@ -41,6 +40,10 @@  advice.*::
 		we can still suggest that the user push to either
 		refs/heads/* or refs/tags/* based on the type of the
 		source object.
+	pushRefNeedsUpdate::
+		Shown when linkgit:git-push[1] rejects a forced update of
+		a branch when its remote-tracking ref has updates that we
+		do not have locally.
 	statusAheadBehind::
 		Shown when linkgit:git-status[1] computes the ahead/behind
 		counts for a local ref compared to its remote tracking ref,
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 3b8053447e..b40fe7e7cf 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -320,6 +320,12 @@  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.
++
+Alternatively, specifying `--force-if-includes` an an ancillary option along
+with `--force-with-lease[=<refname>[:expect]]` (when "<refname>" or "<expect>"
+values are unspecified) at the time of `push` will verify if updates from the
+remote-tracking refs that may have been implicitly updated in the background
+are integrated locally before allowing a forced update.
 
 -f::
 --force::
@@ -341,6 +347,19 @@  one branch, use a `+` in front of the refspec to push (e.g `git push
 origin +master` to force a push to the `master` branch). See the
 `<refspec>...` section above for details.
 
+--[no-]force-if-includes::
+	Force an update only if the tip of the remote-tracking ref
+	has been integrated locally.
++
+This option verifies if the tip of the remote-tracking ref on which
+a local branch has based on (for a rewrite), is reachable from at
+least one of the `reflog` entries of the local branch about to be
+updated by force on the remote. The check ensures that any updates
+from the remote have been incorporated locally by rejecting a push
+if that is not the case.
++
+Specifying `--no-force-if-includes` disables this behavior.
+
 --repo=<repository>::
 	This option is equivalent to the <repository> argument. If both
 	are specified, the command-line argument takes precedence.