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

Hello,

On Wed, Nov 9, 2016 at 5:28 AM, Jacob Keller [off-list ref] wrote:

On Tue, Nov 8, 2016 at 12:12 PM, Karthik Nayak [off-list ref] wrote:

quoted

From: Karthik Nayak <redacted>
Add tests and documentation for the same.

Signed-off-by: Karthik Nayak <redacted>
---
 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