Hello,
On Wed, Nov 9, 2016 at 5:28 AM, Jacob Keller <jacob.keller@xxxxxxxxx> wrote:
> On Tue, Nov 8, 2016 at 12:12 PM, Karthik Nayak <karthik.188@xxxxxxxxx> wrote:
>> From: Karthik Nayak <karthik.188@xxxxxxxxx>
>> Add tests and documentation for the same.
>>
>> Signed-off-by: Karthik Nayak <Karthik.188@xxxxxxxxx>
>> ---
>> 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