Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^
- From
Drew Northup <drew.northup@maine.edu>
- Date
- Dec 1, 2010, 19:13 UTC
- Message-ID
- <1291230820.11917.25.camel@drew-northup.unet.maine.edu>
- In-Reply-To
- <1291227258-17922-1-git-send-email-jari.aalto@cante.net>
On Wed, 2010-12-01 at 20:14 +0200, jari.aalto@cante.net wrote:
Show 42 quoted lines
> From: Jari Aalto <jari.aalto@cante.net> > > In order to easily read paragraphs, use same notation and do not mixed > both ^ and ~N. This helps digesting the information more easier as the > tokens stay the same (dcumentation uniformity). > > Signed-off-by: Jari Aalto <jari.aalto@cante.net> > --- > Documentation/git-reset.txt | 6 +++--- > 1 files changed, 3 insertions(+), 3 deletions(-) > > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt > index fd72976..b679c99 100644 > --- a/Documentation/git-reset.txt > +++ b/Documentation/git-reset.txt > @@ -129,7 +129,7 @@ Undo a commit and redo:: > + > ------------ > $ git commit ... > -$ git reset --soft HEAD^ <1> > +$ git reset --soft HEAD~1 <1> > $ edit <2> > $ git commit -a -c ORIG_HEAD <3> > ------------ > @@ -166,7 +166,7 @@ $ git commit ... > $ git reset --hard HEAD~3 <1> > ------------ > + > -<1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad > +<1> The last three commits (HEAD, HEAD~1, and HEAD~2) were bad > and you do not want to ever see them again. Do *not* do this if > you have already given these commits to somebody else. (See the > "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for > @@ -237,7 +237,7 @@ $ git checkout master > $ fix fix fix > $ git commit ;# commit with real log > $ git checkout feature > -$ git reset --soft HEAD^ ;# go back to WIP state <2> > +$ git reset --soft HEAD~1 ;# go back to WIP state <2> > $ git reset <3> > ------------ > +
I have to disagree here. Part of the task of good documentation is to show not just what any one user may prefer (unless it is an accepted standard, such as an RFC) but also what is possible. Removing the non "~" examples is actually a disservice to the documentation reader in a great many cases. What makes more sense in this case is to refer at some point to the documentation which describes the allowed reference formats. This makes it clear that: (1) There are several allowed reference formats, and these are examples using them; (2) These, over here, are descriptions of the allowed reference formats.
Also, strictly speaking, each separate operation example is a "paragraph" inside of a subsection and "EXAMPLES" is the containing section. If you look at it this way it is already reasonably internally consistent.
-- -Drew Northup N1XIM AKA RvnPhnx on OPN ________________________________________________ "As opposed to vegetable or mineral error?" -John Pescatore, SANS NewsBites Vol. 12 Num. 59