git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
* [PATCH] doc: fix a typo and clarify a sentence
@ 2018-10-03 21:08 Mihir Mehta
  2018-10-05  6:20 ` Junio C Hamano
  0 siblings, 1 reply; 7+ messages in thread
From: Mihir Mehta @ 2018-10-03 21:08 UTC (permalink / raw)
  To: git; +Cc: gitster, sunshine, Mihir Mehta

I noticed that git-merge-base was unlikely to actually be a git command,
and tried it in my shell. Seeing that it doesn't work, I cleaned up two
places in the docs where it appears.

Signed-off-by: Mihir Mehta <mihir@cs.utexas.edu>
---
 Documentation/git-diff.txt                  | 5 +++--
 Documentation/howto/update-hook-example.txt | 2 +-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index b180f1fa5..6173f569e 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -72,8 +72,9 @@ two blob objects, or changes between two files on disk.
 	This form is to view the changes on the branch containing
 	and up to the second <commit>, starting at a common ancestor
 	of both <commit>.  "git diff A\...B" is equivalent to
-	"git diff $(git-merge-base A B) B".  You can omit any one
-	of <commit>, which has the same effect as using HEAD instead.
+	"git diff $(git merge-base A B) B".  You can omit any one
+	of the two instances of <commit>, which has the same effect as
+	using HEAD in its place.
 
 Just in case if you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt
index a5193b1e5..89821ec74 100644
--- a/Documentation/howto/update-hook-example.txt
+++ b/Documentation/howto/update-hook-example.txt
@@ -80,7 +80,7 @@ case "$1" in
       info "The branch '$1' is new..."
     else
       # updating -- make sure it is a fast-forward
-      mb=$(git-merge-base "$2" "$3")
+      mb=$(git merge-base "$2" "$3")
       case "$mb,$2" in
         "$2,$mb") info "Update is fast-forward" ;;
 	*)	  noff=y; info "This is not a fast-forward update.";;
-- 
2.19.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] doc: fix a typo and clarify a sentence
  2018-10-03 21:08 [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
@ 2018-10-05  6:20 ` Junio C Hamano
  2018-10-10 15:20   ` Mihir Mehta
  0 siblings, 1 reply; 7+ messages in thread
From: Junio C Hamano @ 2018-10-05  6:20 UTC (permalink / raw)
  To: Mihir Mehta; +Cc: git, sunshine

Mihir Mehta <mihir@cs.utexas.edu> writes:

> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index b180f1fa5..6173f569e 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -72,8 +72,9 @@ two blob objects, or changes between two files on disk.
>  	This form is to view the changes on the branch containing
>  	and up to the second <commit>, starting at a common ancestor
>  	of both <commit>.  "git diff A\...B" is equivalent to
> -	"git diff $(git-merge-base A B) B".  You can omit any one
> -	of <commit>, which has the same effect as using HEAD instead.
> +	"git diff $(git merge-base A B) B".  You can omit any one

"git merge-base" is a more modern way to spell "git-merge-base" and
we have been trying to update the mention of the latter in the docs
to the former.  Thanks for doing this.

> +	of the two instances of <commit>, which has the same effect as

The paragraph is about <commit>...<commit> three-dot notation.  I
suspect that you wanted to say <commit>... and ...<commit> are
allowed, implying that a bare ... is not allowed and does not mean
the same thing as what HEAD...HEAD means.  But that is not the case.
Asking "git diff HEAD...HEAD" by omitting both may not give very
interesting output (it always becomes a no-op), but nevertheless it
is a valid thing to ask (iow "git diff $commit1...$commit2" is what
you can safely write without having to worry about one or both going
empty string).  So I'd rather not to see this change in this form.
It is an incomplete attempt to discourage use of <empty>...<empty>
but without giving enough justification.

	Side note.  I am not recommending to do so, but
	"discouragement with enough justification" would look like
	this.

	You can omit <commit> on any side of the three dots, which
	has the same effect as using HEAD instead.  Omitting both
	and leaving only three dots is not an error but that merely
	specifies a set of commits that are and are not reachable
	from HEAD at the same time, which by definition is an empty
	set, hence it is not very useful.

> +	using HEAD in its place.

> +++ b/Documentation/howto/update-hook-example.txt
> @@ -80,7 +80,7 @@ case "$1" in
>        info "The branch '$1' is new..."
>      else
>        # updating -- make sure it is a fast-forward
> -      mb=$(git-merge-base "$2" "$3")
> +      mb=$(git merge-base "$2" "$3")

I strongly suspect that inside update-hook, the original still
should work (iow, $GIT_EXEC_PATH should already have been prepended
to $PATH before a hoook is called).  But the updated form should
also work, and it is the form we humans need to type, so let's take
this change.

Thanks.

>        case "$mb,$2" in
>          "$2,$mb") info "Update is fast-forward" ;;
>  	*)	  noff=y; info "This is not a fast-forward update.";;

^ permalink raw reply	[flat|nested] 7+ messages in thread

* 
  2018-10-05  6:20 ` Junio C Hamano
@ 2018-10-10 15:20   ` Mihir Mehta
  2018-10-10 15:20     ` [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
  2018-10-10 22:19     ` none Junio C Hamano
  0 siblings, 2 replies; 7+ messages in thread
From: Mihir Mehta @ 2018-10-10 15:20 UTC (permalink / raw)
  To: gitster; +Cc: git

Thanks, Junio. Instead of removing that part of the patch, I opted to
expand it to make it a little clearer (in my opinion) than it was
before. Let me know if this works.

Mihir.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH] doc: fix a typo and clarify a sentence
  2018-10-10 15:20   ` Mihir Mehta
@ 2018-10-10 15:20     ` Mihir Mehta
  2018-10-10 22:19     ` none Junio C Hamano
  1 sibling, 0 replies; 7+ messages in thread
From: Mihir Mehta @ 2018-10-10 15:20 UTC (permalink / raw)
  To: gitster; +Cc: git, Mihir Mehta

I noticed that git-merge-base was unlikely to actually be a git command,
and tried it in my shell. Seeing that it doesn't work, I cleaned up two
places in the docs where it appears.

Signed-off-by: Mihir Mehta <mihir@cs.utexas.edu>
---
 Documentation/git-diff.txt                  | 7 ++++---
 Documentation/howto/update-hook-example.txt | 2 +-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index b180f1fa5..a122f9ded 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -72,10 +72,11 @@ two blob objects, or changes between two files on disk.
 	This form is to view the changes on the branch containing
 	and up to the second <commit>, starting at a common ancestor
 	of both <commit>.  "git diff A\...B" is equivalent to
-	"git diff $(git-merge-base A B) B".  You can omit any one
-	of <commit>, which has the same effect as using HEAD instead.
+	"git diff $(git merge-base A B) B".  You can omit any one
+	of the two instances of <commit>, which has the same effect as
+	using HEAD in its place; omitting both results in an empty diff.
 
-Just in case if you are doing something exotic, it should be
+Just in case you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
 in the last two forms that use ".." notations, can be any
 <tree>.
diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt
index a5193b1e5..89821ec74 100644
--- a/Documentation/howto/update-hook-example.txt
+++ b/Documentation/howto/update-hook-example.txt
@@ -80,7 +80,7 @@ case "$1" in
       info "The branch '$1' is new..."
     else
       # updating -- make sure it is a fast-forward
-      mb=$(git-merge-base "$2" "$3")
+      mb=$(git merge-base "$2" "$3")
       case "$mb,$2" in
         "$2,$mb") info "Update is fast-forward" ;;
 	*)	  noff=y; info "This is not a fast-forward update.";;
-- 
2.19.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: none
  2018-10-10 15:20   ` Mihir Mehta
  2018-10-10 15:20     ` [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
@ 2018-10-10 22:19     ` Junio C Hamano
  2018-10-10 22:26       ` [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
  1 sibling, 1 reply; 7+ messages in thread
From: Junio C Hamano @ 2018-10-10 22:19 UTC (permalink / raw)
  To: Mihir Mehta; +Cc: git

Mihir Mehta <mihir@cs.utexas.edu> writes:

> Thanks, Junio. Instead of removing that part of the patch, I opted to
> expand it to make it a little clearer (in my opinion) than it was
> before. Let me know if this works.

I am mildly negative on that change.  "Omitting both would give an
empty diff" would be understandable to anybody who understands that
an omitted end of dot-dot is substituted with HEAD *and* thinks what
range HEAD..HEAD means, so it is just an additional noise to them,
and to those who do not want to waste time on thinking, it is a
statement that reads as if "it will be an error" without saying why
it is an error.  So overall, it seems, at least to me, that the
additional text adds negative value.

So, I dunno.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH] doc: fix a typo and clarify a sentence
  2018-10-10 22:19     ` none Junio C Hamano
@ 2018-10-10 22:26       ` Mihir Mehta
  2018-10-10 23:27         ` Junio C Hamano
  0 siblings, 1 reply; 7+ messages in thread
From: Mihir Mehta @ 2018-10-10 22:26 UTC (permalink / raw)
  To: gitster; +Cc: git, Mihir Mehta

I noticed that git-merge-base was unlikely to actually be a git command,
and tried it in my shell. Seeing that it doesn't work, I cleaned up two
places in the docs where it appears.

Signed-off-by: Mihir Mehta <mihir@cs.utexas.edu>
---
 Documentation/git-diff.txt                  | 4 ++--
 Documentation/howto/update-hook-example.txt | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index b180f1fa5..030f162f3 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -72,10 +72,10 @@ two blob objects, or changes between two files on disk.
 	This form is to view the changes on the branch containing
 	and up to the second <commit>, starting at a common ancestor
 	of both <commit>.  "git diff A\...B" is equivalent to
-	"git diff $(git-merge-base A B) B".  You can omit any one
+	"git diff $(git merge-base A B) B".  You can omit any one
 	of <commit>, which has the same effect as using HEAD instead.
 
-Just in case if you are doing something exotic, it should be
+Just in case you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
 in the last two forms that use ".." notations, can be any
 <tree>.
diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt
index a5193b1e5..89821ec74 100644
--- a/Documentation/howto/update-hook-example.txt
+++ b/Documentation/howto/update-hook-example.txt
@@ -80,7 +80,7 @@ case "$1" in
       info "The branch '$1' is new..."
     else
       # updating -- make sure it is a fast-forward
-      mb=$(git-merge-base "$2" "$3")
+      mb=$(git merge-base "$2" "$3")
       case "$mb,$2" in
         "$2,$mb") info "Update is fast-forward" ;;
 	*)	  noff=y; info "This is not a fast-forward update.";;
-- 
2.19.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] doc: fix a typo and clarify a sentence
  2018-10-10 22:26       ` [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
@ 2018-10-10 23:27         ` Junio C Hamano
  0 siblings, 0 replies; 7+ messages in thread
From: Junio C Hamano @ 2018-10-10 23:27 UTC (permalink / raw)
  To: Mihir Mehta; +Cc: git

Mihir Mehta <mihir@cs.utexas.edu> writes:

> -Just in case if you are doing something exotic, it should be
> +Just in case you are doing something exotic, it should be

Thanks.  Somehow I didn't notice this change earlier, but it looks
good, too.

Will queue.

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, back to index

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-10-03 21:08 [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
2018-10-05  6:20 ` Junio C Hamano
2018-10-10 15:20   ` Mihir Mehta
2018-10-10 15:20     ` [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
2018-10-10 22:19     ` none Junio C Hamano
2018-10-10 22:26       ` [PATCH] doc: fix a typo and clarify a sentence Mihir Mehta
2018-10-10 23:27         ` Junio C Hamano

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox