Various commands list refs and allow to use a format string for the
output that interpolates from the ref as well as the object it points
at (for-each-ref; branch and tag in list mode).

Currently, the documentation talks about interpolating from the object.
This is confusing because a ref points to an object but not vice versa,
so the object cannot possible know %(refname), for example. Thus, this is
wrong independent of refs being objects (one day, maybe) or not.

Change the wording to make this clearer (and distinguish it from formats
for the log family).

Signed-off-by: Michael J Gruber <git@grubix.eu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

"git tag/branch/for-each-ref" family of commands long allowed to
filter the refs by "--contains X" (show only the refs that are
descendants of X), "--merged X" (show only the refs that are
ancestors of X), "--no-merged X" (show only the refs that are not
ancestors of X).  One curious omission, "--no-contains X" (show
only the refs that are not descendants of X) has been added to
them.

* ab/ref-filter-no-contains:
  tag: add tests for --with and --without
  ref-filter: reflow recently changed branch/tag/for-each-ref docs
  ref-filter: add --no-contains option to tag/branch/for-each-ref
  tag: change --point-at to default to HEAD
  tag: implicitly supply --list given another list-like option
  tag: change misleading --list <pattern> documentation
  parse-options: add OPT_NONEG to the "contains" option
  tag: add more incompatibles mode tests
  for-each-ref: partly change <object> to <commit> in help
  tag tests: fix a typo in a test description
  tag: remove a TODO item from the test suite
  ref-filter: add test for --contains on a non-commit
  ref-filter: make combining --merged & --no-merged an error
  tag doc: reword --[no-]merged to talk about commits, not tips
  tag doc: split up the --[no-]merged documentation
  tag doc: move the description of --[no-]merged earlier

Doc update.

* ab/branch-list-doc:
  branch doc: update description for `--list`
  branch doc: change `git branch <pattern>` to use `<branchname>`

Reflow the recently changed branch/tag-for-each-ref
documentation. This change shows no changes under --word-diff, except
the innocuous change of moving git-tag.txt's "[--sort=<key>]" around
slightly.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Change the tag, branch & for-each-ref commands to have a --no-contains
option in addition to their longstanding --contains options.

This allows for finding the last-good rollout tag given a known-bad
<commit>. Given a hypothetically bad commit cf5c7253e0, the git
version to revert to can be found with this hacky two-liner:

    (git tag -l 'v[0-9]*'; git tag -l --contains cf5c7253e0 'v[0-9]*') |
        sort | uniq -c | grep -E '^ *1 ' | awk '{print $2}' | tail -n 10

With this new --no-contains option the same can be achieved with:

    git tag -l --no-contains cf5c7253e0 'v[0-9]*' | sort | tail -n 10

As the filtering machinery is shared between the tag, branch &
for-each-ref commands, implement this for those commands too. A
practical use for this with "branch" is e.g. finding branches which
were branched off between v2.8.0 and v2.10.0:

    git branch --contains v2.8.0 --no-contains v2.10.0

The "describe" command also has a --contains option, but its semantics
are unrelated to what tag/branch/for-each-ref use --contains for. A
--no-contains option for "describe" wouldn't make any sense, other
than being exactly equivalent to not supplying --contains at all,
which would be confusing at best.

Add a --without option to "tag" as an alias for --no-contains, for
consistency with --with and --contains.  The --with option is
undocumented, and possibly the only user of it is
Junio (<xmqqefy71iej.fsf@gitster.mtv.corp.google.com>). But it's
trivial to support, so let's do that.

The additions to the the test suite are inverse copies of the
corresponding --contains tests. With this change --no-contains for
tag, branch & for-each-ref is just as well tested as the existing
--contains option.

In addition to those tests, add a test for "tag" which asserts that
--no-contains won't find tree/blob tags, which is slightly
unintuitive, but consistent with how --contains works & is documented.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

The paragraph begins with a sample command line `git branch <name>`
that has nothing to do with the option being described.  Remove it,
but use the space to instead show that multiple patterns can be
given.

Also mention the unfortunate `-l` that can be easily confused with
it.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Reviewed-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Change an example for `git branch <pattern>` to say `git branch
<branchname>` to be consistent with the synopsis. This changes
documentation added in d8d33736b5 ("branch: allow pattern arguments",
2011-08-28).

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Change the behavior of specifying --merged & --no-merged to be an
error, instead of silently picking the option that was provided last.

Subsequent changes of mine add a --no-contains option in addition to
the existing --contains. Providing both of those isn't an error, and
has actual meaning.

Making its cousins have different behavior in this regard would be
confusing to the user, especially since we'd be silently disregarding
some of their command-line input.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

The code to list branches in "git branch" has been consolidated
with the more generic ref-filter API.

* kn/ref-filter-branch-list: (21 commits)
  ref-filter: resurrect "strip" as a synonym to "lstrip"
  branch: implement '--format' option
  branch: use ref-filter printing APIs
  branch, tag: use porcelain output
  ref-filter: allow porcelain to translate messages in the output
  ref-filter: add an 'rstrip=<N>' option to atoms which deal with refnames
  ref-filter: modify the 'lstrip=<N>' option to work with negative '<N>'
  ref-filter: Do not abruptly die when using the 'lstrip=<N>' option
  ref-filter: rename the 'strip' option to 'lstrip'
  ref-filter: make remote_ref_atom_parser() use refname_atom_parser_internal()
  ref-filter: introduce refname_atom_parser()
  ref-filter: introduce refname_atom_parser_internal()
  ref-filter: make "%(symref)" atom work with the ':short' modifier
  ref-filter: add support for %(upstream:track,nobracket)
  ref-filter: make %(upstream:track) prints "[gone]" for invalid upstreams
  ref-filter: introduce format_ref_array_item()
  ref-filter: move get_head_description() from branch.c
  ref-filter: modify "%(objectname:short)" to take length
  ref-filter: implement %(if:equals=<string>) and %(if:notequals=<string>)
  ref-filter: include reference to 'used_atom' within 'atom_value'
  ...

The commands git-branch and git-tag accept the '--create-reflog'
option, and create reflog even when core.logallrefupdates
configuration is explicitly set not to.

On the other hand, the negated form '--no-create-reflog' is accepted
as a valid option but has no effect (other than overriding an
earlier '--create-reflog' on the command line). This silent noop may
puzzle users.  To communicate that this is a known limitation, add a
short note in the manuals for git-branch and git-tag.

Signed-off-by: Cornelius Weig <cornelius.weig@tngtech.com>
Helped-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>