Re: [PATCH] change 'commands' to comments and improve wording
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 29, 2017, 01:03 UTC
- Message-ID
- <xmqq8tlga2yz.fsf@gitster.mtv.corp.google.com>
- In-Reply-To
- <0102015c4809f8c7-a5cb604c-782d-4a10-87e1-2fe23e9989ba-000000@eu-west-1.amazonses.com>
Adrian <forbesa06@gmail.com> writes: (nothing)
Imagine a reader who finds the title of this commit in 3 weeks from now among 200 other commits. Do you think the reader can guess that this is a documentation fix? Can the reader tell this is about "stash"?
Subject: stash doc: write explanation as comments, not as commands
or something, perhaps. This commit is simple enough that it may not need the body but explaining why would not hurt. Perhaps like this:
In the illustration of workflows in "git stash" documentation,
where it shows sequence of 'git' commands, there are a few steps
that are not literal commands (i.e. "here, you would use your
editor"). Clarify that these are not something the user can
blindly cut-and-paste by turning them into comments.would be clear enough.
> ---
And please sign-off (Documentation/SubmittingPatches) your patch.
Thanks.
Show 42 quoted lines
> Documentation/git-stash.txt | 8 ++++---- > 1 file changed, 4 insertions(+), 4 deletions(-) > > diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt > index 70191d06b69e..3899d36b2bab 100644 > --- a/Documentation/git-stash.txt > +++ b/Documentation/git-stash.txt > @@ -233,7 +233,7 @@ return to your original branch to make the emergency fix, like this: > $ git checkout -b my_wip > $ git commit -a -m "WIP" > $ git checkout master > -$ edit emergency fix > +# ... edit emergency fix ... > $ git commit -a -m "Fix in a hurry" > $ git checkout my_wip > $ git reset --soft HEAD^ > @@ -245,7 +245,7 @@ You can use 'git stash' to simplify the above, like this: > ---------------------------------------------------------------- > # ... hack hack hack ... > $ git stash > -$ edit emergency fix > +# ... edit emergency fix ... > $ git commit -a -m "Fix in a hurry" > $ git stash pop > # ... continue hacking ... > @@ -261,11 +261,11 @@ each change before committing: > # ... hack hack hack ... > $ git add --patch foo # add just first part to the index > $ git stash save --keep-index # save all other changes to the stash > -$ edit/build/test first part > +# ... edit, build and test first part ... > $ git commit -m 'First part' # commit fully tested change > $ git stash pop # prepare to work on all other changes > # ... repeat above five steps until one commit remains ... > -$ edit/build/test remaining parts > +# ... edit, build and test remaining parts ... > $ git commit foo -m 'Remaining parts' > ---------------------------------------------------------------- > > > -- > https://github.com/git/git/pull/361