threads / patch / 50659

patchgit-reset.txt: clarify documentation

Subject: [PATCH] git-reset.txt: clarify documentation

## tl;dr

5 messages between Mar 5, 2019 and Mar 5, 2019. Diffs are folded; open one to read it.

replies: 4people: 2as markdown or json

Denton Liu· Mar 5, 2019, 18:54 UTC · lore

git-reset.txt contained a missing "a" and "wrt". Fix the missing "a" for correctness and replace "wrt" with "with respect to" so that the documentation is not so cryptic.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-reset.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

Show changes to Documentation/git-reset.txt +5 −5

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 132f8e55f6..dbf4e567a2 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -428,11 +428,11 @@ working index HEAD target         working index HEAD
 
 `reset --merge` is meant to be used when resetting out of a conflicted
 merge. Any mergy operation guarantees that the working tree file that is
-involved in the merge does not have local change wrt the index before
-it starts, and that it writes the result out to the working tree. So if
-we see some difference between the index and the target and also
-between the index and the working tree, then it means that we are not
-resetting out from a state that a mergy operation left after failing
+involved in the merge does not have a local change with respect to the
+index before it starts, and that it writes the result out to the working
+tree. So if we see some difference between the index and the target and
+also between the index and the working tree, then it means that we are
+not resetting out from a state that a mergy operation left after failing
 with a conflict. That is why we disallow `--merge` option in this case.
 
 `reset --keep` is meant to be used when removing some of the last

-- 
2.21.0.260.g8f7229c82f

Junio C Hamano· Mar 5, 2019, 22:30 UTC · re: Denton Liu · lore

Re: [PATCH] git-reset.txt: clarify documentation

Denton Liu <liu.denton@gmail.com> writes:

> git-reset.txt contained a missing "a" and "wrt". Fix the missing "a" for
> correctness and replace "wrt" with "with respect to" so that the
> documentation is not so cryptic.

Could you try again without unrelated reflowing of the text?

Thanks.

Show 27 quoted lines

>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>  Documentation/git-reset.txt | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
> index 132f8e55f6..dbf4e567a2 100644
> --- a/Documentation/git-reset.txt
> +++ b/Documentation/git-reset.txt
> @@ -428,11 +428,11 @@ working index HEAD target         working index HEAD
>  
>  `reset --merge` is meant to be used when resetting out of a conflicted
>  merge. Any mergy operation guarantees that the working tree file that is
> -involved in the merge does not have local change wrt the index before
> -it starts, and that it writes the result out to the working tree. So if
> -we see some difference between the index and the target and also
> -between the index and the working tree, then it means that we are not
> -resetting out from a state that a mergy operation left after failing
> +involved in the merge does not have a local change with respect to the
> +index before it starts, and that it writes the result out to the working
> +tree. So if we see some difference between the index and the target and
> +also between the index and the working tree, then it means that we are
> +not resetting out from a state that a mergy operation left after failing
>  with a conflict. That is why we disallow `--merge` option in this case.
>  
>  `reset --keep` is meant to be used when removing some of the last

Denton Liu· Mar 5, 2019, 22:37 UTC · re: Junio C Hamano · lore

Re: [PATCH] git-reset.txt: clarify documentation

Hi Junio,

On Wed, Mar 06, 2019 at 07:30:40AM +0900, Junio C Hamano wrote:

Show 9 quoted lines

> Denton Liu <liu.denton@gmail.com> writes:
> 
> > git-reset.txt contained a missing "a" and "wrt". Fix the missing "a" for
> > correctness and replace "wrt" with "with respect to" so that the
> > documentation is not so cryptic.
> 
> Could you try again without unrelated reflowing of the text?
> 
> Thanks.

Should reflowing the text be done in a separate patch or should it just not be done at all and just be considered noise?

Thanks,

Denton

Junio C Hamano· Mar 5, 2019, 22:49 UTC · re: Denton Liu · lore

Re: [PATCH] git-reset.txt: clarify documentation

Denton Liu <liu.denton@gmail.com> writes:

> Should reflowing the text be done in a separate patch or should it just
> not be done at all and just be considered noise?

Of course when the rewrite is so extensive that the two versions of the whole paragraph needs to be carefully read and compared to judge if the change is desirable, reflowing of the paragraph would not waste reviewer's time trying to spot where the change is and also trying to verify there is no other change, and in such a case, reflowing would be very much OK.

For this particular case, however, I would say it is the latter, as the way I would have done it would look like either of these, which would not leave the result any harder to read with unnaturally uneven lines.

Thanks.

(variant #1)

 Documentation/git-reset.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Show changes to Documentation/git-reset.txt +4 −3

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 132f8e55f6..26e746c53f 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -428,8 +428,8 @@ working index HEAD target         working index HEAD
 
 `reset --merge` is meant to be used when resetting out of a conflicted
 merge. Any mergy operation guarantees that the working tree file that is
-involved in the merge does not have local change wrt the index before
-it starts, and that it writes the result out to the working tree. So if
+involved in the merge does not have a local change with respect to the index
+before it starts, and that it writes the result out to the working tree. So if
 we see some difference between the index and the target and also
 between the index and the working tree, then it means that we are not
 resetting out from a state that a mergy operation left after failing



(variant #2)

 Documentation/git-reset.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 132f8e55f6..e952b28305 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -428,7 +428,8 @@ working index HEAD target         working index HEAD
 
 `reset --merge` is meant to be used when resetting out of a conflicted
 merge. Any mergy operation guarantees that the working tree file that is
-involved in the merge does not have local change wrt the index before
+involved in the merge does not have a local change with respect to
+the index before
 it starts, and that it writes the result out to the working tree. So if
 we see some difference between the index and the target and also
 between the index and the working tree, then it means that we are not

Denton Liu· Mar 5, 2019, 23:34 UTC · re: Denton Liu · lore

[PATCH v2] git-reset.txt: clarify documentation

git-reset.txt contained a missing "a" and "wrt". Fix the missing "a" for correctness and replace "wrt" with "with respect to" so that the documentation is not so cryptic.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---

My mistake, I fired off the email before it was ready.

---
 Documentation/git-reset.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Show changes to Documentation/git-reset.txt +2 −1

diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index 132f8e55f6..e952b28305 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -428,7 +428,8 @@ working index HEAD target         working index HEAD
 
 `reset --merge` is meant to be used when resetting out of a conflicted
 merge. Any mergy operation guarantees that the working tree file that is
-involved in the merge does not have local change wrt the index before
+involved in the merge does not have a local change with respect to
+the index before
 it starts, and that it writes the result out to the working tree. So if
 we see some difference between the index and the target and also
 between the index and the working tree, then it means that we are not

-- 
2.21.0.260.g8f7229c82f