Re: Call Me Gitless
- From
- Tarmigan <tarmigan+git@gmail.com>
- Date
- Aug 19, 2008, 00:45 UTC
- Message-ID
- <905315640808181745n7186aa1bu62f6d454255fd805@mail.gmail.com>
- In-Reply-To
- <alpine.LNX.1.00.0808182027240.19665@iabervon.org>
On Mon, Aug 18, 2008 at 5:32 PM, Daniel Barkalow <barkalow@iabervon.org> wrote:
Show 26 quoted lines
> On Mon, 18 Aug 2008, Tarmigan wrote: > >> On Mon, Aug 18, 2008 at 1:20 PM, Junio C Hamano <gitster@pobox.com> wrote: >> > (2) Some concepts in git are different from what they are used to, without >> > any good reason. IOW, the concepts have room for improvement, and our >> > UI is based on these faulty concepts. >> > >> > (3) Some concepts in git may be exactly the same with other systems, yet >> > our UI may operate differently from them without any good reason. >> >> One confusing part of the porcelain may be the way that git's revert >> is different from other systems' revert. What would people think >> about something like this somewhere in git-revert(1)? >> >> +DISCUSSION >> +---------- >> +If you are more familiar with another SCM, 'git revert' may not do what you >> +expect. Specifically, if you want to throw away all changes in your working >> +directory, you should read the man page for 'git reset', particulary the >> +'--hard' option. If you want to extract specific files as they were in a >> +previous commit, you should read the man page for 'git checkout -- <filename>'. > > "as they were in a particular commit"; it works for the current commit as > well as older ones. And skip the first sentence; even people who aren't > familiar with another SCM are reasonably likely to be attracted by the > name "revert" as being descriptive of what they want to do.
Good points, thanks.
> I think this is a good idea, although clever placement is necessary to > neither distract people who really do want "revert" nor get missed by > people who are looking in the wrong place.
Yes, I actually didn't include any context because I wasn't sure where to put it and was hoping for feedback on that front as well. git-revert(1) is very short as it is, so I would be inclined to put the DISCUSSION fairly early, like between the DESCRIPTION and the OPTIONS so it is very easy to find. But it seems incorrect to put it before the options. Perhaps that text should just be a note in the DESCRIPTION?
Thanks, Tarmigan