Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

[Philip Oakley]

From: "Philip Oakley" 

From: "Junio C Hamano" 

"Philip Oakley"  writes:


I think the
use of "commit" in an angle-bracket-pair in the label for the
section, i.e. "--fixup=", has been considered to be clear
enough to tell that you can use usual extended SHA-1 syntax to
specify the commit you want to talk about,


I certainly hadn't picked up on that ability to use the extended sha1
syntax (specifying revisions...) here.


By "has been considered", I meant that the documentation text is
still open for improvement.  I just didn't find rewording "commit"
with "commit revision" is that improvement we need there.

Perhaps we need to have somewhere central a section that explains
various notations used in the documentation set.  I think it is safe
to say something like "unless otherwise qualified,  (or any
object type in an angle-bracket-pair) is used as a placeholder to
take any acceptable way to spell object names (cf. gitrevisions for
details)" these days [*1*].


True. I'm cautious that we may accidentally still hide it in another 
document that the user doesn't see when reading "this" (or any other)  man 
page.


Your sentence is short enough to be added to those few key pages that 
users refer to to get them started in the right direction.



*1* In ancient days I think some plumbing commands only took 40-hex
object names, but as far as I know they've all been updated.
--


I'll take the patch series away and have a rework over the coming week or 
so.


Philip 


--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

[Philip Oakley]

From: "Junio C Hamano" 

"Philip Oakley"  writes:


I think the
use of "commit" in an angle-bracket-pair in the label for the
section, i.e. "--fixup=", has been considered to be clear
enough to tell that you can use usual extended SHA-1 syntax to
specify the commit you want to talk about,


I certainly hadn't picked up on that ability to use the extended sha1
syntax (specifying revisions...) here.


By "has been considered", I meant that the documentation text is
still open for improvement.  I just didn't find rewording "commit"
with "commit revision" is that improvement we need there.

Perhaps we need to have somewhere central a section that explains
various notations used in the documentation set.  I think it is safe
to say something like "unless otherwise qualified,  (or any
object type in an angle-bracket-pair) is used as a placeholder to
take any acceptable way to spell object names (cf. gitrevisions for
details)" these days [*1*].


True. I'm cautious that we may accidentally still hide it in another 
document that the user doesn't see when reading "this" (or any other)  man 
page.


Your sentence is short enough to be added to those few key pages that users 
refer to to get them started in the right direction.



*1* In ancient days I think some plumbing commands only took 40-hex
object names, but as far as I know they've all been updated.
--
Philip 


--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

[Junio C Hamano]

"Philip Oakley"  writes:

>> I think the
>> use of "commit" in an angle-bracket-pair in the label for the
>> section, i.e. "--fixup=", has been considered to be clear
>> enough to tell that you can use usual extended SHA-1 syntax to
>> specify the commit you want to talk about,
>
> I certainly hadn't picked up on that ability to use the extended sha1
> syntax (specifying revisions...) here.

By "has been considered", I meant that the documentation text is
still open for improvement.  I just didn't find rewording "commit"
with "commit revision" is that improvement we need there.

Perhaps we need to have somewhere central a section that explains
various notations used in the documentation set.  I think it is safe
to say something like "unless otherwise qualified,  (or any
object type in an angle-bracket-pair) is used as a placeholder to
take any acceptable way to spell object names (cf. gitrevisions for
details)" these days [*1*].


[Footnote]

*1* In ancient days I think some plumbing commands only took 40-hex
object names, but as far as I know they've all been updated.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

[Philip Oakley]

From: "Junio C Hamano" 

Philip Oakley  writes:

Be clearer that the --fixup/--squash options can take any of the
gitrevisions methods of specifying a commit, not just a 'hash'.

Signed-off-by: Philip Oakley 
---
...
@@ -81,15 +81,15 @@ OPTIONS
 --fixup=::
 Construct a commit message for use with `rebase --autosquash`.
 The commit message will be the subject line from the specified
- commit with a prefix of "fixup! ".  See linkgit:git-rebase[1]
- for details.
+ commit revision with a prefix of "fixup! ".  See linkgit:git-rebase[1]
+ and linkgit:gitrevisions[7] for details.


The same comment applies to the other hunk, but rephrasing "commit"
with "commit revision" (the latter is not even in the glossary) does
not make it clearer at all.  Especially when discussing rebases and
anything that rewrites commits, it can easily be mistaken as if you
are talking about v2 of the commit by fixing up the original, but
that is not the impression you want to give.


Hmm, had to read that a few times before I saw what you meant regarding 'v2' 
as the revised commit.




"The specified commit" is clear enough.  It may be debatable if we
want to talk about "how" to specify the commit, though.


Exactly. The latter.


I think the
use of "commit" in an angle-bracket-pair in the label for the
section, i.e. "--fixup=", has been considered to be clear
enough to tell that you can use usual extended SHA-1 syntax to
specify the commit you want to talk about,


I certainly hadn't picked up on that ability to use the extended sha1 syntax 
(specifying revisions...) here.


Part of the issue is that the whole fixup/squash capability is buried within 
just two documents as asides [1], and in the place it's spelt out (in 
rebase) it talks about the commit message being used, which is just part of 
the confusion.



 but if so, that is not
limited to this entry, and I do not think this description or the
other one for the "--squash" option are particularly worse than
those for the "-c" and "-C" options.  The description for "-c" does
say "Take an existing commit object", but that's like "the specified
commit" used here.


OK
--
Philip
[1] just looked at the new Progit version and fixup/squash is not even 
mentioned. 


--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

[Junio C Hamano]

Philip Oakley  writes:
> Be clearer that the --fixup/--squash options can take any of the
> gitrevisions methods of specifying a commit, not just a 'hash'.
>
> Signed-off-by: Philip Oakley 
> ---
> ...
> @@ -81,15 +81,15 @@ OPTIONS
>  --fixup=::
>   Construct a commit message for use with `rebase --autosquash`.
>   The commit message will be the subject line from the specified
> - commit with a prefix of "fixup! ".  See linkgit:git-rebase[1]
> - for details.
> + commit revision with a prefix of "fixup! ".  See linkgit:git-rebase[1]
> + and linkgit:gitrevisions[7] for details.

The same comment applies to the other hunk, but rephrasing "commit"
with "commit revision" (the latter is not even in the glossary) does
not make it clearer at all.  Especially when discussing rebases and
anything that rewrites commits, it can easily be mistaken as if you
are talking about v2 of the commit by fixing up the original, but
that is not the impression you want to give.

"The specified commit" is clear enough.  It may be debatable if we
want to talk about "how" to specify the commit, though.  I think the
use of "commit" in an angle-bracket-pair in the label for the
section, i.e. "--fixup=", has been considered to be clear
enough to tell that you can use usual extended SHA-1 syntax to
specify the commit you want to talk about, but if so, that is not
limited to this entry, and I do not think this description or the
other one for the "--squash" option are particularly worse than
those for the "-c" and "-C" options.  The description for "-c" does
say "Take an existing commit object", but that's like "the specified
commit" used here.

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

[Philip Oakley]

Be clearer that the --fixup/--squash options can take any of the
gitrevisions methods of specifying a commit, not just a 'hash'.

Signed-off-by: Philip Oakley 
---
v1
It's not immediately obvious what different forms the 
option can take. Spell out, and refer to the git revisions guide,
that any of the revision methods will work.

On a side note, if one looks at the glossary, a  links to
 which links to  (and only tangentially
"about" revisions) which then says "uniquely identified by the SHA-1",
so it is easy to think one should use the sha1 here.

I only discovered this misunderstanding while following up
other parts of this series!
---
 Documentation/git-commit.txt | 8 
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index e704953..3600929 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -81,15 +81,15 @@ OPTIONS
 --fixup=::
Construct a commit message for use with `rebase --autosquash`.
The commit message will be the subject line from the specified
-   commit with a prefix of "fixup! ".  See linkgit:git-rebase[1]
-   for details.
+   commit revision with a prefix of "fixup! ".  See linkgit:git-rebase[1]
+   and linkgit:gitrevisions[7] for details.
 
 --squash=::
Construct a commit message for use with `rebase --autosquash`.
The commit message subject line is taken from the specified
-   commit with a prefix of "squash! ".  Can be used with additional
+   commit revision with a prefix of "squash! ".  Can be used with 
additional
commit message options (`-m`/`-c`/`-C`/`-F`). See
-   linkgit:git-rebase[1] for details.
+   linkgit:git-rebase[1] and linkgit:gitrevisions[7] for details.
 
 --reset-author::
When used with -C/-c/--amend options, or when committing after a
-- 
2.9.0.windows.1

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html