From: "Philip Oakley" <philipoakley@iee.org>
To: "Philip Oakley" <philipoakley@iee.org>,
"Junio C Hamano" <gitster@pobox.com>
Cc: "Stefan Beller" <sbeller@google.com>, "git" <git@vger.kernel.org>,
"Kevin Daudt" <me@ikke.info>,
"Jacob Keller" <jacob.keller@gmail.com>,
"Johannes Schindelin" <Johannes.Schindelin@gmx.de>
Subject: Re: [PATCH 6/7] builtin/describe.c: describe a blob
Date: Mon, 20 Nov 2017 18:18:51 -0000 [thread overview]
Message-ID: <B89FAB6895F940EBA45554F20184302F@PhilipOakley> (raw)
In-Reply-To: 205BDB5638F64690AF6BE91360CE155E@PhilipOakley
From: "Philip Oakley" <philipoakley@iee.org>
s/with/without/ ...
> From: "Junio C Hamano" <gitster@pobox.com>
> : Friday, November 10, 2017 1:24 AM
> [catch up]
>
>> "Philip Oakley" <philipoakley@iee.org> writes:
>>
>>> From: "Stefan Beller" <sbeller@google.com>
>>>> Rereading this discussion, there is currently no urgent thing to
>>>> address?
>>>
>>> True.
>>>
>>>> Then the state as announced by the last cooking email, to just cook
>>>> it, seems
>>>> about right and we'll wait for further feedback.
>>
>> A shiny new toy that is not a fix for a grave bug is rarely urgent,
>> so with that criterion, we'd end up with hundreds of topics not in
>> 'next' but in 'pu' waiting for the original contributor to get out
>> of his or her procrastination, which certainly is not what I want to
>> see, as I'd have to throw them into the Stalled bin and then
>> eventually discard them, while having to worry about possible
>> mismerges with remaining good topics caused by these topics
>> appearing and disappearing from 'pu'.
>>
>> I'd rather see any topic that consumed reviewers' time to be
>> polished enough to get into 'next' while we all recall the issues
>> raised during previous reviews. I consider the process to further
>> incrementally polish it after that happens a true "cooking".
>>
>> For this topic, aside from "known issues" that we decided to punt
>> for now, my impression was that the code is in good enough shape,
>> and we need a bit of documentation polishes before I can mark it
>> as "Will merge to 'next'".
>>
>>> Possibly only checking the documenation aspects, so folks don't fall
>>> into the same trap as me.. ;-)
>>
>> Yup, so let's resolve that documentation thing while we remember
>> that the topic has that issue, and what part of the documentation
>> we find needs improvement.
>>
>> I am not sure what "trap: you fell into, though. Are you saying
>> that giving
>>
>> git describe [<option to describe a commit>...] <commit-ish>
>> git describe [<option to describe a blob>...] <blob>
>>
>> in the synopsis is not helpful, because the user may not know what
>> kind of object s/he has, and cannot decide from which set of options
>> to pick? Then an alternative would be to list
>
> (If I remember correctly) My nit pick was roughly along the lines you
> suggest, and that the two option lists (for commit-ish and blob) were
> shown in different ways, which could lead to the scenarion that, with
> knowing the
s/with/without/ ...
> oid object type (or knowing how to get it), the user could give an invalid
> option, and think the command failure was because the oid was invalid, not
> that the option was not appropriate, along with variations on that theme.
>
> The newer synopsis (v5) looks Ok in that it avoids digging the hole by not
> mentioning the blob options. Personally I'm more for manuals that tend
> toward instructional, rather than being expert references. I'd sneak in a
> line saying "The object type can be determined using `git cat-file`.", but
> maybe that's my work environment...
>
>>
>> git describe [<option>...] <object>
>>
>> in the synopsis, say upfront that most options are applicable only
>> when describing a commit-ish, and when describing a blob, we do
>> quite different thing and a separate set of options apply, perhaps?
>>
> --
> Philip
next prev parent reply other threads:[~2017-11-20 18:19 UTC|newest]
Thread overview: 110+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-10-28 0:44 [RFC PATCH 0/3] git-describe <blob> ? Stefan Beller
2017-10-28 0:45 ` [PATCH 1/3] list-objects.c: factor out traverse_trees_and_blobs Stefan Beller
2017-10-28 0:45 ` [PATCH 2/3] revision.h: introduce blob/tree walking in order of the commits Stefan Beller
2017-10-28 17:20 ` Johannes Schindelin
2017-10-29 3:22 ` Stefan Beller
2017-10-29 3:23 ` Stefan Beller
2017-10-29 3:43 ` Junio C Hamano
2017-10-28 0:45 ` [PATCH 3/3] builtin/describe: describe blobs Stefan Beller
2017-10-28 17:32 ` Johannes Schindelin
2017-10-28 22:47 ` Jacob Keller
2017-10-29 3:28 ` Stefan Beller
2017-10-29 12:02 ` Kevin Daudt
2017-10-29 12:07 ` Johannes Schindelin
2017-10-28 17:15 ` [PATCH 1/3] list-objects.c: factor out traverse_trees_and_blobs Johannes Schindelin
2017-10-29 3:13 ` Stefan Beller
2017-10-28 16:04 ` [RFC PATCH 0/3] git-describe <blob> ? Johannes Schindelin
2017-10-31 0:33 ` [PATCH 0/7] git-describe <blob> Stefan Beller
2017-10-31 0:33 ` [PATCH 1/7] list-objects.c: factor out traverse_trees_and_blobs Stefan Beller
2017-10-31 6:07 ` Junio C Hamano
2017-10-31 0:33 ` [PATCH 2/7] revision.h: introduce blob/tree walking in order of the commits Stefan Beller
2017-10-31 6:57 ` Junio C Hamano
2017-10-31 18:12 ` Stefan Beller
2017-10-31 0:33 ` [PATCH 3/7] builtin/describe.c: rename `oid` to avoid variable shadowing Stefan Beller
2017-10-31 8:15 ` Jacob Keller
2017-10-31 0:33 ` [PATCH 4/7] builtin/describe.c: print debug statements earlier Stefan Beller
2017-10-31 7:03 ` Junio C Hamano
2017-10-31 19:05 ` Stefan Beller
2017-10-31 0:33 ` [PATCH 5/7] builtin/describe.c: factor out describe_commit Stefan Beller
2017-10-31 0:33 ` [PATCH 6/7] builtin/describe.c: describe a blob Stefan Beller
2017-10-31 6:25 ` Junio C Hamano
2017-10-31 19:16 ` Stefan Beller
2017-11-01 3:34 ` Junio C Hamano
2017-11-01 20:58 ` Stefan Beller
2017-11-02 1:53 ` Junio C Hamano
2017-11-02 4:23 ` Junio C Hamano
2017-11-04 21:15 ` Philip Oakley
2017-11-05 6:28 ` Junio C Hamano
2017-11-06 23:50 ` Philip Oakley
2017-11-09 20:30 ` Stefan Beller
2017-11-10 0:25 ` Philip Oakley
2017-11-10 1:24 ` Junio C Hamano
2017-11-10 22:44 ` [PATCH 0/1] describe a blob: with better docs Stefan Beller
2017-11-10 22:44 ` [PATCH] builtin/describe.c: describe a blob Stefan Beller
2017-11-13 1:33 ` Junio C Hamano
2017-11-14 23:37 ` Stefan Beller
2017-11-20 15:22 ` [PATCH 6/7] " Philip Oakley
2017-11-20 18:18 ` Philip Oakley [this message]
2017-11-01 3:44 ` Junio C Hamano
2017-10-31 0:33 ` [PATCH 7/7] t6120: fix typo in test name Stefan Beller
2017-11-01 1:21 ` Junio C Hamano
2017-11-01 18:13 ` Stefan Beller
2017-11-02 1:36 ` Junio C Hamano
2017-10-31 21:18 ` [PATCHv2 0/7] git describe blob Stefan Beller
2017-10-31 21:18 ` [PATCHv2 1/7] list-objects.c: factor out traverse_trees_and_blobs Stefan Beller
2017-11-01 3:46 ` Junio C Hamano
2017-10-31 21:18 ` [PATCHv2 2/7] revision.h: introduce blob/tree walking in order of the commits Stefan Beller
2017-11-01 3:50 ` Junio C Hamano
2017-11-01 12:26 ` Johannes Schindelin
2017-11-01 12:37 ` Junio C Hamano
2017-11-01 19:37 ` Stefan Beller
2017-11-01 22:08 ` Johannes Schindelin
2017-11-01 22:19 ` Stefan Beller
2017-11-01 22:39 ` Johannes Schindelin
2017-11-01 22:46 ` Stefan Beller
2017-11-01 21:36 ` Johannes Schindelin
2017-11-01 21:39 ` Jeff King
2017-11-01 22:33 ` Johannes Schindelin
2017-11-02 1:20 ` Junio C Hamano
2017-10-31 21:18 ` [PATCHv2 3/7] builtin/describe.c: rename `oid` to avoid variable shadowing Stefan Beller
2017-10-31 21:18 ` [PATCHv2 4/7] builtin/describe.c: print debug statements earlier Stefan Beller
2017-10-31 21:31 ` Eric Sunshine
2017-10-31 21:18 ` [PATCHv2 5/7] builtin/describe.c: factor out describe_commit Stefan Beller
2017-10-31 21:18 ` [PATCHv2 6/7] builtin/describe.c: describe a blob Stefan Beller
2017-10-31 21:49 ` Eric Sunshine
2017-11-01 19:51 ` Stefan Beller
2017-11-01 4:11 ` Junio C Hamano
2017-11-01 12:32 ` Johannes Schindelin
2017-11-01 17:59 ` Stefan Beller
2017-11-01 21:05 ` Jacob Keller
2017-11-01 22:12 ` Johannes Schindelin
2017-11-01 22:21 ` Stefan Beller
2017-11-01 22:41 ` Johannes Schindelin
2017-11-01 22:53 ` Stefan Beller
2017-11-02 6:05 ` Jacob Keller
2017-11-03 5:18 ` Junio C Hamano
2017-11-03 6:55 ` Jacob Keller
2017-11-03 15:02 ` Junio C Hamano
2017-11-02 7:23 ` Andreas Schwab
2017-11-02 18:18 ` Stefan Beller
2017-11-03 12:05 ` Johannes Schindelin
2017-11-01 21:28 ` Stefan Beller
2017-10-31 21:18 ` [PATCHv2 7/7] t6120: fix typo in test name Stefan Beller
2017-11-01 5:14 ` [PATCHv2 0/7] git describe blob Junio C Hamano
2017-11-02 19:41 ` [PATCHv3 " Stefan Beller
2017-11-02 19:41 ` [PATCHv3 1/7] t6120: fix typo in test name Stefan Beller
2017-11-02 19:41 ` [PATCHv3 2/7] list-objects.c: factor out traverse_trees_and_blobs Stefan Beller
2017-11-02 19:41 ` [PATCHv3 3/7] revision.h: introduce blob/tree walking in order of the commits Stefan Beller
2017-11-14 19:52 ` Jonathan Tan
2017-11-02 19:41 ` [PATCHv3 4/7] builtin/describe.c: rename `oid` to avoid variable shadowing Stefan Beller
2017-11-02 19:41 ` [PATCHv3 5/7] builtin/describe.c: print debug statements earlier Stefan Beller
2017-11-14 19:55 ` Jonathan Tan
2017-11-14 20:00 ` Stefan Beller
2017-11-02 19:41 ` [PATCHv3 6/7] builtin/describe.c: factor out describe_commit Stefan Beller
2017-11-02 19:41 ` [PATCHv3 7/7] builtin/describe.c: describe a blob Stefan Beller
2017-11-14 20:02 ` Jonathan Tan
2017-11-14 20:40 ` Stefan Beller
2017-11-14 21:17 ` Jonathan Tan
2017-11-03 0:23 ` [PATCHv3 0/7] git describe blob Jacob Keller
2017-11-03 1:46 ` Junio C Hamano
2017-11-03 2:29 ` Stefan Beller
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=B89FAB6895F940EBA45554F20184302F@PhilipOakley \
--to=philipoakley@iee.org \
--cc=Johannes.Schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jacob.keller@gmail.com \
--cc=me@ikke.info \
--cc=sbeller@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).