[PATCH v3] push: Provide situational hints for non-fast-forward errors

[PATCH v3] push: Provide situational hints for non-fast-forward errors

[Christopher Tiwald]

Pushing a non-fast-forward update to a remote repository will result in
an error, but the hint text doesn't provide the correct resolution in
every case. Give better resolution advice in three push scenarios:

1) If you push your current branch and it triggers a non-fast-forward
error, you should merge remote changes with 'git pull' before pushing
again.

2) If you push to a shared repository others push to, and your local
tracking branches are not kept up to date, the 'matching refs' default
will generate non-fast-forward errors on outdated branches. If this is
your workflow, the 'matching refs' default is not for you. Consider
setting the 'push.default' configuration variable to 'current' or
'upstream' to ensure only your current branch is pushed.

3) If you explicitly specify a ref that is not your current branch or
push matching branches with ':', you will generate a non-fast-forward
error if any pushed branch tip is out of date. You should checkout the
offending branch and merge remote changes before pushing again.

Teach transport.c to recognize these scenarios and configure push.c
to hint for them. If 'git push's default behavior changes or we
discover more scenarios, extension is easy. Standardize on the
advice API and add three new advice variables, 'pushNonFFCurrent',
'pushNonFFDefault', and 'pushNonFFMatching'. Setting any of these
to 'false' will disable their affiliated advice. Setting
'pushNonFastForward' to false will disable all three, thus preserving the
config option for users who already set it, but guaranteeing new
users won't disable push advice accidentally.

Based-on-patch-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Christopher Tiwald <christiwald@gmail.com>
---
 Changes since v2:
	- Cleaned up commit message language, specifically in scenario
	  one.
	- Created one config variable per piece of non-ff push advice.
	  Additionally, preserved 'pushNonFastForward' as a means of
	  disabling all non-ff push advice. Users who set this
	  config option should see no change to 'git push'.

 Documentation/config.txt |   19 +++++++++++++--
 advice.c                 |    6 +++++
 advice.h                 |    3 +++
 builtin/push.c           |   60 ++++++++++++++++++++++++++++++++++++++++++----
 cache.h                  |    8 +++++--
 environment.c            |    2 +-
 transport.c              |   13 ++++++++--
 7 files changed, 99 insertions(+), 12 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index c081657..fb386ab 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -138,8 +138,23 @@ advice.*::
 +
 --
 	pushNonFastForward::
-		Advice shown when linkgit:git-push[1] refuses
-		non-fast-forward refs.
+		Set this variable to 'false' if you want to disable
+		'pushNonFFCurrent', 'pushNonFFDefault', and
+		'pushNonFFMatching' simultaneously.
+	pushNonFFCurrent::
+		Advice shown when linkgit:git-push[1] fails due to a
+		non-fast-forward update to the current branch.
+	pushNonFFDefault::
+		Advice to set 'push.default' to 'upstream' or 'current'
+		when you ran linkgit:git-push[1] and pushed 'matching
+		refs' by default (i.e. you did not provide an explicit
+		refspec, and no 'push.default' configuration was set)
+		and it resulted in a non-fast-forward error.
+	pushNonFFMatching::
+		Advice shown when you ran linkgit:git-push[1] and pushed
+		'matching refs' explicitly (i.e. you used ':', or
+		specified a refspec that isn't your current branch) and
+		it resulted in a non-fast-forward error.
 	statusHints::
 		Directions on how to stage/unstage/add shown in the
 		output of linkgit:git-status[1] and the template shown
diff --git a/advice.c b/advice.c
index 01130e5..a492eea 100644
--- a/advice.c
+++ b/advice.c
@@ -1,6 +1,9 @@
 #include "cache.h"
 
 int advice_push_nonfastforward = 1;
+int advice_push_non_ff_current = 1;
+int advice_push_non_ff_default = 1;
+int advice_push_non_ff_matching = 1;
 int advice_status_hints = 1;
 int advice_commit_before_merge = 1;
 int advice_resolve_conflict = 1;
@@ -12,6 +15,9 @@ static struct {
 	int *preference;
 } advice_config[] = {
 	{ "pushnonfastforward", &advice_push_nonfastforward },
+	{ "pushnonffcurrent", &advice_push_non_ff_current },
+	{ "pushnonffdefault", &advice_push_non_ff_default },
+	{ "pushnonffmatching", &advice_push_non_ff_matching },
 	{ "statushints", &advice_status_hints },
 	{ "commitbeforemerge", &advice_commit_before_merge },
 	{ "resolveconflict", &advice_resolve_conflict },
diff --git a/advice.h b/advice.h
index 7bda45b..f3cdbbf 100644
--- a/advice.h
+++ b/advice.h
@@ -4,6 +4,9 @@
 #include "git-compat-util.h"
 
 extern int advice_push_nonfastforward;
+extern int advice_push_non_ff_current;
+extern int advice_push_non_ff_default;
+extern int advice_push_non_ff_matching;
 extern int advice_status_hints;
 extern int advice_commit_before_merge;
 extern int advice_resolve_conflict;
diff --git a/builtin/push.c b/builtin/push.c
index d315475..8a14e4b 100644
--- a/builtin/push.c
+++ b/builtin/push.c
@@ -24,6 +24,7 @@ static int progress = -1;
 static const char **refspec;
 static int refspec_nr;
 static int refspec_alloc;
+static int default_matching_used;
 
 static void add_refspec(const char *ref)
 {
@@ -95,6 +96,9 @@ static void setup_default_push_refspecs(struct remote *remote)
 {
 	switch (push_default) {
 	default:
+	case PUSH_DEFAULT_UNSPECIFIED:
+		default_matching_used = 1;
+		/* fallthru */
 	case PUSH_DEFAULT_MATCHING:
 		add_refspec(":");
 		break;
@@ -114,6 +118,45 @@ static void setup_default_push_refspecs(struct remote *remote)
 	}
 }
 
+static const char message_advice_pull_before_push[] =
+	N_("Updates were rejected because the tip of your current branch is behind\n"
+	   "its remote counterpart. Merge the remote changes (e.g. 'git pull')\n"
+	   "before pushing again.\n"
+	   "See the 'Note about fast-forwards' in 'git push --help' for details.");
+
+static const char message_advice_use_upstream[] =
+	N_("Updates were rejected because a pushed branch tip is behind its remote\n"
+	   "counterpart. If you did not intend to push that branch, you may want to\n"
+	   "specify branches to push or set the 'push.default' configuration\n"
+	   "variable to 'current' or 'upstream' to push only the current branch.");
+
+static const char message_advice_checkout_pull_push[] =
+	N_("Updates were rejected because a pushed branch tip is behind its remote\n"
+	   "counterpart. Check out this branch and merge the remote changes\n"
+	   "(e.g. 'git pull') before pushing again.\n"
+	   "See the 'Note about fast-forwards' in 'git push --help' for details.");
+
+static void advise_pull_before_push(void)
+{
+	if (!advice_push_non_ff_current || !advice_push_nonfastforward)
+		return;
+	advise(_(message_advice_pull_before_push));
+}
+
+static void advise_use_upstream(void)
+{
+	if (!advice_push_non_ff_default || !advice_push_nonfastforward)
+		return;
+	advise(_(message_advice_use_upstream));
+}
+
+static void advise_checkout_pull_push(void)
+{
+	if (!advice_push_non_ff_matching || !advice_push_nonfastforward)
+		return;
+	advise(_(message_advice_checkout_pull_push));
+}
+
 static int push_with_options(struct transport *transport, int flags)
 {
 	int err;
@@ -135,14 +178,21 @@ static int push_with_options(struct transport *transport, int flags)
 		error(_("failed to push some refs to '%s'"), transport->url);
 
 	err |= transport_disconnect(transport);
-
 	if (!err)
 		return 0;
 
-	if (nonfastforward && advice_push_nonfastforward) {
-		fprintf(stderr, _("To prevent you from losing history, non-fast-forward updates were rejected\n"
-				"Merge the remote changes (e.g. 'git pull') before pushing again.  See the\n"
-				"'Note about fast-forwards' section of 'git push --help' for details.\n"));
+	switch (nonfastforward) {
+	default:
+		break;
+	case NON_FF_HEAD:
+		advise_pull_before_push();
+		break;
+	case NON_FF_OTHER:
+		if (default_matching_used)
+			advise_use_upstream();
+		else
+			advise_checkout_pull_push();
+		break;
 	}
 
 	return 1;
diff --git a/cache.h b/cache.h
index e5e1aa4..427b600 100644
--- a/cache.h
+++ b/cache.h
@@ -625,7 +625,8 @@ enum push_default_type {
 	PUSH_DEFAULT_NOTHING = 0,
 	PUSH_DEFAULT_MATCHING,
 	PUSH_DEFAULT_UPSTREAM,
-	PUSH_DEFAULT_CURRENT
+	PUSH_DEFAULT_CURRENT,
+	PUSH_DEFAULT_UNSPECIFIED
 };
 
 extern enum branch_track git_branch_track;
@@ -1008,7 +1009,6 @@ struct ref {
 	char *symref;
 	unsigned int force:1,
 		merge:1,
-		nonfastforward:1,
 		deletion:1;
 	enum {
 		REF_STATUS_NONE = 0,
@@ -1019,6 +1019,10 @@ struct ref {
 		REF_STATUS_REMOTE_REJECT,
 		REF_STATUS_EXPECTING_REPORT
 	} status;
+	enum {
+		NON_FF_HEAD = 1,
+		NON_FF_OTHER
+	} nonfastforward;
 	char *remote_status;
 	struct ref *peer_ref; /* when renaming */
 	char name[FLEX_ARRAY]; /* more */
diff --git a/environment.c b/environment.c
index c93b8f4..d7e6c65 100644
--- a/environment.c
+++ b/environment.c
@@ -52,7 +52,7 @@ enum safe_crlf safe_crlf = SAFE_CRLF_WARN;
 unsigned whitespace_rule_cfg = WS_DEFAULT_RULE;
 enum branch_track git_branch_track = BRANCH_TRACK_REMOTE;
 enum rebase_setup_type autorebase = AUTOREBASE_NEVER;
-enum push_default_type push_default = PUSH_DEFAULT_MATCHING;
+enum push_default_type push_default = PUSH_DEFAULT_UNSPECIFIED;
 #ifndef OBJECT_CREATION_MODE
 #define OBJECT_CREATION_MODE OBJECT_CREATION_USES_HARDLINKS
 #endif
diff --git a/transport.c b/transport.c
index 181f8f2..7864007 100644
--- a/transport.c
+++ b/transport.c
@@ -721,6 +721,10 @@ void transport_print_push_status(const char *dest, struct ref *refs,
 {
 	struct ref *ref;
 	int n = 0;
+	unsigned char head_sha1[20];
+	char *head;
+
+	head = resolve_refdup("HEAD", head_sha1, 1, NULL);
 
 	if (verbose) {
 		for (ref = refs; ref; ref = ref->next)
@@ -738,8 +742,13 @@ void transport_print_push_status(const char *dest, struct ref *refs,
 		    ref->status != REF_STATUS_UPTODATE &&
 		    ref->status != REF_STATUS_OK)
 			n += print_one_push_status(ref, dest, n, porcelain);
-		if (ref->status == REF_STATUS_REJECT_NONFASTFORWARD)
-			*nonfastforward = 1;
+		if (ref->status == REF_STATUS_REJECT_NONFASTFORWARD &&
+		    *nonfastforward != NON_FF_HEAD) {
+			if (!strcmp(head, ref->name))
+				*nonfastforward = NON_FF_HEAD;
+			else
+				*nonfastforward = NON_FF_OTHER;
+		}
 	}
 }
 
-- 
1.7.10.rc1.23.g2a051.dirty

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Junio C Hamano]

Christopher Tiwald <christiwald@gmail.com> writes:

>  Changes since v2:
> 	- Cleaned up commit message language, specifically in scenario
> 	  one.
> 	- Created one config variable per piece of non-ff push advice.
> 	  Additionally, preserved 'pushNonFastForward' as a means of
> 	  disabling all non-ff push advice. Users who set this
> 	  config option should see no change to 'git push'.

This one looks very sensible.  Thanks.

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Jeff King]

On Tue, Mar 20, 2012 at 12:31:33AM -0400, Christopher Tiwald wrote:

>  Changes since v2:
> 	- Cleaned up commit message language, specifically in scenario
> 	  one.
> 	- Created one config variable per piece of non-ff push advice.
> 	  Additionally, preserved 'pushNonFastForward' as a means of
> 	  disabling all non-ff push advice. Users who set this
> 	  config option should see no change to 'git push'.

This version looks pretty good to me, but I have one question:

> @@ -1008,7 +1009,6 @@ struct ref {
>  	char *symref;
>  	unsigned int force:1,
>  		merge:1,
> -		nonfastforward:1,
>  		deletion:1;
>  	enum {
>  		REF_STATUS_NONE = 0,
> @@ -1019,6 +1019,10 @@ struct ref {
>  		REF_STATUS_REMOTE_REJECT,
>  		REF_STATUS_EXPECTING_REPORT
>  	} status;
> +	enum {
> +		NON_FF_HEAD = 1,
> +		NON_FF_OTHER
> +	} nonfastforward;
>  	char *remote_status;
>  	struct ref *peer_ref; /* when renaming */
>  	char name[FLEX_ARRAY]; /* more */

Why is this enum stored inside the ref? It doesn't actually know whether
it is a HEAD or not, and we never actually store that value there. We
always just store a boolean (remote.c, ll. 1294-1298) and access it as
one (remote.c, l. 1300; transport.c, l. 1259).

The only time we use the enum values is via the "int nonfastforward"
passed to transport_push.  I think it would be a lot clearer to leave
nonfastforward as a single bit in the ref, and then define the enum
elsewhere (or even just use #define if we are not going to use the enum
type). Like this on top of your patch:

diff --git a/cache.h b/cache.h
index 427b600..35f3075 100644
--- a/cache.h
+++ b/cache.h
@@ -1009,6 +1009,7 @@ struct ref {
 	char *symref;
 	unsigned int force:1,
 		merge:1,
+		nonfastforward:1,
 		deletion:1;
 	enum {
 		REF_STATUS_NONE = 0,
@@ -1019,10 +1020,6 @@ struct ref {
 		REF_STATUS_REMOTE_REJECT,
 		REF_STATUS_EXPECTING_REPORT
 	} status;
-	enum {
-		NON_FF_HEAD = 1,
-		NON_FF_OTHER
-	} nonfastforward;
 	char *remote_status;
 	struct ref *peer_ref; /* when renaming */
 	char name[FLEX_ARRAY]; /* more */
diff --git a/transport.h b/transport.h
index ce99ef8..1631a35 100644
--- a/transport.h
+++ b/transport.h
@@ -138,6 +138,8 @@ int transport_set_option(struct transport *transport, const char *name,
 void transport_set_verbosity(struct transport *transport, int verbosity,
 	int force_progress);
 
+#define NON_FF_HEAD 1
+#define NON_FF_OTHER 2
 int transport_push(struct transport *connection,
 		   int refspec_nr, const char **refspec, int flags,
 		   int * nonfastforward);


I don't think your patch is buggy, because the enum is perfectly capable
of being used as a single bit. But it's confusing to read, because
ref->nonfastforward will never actually be set to the NON_FF_OTHER enum
value.

-Peff

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Christopher Tiwald]

On Fri, Mar 23, 2012 at 05:41:14PM -0400, Jeff King wrote:
> The only time we use the enum values is via the "int nonfastforward"
> passed to transport_push.  I think it would be a lot clearer to leave
> nonfastforward as a single bit in the ref, and then define the enum
> elsewhere (or even just use #define if we are not going to use the enum
> type).

I used the REF_STATUS_* enum as a template for what I wanted to accomplish
when authoring v1, but did notice there was no other place my new
options made much sense (Junio helped me remove one other call between v1
and v2). I like the readability fixup, but it won't compile as both push.c
and transport.c need to see these. Would something like the following
work? It simply moves the define statements to cache.h, so that both push and
transport can use them.

diff --git a/cache.h b/cache.h
index 427b600..cb960c6 100644
--- a/cache.h
+++ b/cache.h
@@ -1009,6 +1009,7 @@ struct ref {
 	char *symref;
 	unsigned int force:1,
 		merge:1,
+		nonfastforward:1,
 		deletion:1;
 	enum {
 		REF_STATUS_NONE = 0,
@@ -1019,15 +1020,14 @@ struct ref {
 		REF_STATUS_REMOTE_REJECT,
 		REF_STATUS_EXPECTING_REPORT
 	} status;
-	enum {
-		NON_FF_HEAD = 1,
-		NON_FF_OTHER
-	} nonfastforward;
 	char *remote_status;
 	struct ref *peer_ref; /* when renaming */
 	char name[FLEX_ARRAY]; /* more */
 };
 
+#define NON_FF_HEAD  1
+#define NON_FF_OTHER 2
+
 #define REF_NORMAL	(1u << 0)
 #define REF_HEADS	(1u << 1)
 #define REF_TAGS	(1u << 2)


It tests fine locally for me using the same test cases I've been using
all along.

--
Christopher Tiwald

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Jeff King]

On Mon, Mar 26, 2012 at 03:20:01PM -0400, Christopher Tiwald wrote:

> I used the REF_STATUS_* enum as a template for what I wanted to accomplish
> when authoring v1, but did notice there was no other place my new
> options made much sense (Junio helped me remove one other call between v1
> and v2). I like the readability fixup, but it won't compile as both push.c
> and transport.c need to see these. Would something like the following
> work? It simply moves the define statements to cache.h, so that both push and
> transport can use them.

My suggestion put them in transport.h, which is included from both
places. It compiles fine for me. Am I missing something?

Generally I would try to keep their definition near the function
interface which uses them (i.e., transport_push). But I don't feel that
strongly about it.

Your patch is already in 'next', so we will have to build on top rather
than squashing. So here it is with an actual commit message:

-- >8 --
Subject: [PATCH] clean up struct ref's nonfastforward field

Each ref structure contains a "nonfastforward" field which
is set during push to show whether the ref rewound history.
Originally this was a single bit, but it was changed in
f25950f (push: Provide situational hints for non-fast-forward
errors) to an enum differentiating a non-ff of the current
branch versus another branch.

However, we never actually set the member according to the
enum values, nor did we ever read it expecting anything but
a boolean value. But we did use the side effect of declaring
the enum constants to store those values in a totally
different integer variable. The code as-is isn't buggy, but
the enum declaration inside "struct ref" is somewhat
misleading.

Let's convert nonfastforward back into a single bit, and
then define the NON_FF_* constants closer to where they
would be used (they are returned via the "int *nonfastforward"
parameter to transport_push, so we can define them there).

Signed-off-by: Jeff King <peff@peff.net>
---
This is the least-invasive patch. You could also turn the "int
*nonfastforward" into an enum, which might be even more readable.

 cache.h     |    5 +----
 transport.h |    2 ++
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/cache.h b/cache.h
index 427b600..35f3075 100644
--- a/cache.h
+++ b/cache.h
@@ -1009,6 +1009,7 @@ struct ref {
 	char *symref;
 	unsigned int force:1,
 		merge:1,
+		nonfastforward:1,
 		deletion:1;
 	enum {
 		REF_STATUS_NONE = 0,
@@ -1019,10 +1020,6 @@ struct ref {
 		REF_STATUS_REMOTE_REJECT,
 		REF_STATUS_EXPECTING_REPORT
 	} status;
-	enum {
-		NON_FF_HEAD = 1,
-		NON_FF_OTHER
-	} nonfastforward;
 	char *remote_status;
 	struct ref *peer_ref; /* when renaming */
 	char name[FLEX_ARRAY]; /* more */
diff --git a/transport.h b/transport.h
index ce99ef8..1631a35 100644
--- a/transport.h
+++ b/transport.h
@@ -138,6 +138,8 @@ int transport_set_option(struct transport *transport, const char *name,
 void transport_set_verbosity(struct transport *transport, int verbosity,
 	int force_progress);
 
+#define NON_FF_HEAD 1
+#define NON_FF_OTHER 2
 int transport_push(struct transport *connection,
 		   int refspec_nr, const char **refspec, int flags,
 		   int * nonfastforward);
-- 
1.7.10.rc2.3.g0850

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Christopher Tiwald]

On Mon, Mar 26, 2012 at 03:51:50PM -0400, Jeff King wrote:
> On Mon, Mar 26, 2012 at 03:20:01PM -0400, Christopher Tiwald wrote:
> 
> > I used the REF_STATUS_* enum as a template for what I wanted to accomplish
> > when authoring v1, but did notice there was no other place my new
> > options made much sense (Junio helped me remove one other call between v1
> > and v2). I like the readability fixup, but it won't compile as both push.c
> > and transport.c need to see these. Would something like the following
> > work? It simply moves the define statements to cache.h, so that both push and
> > transport can use them.
> 
> My suggestion put them in transport.h, which is included from both
> places. It compiles fine for me. Am I missing something?

Ah nope. That was me. Sorry about the noise. This otherwise makes sense
to me.

--
Christopher Tiwald

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Jeff King]

On Mon, Mar 26, 2012 at 03:57:43PM -0400, Christopher Tiwald wrote:

> > My suggestion put them in transport.h, which is included from both
> > places. It compiles fine for me. Am I missing something?
> 
> Ah nope. That was me. Sorry about the noise. This otherwise makes sense
> to me.

OK. Junio, can you throw the patch from the grandparent on top of
ct/advise-push-default?

-Peff

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Generally I would try to keep their definition near the function
> interface which uses them (i.e., transport_push). But I don't feel that
> strongly about it.

I think that advice makes sense.

> Your patch is already in 'next', so we will have to build on top rather
> than squashing. So here it is with an actual commit message:

If the patch were already in 'next', we would have to build on top, but I
thought I kept it out of 'next' because I knew this deserved a bit more
review time.  Perhaps I screwed up, or you are reading the history
incorrectly?

	... goes and looks ...

> -- >8 --
> Subject: [PATCH] clean up struct ref's nonfastforward field
>
> Each ref structure contains a "nonfastforward" field which
> is set during push to show whether the ref rewound history.
> Originally this was a single bit, but it was changed in
> f25950f (push: Provide situational hints for non-fast-forward

Whew. "git log remotes/ko/next..f25950f" says we are OK.

I'm however tempted to keep this follow-up patch as separate without
squashing.

Re: [PATCH v3] push: Provide situational hints for non-fast-forward errors

[Jeff King]

On Mon, Mar 26, 2012 at 01:05:52PM -0700, Junio C Hamano wrote:

> > Your patch is already in 'next', so we will have to build on top rather
> > than squashing. So here it is with an actual commit message:
> 
> If the patch were already in 'next', we would have to build on top, but I
> thought I kept it out of 'next' because I knew this deserved a bit more
> review time.  Perhaps I screwed up, or you are reading the history
> incorrectly?
> 
> 	... goes and looks ...

Oops, you're right. I don't know why I thought it was, and obviously I
should check before speaking next time. :)

> I'm however tempted to keep this follow-up patch as separate without
> squashing.

Either way is fine with me.

BTW, I was on a semi-vacation when Christopher posted the patch, so I
missed out on most of the timely review. But I really like how it ended
up; it's exactly what I was hoping for when we discussed this a month or
two ago. So thanks for working on it, Christopher.

-Peff