Re: [PATCH v7 13/17] ref-filter: add `:dir` and `:base` options for ref printing atoms

[Karthik Nayak <karthik.188@gmail.com>]

Hello,

On Wed, Nov 9, 2016 at 5:28 AM, Jacob Keller <jacob.keller@gmail.com> wrote:
> On Tue, Nov 8, 2016 at 12:12 PM, Karthik Nayak <karthik.188@gmail.com> wrote:
>> From: Karthik Nayak <karthik.188@gmail.com>
>> Add tests and documentation for the same.
>>
>> Signed-off-by: Karthik Nayak <Karthik.188@gmail.com>
>> ---
>>  Documentation/git-for-each-ref.txt | 34 +++++++++++++++++++---------------
>>  ref-filter.c                       | 29 +++++++++++++++++++++++++----
>>  t/t6300-for-each-ref.sh            | 24 ++++++++++++++++++++++++
>>  3 files changed, 68 insertions(+), 19 deletions(-)
>>
>> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
>> index 600b703..f4ad297 100644
>> --- a/Documentation/git-for-each-ref.txt
>> +++ b/Documentation/git-for-each-ref.txt
>> @@ -96,7 +96,9 @@ refname::
>>         slash-separated path components from the front of the refname
>>         (e.g., `%(refname:strip=2)` turns `refs/tags/foo` into `foo`.
>>         `<N>` must be a positive integer.  If a displayed ref has fewer
>> -       components than `<N>`, the command aborts with an error.
>> +       components than `<N>`, the command aborts with an error. For the base
>> +       directory of the ref (i.e. foo in refs/foo/bar/boz) append
>> +       `:base`. For the entire directory path append `:dir`.
>>
>>  objecttype::
>>         The type of the object (`blob`, `tree`, `commit`, `tag`).
>> @@ -114,22 +116,23 @@ objectname::
>>
>>  upstream::
>>         The name of a local ref which can be considered ``upstream''
>> -       from the displayed ref. Respects `:short` and `:strip` in the
>> -       same way as `refname` above.  Additionally respects `:track`
>> -       to show "[ahead N, behind M]" and `:trackshort` to show the
>> -       terse version: ">" (ahead), "<" (behind), "<>" (ahead and
>> -       behind), or "=" (in sync). `:track` also prints "[gone]"
>> -       whenever unknown upstream ref is encountered. Append
>> -       `:track,nobracket` to show tracking information without
>> -       brackets (i.e "ahead N, behind M").  Has no effect if the ref
>> -       does not have tracking information associated with it.
>> +       from the displayed ref. Respects `:short`, `:strip`, `:base`
>> +       and `:dir` in the same way as `refname` above.  Additionally
>> +       respects `:track` to show "[ahead N, behind M]" and
>> +       `:trackshort` to show the terse version: ">" (ahead), "<"
>> +       (behind), "<>" (ahead and behind), or "=" (in sync). `:track`
>> +       also prints "[gone]" whenever unknown upstream ref is
>> +       encountered. Append `:track,nobracket` to show tracking
>> +       information without brackets (i.e "ahead N, behind M").  Has
>> +       no effect if the ref does not have tracking information
>> +       associated with it.
>>
>>  push::
>>         The name of a local ref which represents the `@{push}`
>>         location for the displayed ref. Respects `:short`, `:strip`,
>> -       `:track`, and `:trackshort` options as `upstream`
>> -       does. Produces an empty string if no `@{push}` ref is
>> -       configured.
>> +       `:track`, `:trackshort`, `:base` and `:dir` options as
>> +       `upstream` does. Produces an empty string if no `@{push}` ref
>> +       is configured.
>>
>
> At this point would it make more sense to document the extra values
> here in one block separately? For example, the upstream atom is
> getting pretty complex with all those options. Additionally, some of
> the options can be combined, like nobracket, but others cannot be
> comined so It may be worth documenting how and when those combinations
> work?
>

I do agree. The documentation seems cluttered. It'd be nice to clean
it up. Maybe
after this series? Or any suggestions on how to go about it?

-- 
Regards,
Karthik Nayak