There are a handful of incorrect "linkgit:<page>[<section>]"
instances in our documentation set.
* Some have an extra colon after "linkgit:"; fix them by removing
the extra colon;
* Some refer to a page outside the Git suite, namely curl(1); fix
them by using the `curl(1)` that already appears on the same page
for the same purpose of referring the readers to its manual page.
* Some spell the name of the page incorrectly, e.g. "rev-list" when
they mean "git-rev-list"; fix them.
* Some list the manual section incorrectly; fix them to make sure
they match what is at the top of the target of the link.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
'git for-each-ref's manpage says that '--contains' only lists tags,
but it lists all kinds of refs.
Signed-off-by: SZEDER Gábor <szeder@ira.uka.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The ref-filter's format-parsing code has been refactored, in
preparation for "branch --format" and friends.
* kn/ref-filter-atom-parsing:
ref-filter: introduce objectname_atom_parser()
ref-filter: introduce contents_atom_parser()
ref-filter: introduce remote_ref_atom_parser()
ref-filter: align: introduce long-form syntax
ref-filter: introduce align_atom_parser()
ref-filter: introduce parse_align_position()
ref-filter: introduce color_atom_parser()
ref-filter: introduce parsing functions for each valid atom
ref-filter: introduce struct used_atom
ref-filter: bump 'used_atom' and related code to the top
ref-filter: use string_list_split over strbuf_split
Introduce optional prefixes "width=" and "position=" for the align atom
so that the atom can be used as "%(align:width=<width>,position=<position>)".
Add Documentation and tests for the same.
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Karthik Nayak <Karthik.188@gmail.com>
Reviewed-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git tag" started listing a tag "foo" as "tags/foo" when a branch
named "foo" exists in the same repository; remove this unnecessary
disambiguation, which is a regression introduced in v2.7.0.
* jk/list-tag-2.7-regression:
tag: do not show ambiguous tag names as "tags/foo"
t6300: use test_atom for some un-modern tests
Since b7cc53e9 (tag.c: use 'ref-filter' APIs, 2015-07-11),
git-tag has started showing tags with ambiguous names (i.e.,
when both "heads/foo" and "tags/foo" exists) as "tags/foo"
instead of just "foo". This is both:
- pointless; the output of "git tag" includes only
refs/tags, so we know that "foo" means the one in
"refs/tags".
and
- ambiguous; in the original output, we know that the line
"foo" means that "refs/tags/foo" exists. In the new
output, it is unclear whether we mean "refs/tags/foo" or
"refs/tags/tags/foo".
The reason this happens is that commit b7cc53e9 switched
git-tag to use ref-filter's "%(refname:short)" output
formatting, which was adapted from for-each-ref. This more
general code does not know that we care only about tags, and
uses shorten_unambiguous_ref to get the short-name. We need
to tell it that we care only about "refs/tags/", and it
should shorten with respect to that value.
In theory, the ref-filter code could figure this out by us
passing FILTER_REFS_TAGS. But there are two complications
there:
1. The handling of refname:short is deep in formatting
code that does not even have our ref_filter struct, let
alone the arguments to the filter_ref struct.
2. In git v2.7.0, we expose the formatting language to the
user. If we follow this path, it will mean that
"%(refname:short)" behaves differently for "tag" versus
"for-each-ref" (including "for-each-ref refs/tags/"),
which can lead to confusion.
Instead, let's add a new modifier to the formatting
language, "strip", to remove a specific set of prefix
components. This fixes "git tag", and lets users invoke the
same behavior from their own custom formats (for "tag" or
"for-each-ref") while leaving ":short" with its same
consistent meaning in all places.
We introduce a test in t7004 for "git tag", which fails
without this patch. We also add a similar test in t3203 for
"git branch", which does not actually fail. But since it is
likely that "branch" will eventually use the same formatting
code, the test helps defend against future regressions.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
These were introduced back in 2006 at 3175aa1ec2 but
never documented.
Signed-off-by: Eric Wong <normalperson@yhbt.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The "ref-filter" code was taught about many parts of what "tag -l"
does and then "tag -l" is being reimplemented in terms of "ref-filter".
* kn/for-each-tag:
tag.c: implement '--merged' and '--no-merged' options
tag.c: implement '--format' option
tag.c: use 'ref-filter' APIs
tag.c: use 'ref-filter' data structures
ref-filter: add option to match literal pattern
ref-filter: add support to sort by version
ref-filter: add support for %(contents:lines=X)
ref-filter: add option to filter out tags, branches and remotes
ref-filter: implement an `align` atom
ref-filter: introduce match_atom_name()
ref-filter: introduce handler function for each atom
utf8: add function to align a string into given strbuf
ref-filter: introduce ref_formatting_state and ref_formatting_stack
ref-filter: move `struct atom_value` to ref-filter.c
strtoul_ui: reject negative values
"git log --date=local" used to only show the normal (default)
format in the local timezone. The command learned to take 'local'
as an instruction to use the local timezone with other formats,
e.g. "git show --date=rfc-local".
* jk/date-local:
t6300: add tests for "-local" date formats
t6300: make UTC and local dates different
date: make "local" orthogonal to date format
date: check for "local" before anything else
t6300: add test for "raw" date format
t6300: introduce test_date() helper
fast-import: switch crash-report date to iso8601
Documentation/rev-list: don't list date formats
Documentation/git-for-each-ref: don't list date formats
Documentation/config: don't list date formats
Documentation/blame-options: don't list date formats
Add support to sort by version using the "v:refname" and
"version:refname" option. This is achieved by using the 'versioncmp()'
function as the comparing function for qsort.
This option is included to support sorting by versions in `git tag -l`
which will eventually be ported to use ref-filter APIs.
Add documentation and tests for the same.
Mentored-by: Christian Couder <christian.couder@gmail.com>
Mentored-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In 'tag.c' we can print N lines from the annotation of the tag using
the '-n<num>' option. Copy code from 'tag.c' to 'ref-filter' and
modify it to support appending of N lines from the annotation of tags
to the given strbuf.
Implement %(contents:lines=X) where X lines of the given object are
obtained.
While we're at it, remove unused "contents:<suboption>" atoms from
the `valid_atom` array.
Add documentation and test for the same.
Mentored-by: Christian Couder <christian.couder@gmail.com>
Mentored-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Implement an `align` atom which left-, middle-, or right-aligns the
content between %(align:...) and %(end).
The "align:" is followed by `<width>` and `<position>` in any order
separated by a comma, where the `<position>` is either left, right or
middle, default being left and `<width>` is the total length of the
content with alignment. If the contents length is more than the width
then no alignment is performed. e.g. to align a refname atom to the
middle with a total width of 40 we can do:
--format="%(align:middle,40)%(refname)%(end)".
We introduce an `at_end` function for each element of the stack which
is to be called when the `end` atom is encountered. Using this we
implement end_align_handler() for the `align` atom, this aligns the
final strbuf by calling `strbuf_utf8_align()` from utf8.c.
Ensure that quote formatting is performed on the whole of
%(align:...)...%(end) rather than individual atoms inside. We skip
quote formatting for individual atoms when the current stack element
is handling an %(align:...) atom and perform quote formatting at the
end when we encounter the %(end) atom of the second element of then
stack.
Add documentation and tests for the same.
Mentored-by: Christian Couder <christian.couder@gmail.com>
Mentored-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We are about to add a new set of supported date formats and do not want
to have to maintain the same list in several different bits of
documentation. Refer to git-rev-list(1) which contains the full list of
supported formats.
Signed-off-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add the '--contains' option provided by 'ref-filter'. The '--contains'
option lists only refs which contain the mentioned commit (HEAD if no
commit is explicitly given).
Add documentation and tests for the same.
Mentored-by: Christian Couder <christian.couder@gmail.com>
Mentored-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add the '--merged' and '--no-merged' options provided by 'ref-filter'.
The '--merged' option lets the user to only list refs merged into the
named commit. The '--no-merged' option lets the user to only list refs
not merged into the named commit.
Add documentation and tests for the same.
Based-on-patch-by: Jeff King <peff@peff.net>
Mentored-by: Christian Couder <christian.couder@gmail.com>
Mentored-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add the '--points-at' option provided by 'ref-filter'. The
option lets the user to list only refs which points at the
given object.
Add documentation and tests for the same.
Based-on-patch-by: Jeff King <peff@peff.net>
Mentored-by: Christian Couder <christian.couder@gmail.com>
Mentored-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Just as we have "%(upstream)" to report the "@{upstream}"
for each ref, this patch adds "%(push)" to match "@{push}".
It supports the same tracking format modifiers as upstream
(because you may want to know, for example, which branches
have commits to push).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We decided at 48bb914e (doc: drop author/documentation sections from
most pages, 2011-03-11) to remove "author" and "documentation"
sections from our documentation. Remove a few stragglers.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add cross-references between the manpages for git-for-each-ref(1) and
git-show-ref(1).
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Enhance 'git for-each-ref' with color formatting options. You can now
use the following format in for-each-ref:
%(color:green)%(refname:short)%(color:reset)
where color names are described in color.branch.*.
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Introduce %(upstream:track) to display "[ahead M, behind N]" and
%(upstream:trackshort) to display "=", ">", "<", or "<>"
appropriately (inspired by contrib/completion/git-prompt.sh).
Now you can use the following format in for-each-ref:
%(refname:short)%(upstream:trackshort)
to display refs with terse tracking information.
Note that :track and :trackshort only work with "upstream", and error
out when used with anything else.
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
'git branch' shows which branch you are currently on with an '*', but
'git for-each-ref' misses this feature. So, extend its format with
%(HEAD) for the same effect.
Now you can use the following format in for-each-ref:
%(HEAD) %(refname:short)
to display an asterisk next to the current ref.
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Commit 7dff9b3 (Support 'raw' date format) added a raw date format.
Update the git-for-each-ref documentation to include this.
Signed-off-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The discussion of email subject throughout the documentation is
misleading; it indicates that the first line will always become
the subject. In fact, the subject is generally all lines up until
the first full blank line.
This patch refines that, and makes more use of the concept of a
commit title, with the title being all text up to the first blank line.
Signed-off-by: Jeremy White <jwhite@codeweavers.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The %(body) placeholder returns the whole body of a tag or
commit, including the signature. However, callers may want
to get just the body without signature, or just the
signature.
Rather than change the meaning of %(body), which might break
some scripts, this patch introduces a new set of
placeholders which break down the %(contents) placeholder
into its constituent parts.
[jk: initial patch by mg, rebased on top of my refactoring
and with tests by me]
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Remove some stray usage of other bracket types and asterisks for the
same purpose.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Acked-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
For some reason, various manual pages have an asterisk escaped
with \ in the synopsis. Since there is no other asterisk to pair it
with, Asciidoc does not consider this asterisk escapable, so it passes
the backslash through.
Each page either uses [verse] or has only one asterisk, so it
is safe to drop the backslashes (checked with asciidoc 8.5.2).
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Introduce a :short modifier to objectname which outputs the abbreviated
object name.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Reviewed-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation was quite inconsistent when spelling 'git cmd' if it
only refers to the program, not to some specific invocation syntax:
both 'git-cmd' and 'git cmd' spellings exist.
The current trend goes towards dashless forms, and there is precedent
in 647ac70 (git-svn.txt: stop using dash-form of commands.,
2009-07-07) to actively eliminate the dashed variants.
Replace 'git-cmd' with 'git cmd' throughout, except where git-shell,
git-cvsserver, git-upload-pack, git-receive-pack, and
git-upload-archive are concerned, because those really live in the
$PATH.
core.warnAmbiguousRefs is used to select strict mode for the
abbreviation for the ":short" format specifier of "refname" and "upstream".
In strict mode, the abbreviated ref will never trigger the
'warn_ambiguous_refs' warning. I.e. for these refs:
refs/heads/xyzzy
refs/tags/xyzzy
the abbreviated forms are:
heads/xyzzy
tags/xyzzy
Signed-off-by: Bert Wesarg <bert.wesarg@googlemail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The logic for determining the upstream ref of a branch is
somewhat complex to perform in a shell script. This patch
provides a plumbing mechanism for scripts to access the C
logic used internally by git-status, git-branch, etc.
For example:
$ git for-each-ref \
--format='%(refname:short) %(upstream:short)' \
refs/heads/
master origin/master
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Tries to shorten the refname to a non-ambiguous name.
Szeder Gábor noticed that the git bash completion takes a
tremendous amount of time to strip leading components from
heads and tags refs (i.e. refs/heads, refs/tags, ...). He
proposed a new atom called 'refbasename' which removes at
most two leading components from the ref name.
I myself, proposed a more dynamic solution, which strips off
common leading components with the matched pattern.
But the current bash solution and both proposals suffer from
one mayor problem: ambiguous refs.
A ref is ambiguous, if it resolves to more than one full refs.
I.e. given the refs refs/heads/xyzzy and refs/tags/xyzzy. The
(short) ref xyzzy can point to both refs.
( Note: Its irrelevant whether the referenced objects are the
same or not. )
This proposal solves this by checking for ambiguity of the
shorten ref name.
The shortening is done with the same rules for resolving refs
but in the reverse order. The short name is checked if it
resolves to a different ref.
To continue the above example, the output would be like this:
heads/xyzzy
xyzzy
So, if you want just tags, xyzzy is not ambiguous, because it
will resolve to a tag. If you need the heads you get a also
a non-ambiguous short form of the ref.
To integrate this new format into the bash completion to get
only non-ambiguous refs is beyond the scope of this patch.
Signed-off-by: Bert Wesarg <bert.wesarg@googlemail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When the SYNOPSIS says e.g. "<path>...", it is nice if the DESCRIPTION
also mentions "<path>..." and says the specified "paths" (note plural)
are used for $whatever. This fixes the obvious mismatches.
Signed-off-by: Abhijit Menon-Sen <ams@toroid.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The names of git commands are not meant to be entered at the
commandline; they are just names. So we render them in italics,
as is usual for command names in manpages.
Using
doit () {
perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }'
}
for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \
merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt
do
doit <"$i" >"$i+" && mv "$i+" "$i"
done
git diff
.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since the git-* commands are not installed in $(bindir), using
"git-command <parameters>" in examples in the documentation is
not a good idea. On the other hand, it is nice to be able to
refer to each command using one hyphenated word. (There is no
escaping it, anyway: man page names cannot have spaces in them.)
This patch retains the dash in naming an operation, command,
program, process, or action. Complete command lines that can
be entered at a shell (i.e., without options omitted) are
made to use the dashless form.
The changes consist only of replacing some spaces with hyphens
and vice versa. After a "s/ /-/g", the unpatched and patched
versions are identical.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The OPTIONS section of a documentation file contains a list
of the options a git command accepts.
Currently there are several variants to describe the case that
different options (almost) do the same in the OPTIONS section.
Some are:
-f, --foo::
-f|--foo::
-f | --foo::
But AsciiDoc has the special form:
-f::
--foo::
This patch applies this form to the documentation of the whole git suite,
and removes useless em-dash prevention, so \--foo becomes --foo.
Signed-off-by: Stephan Beyer <s-beyer@gmx.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Rewrapped synopsis and removed wrong asterisk behind --count option;
clarified --sort=<key> description for multiple keys; documented that
for-each-ref supports not only glob patterns but also prefixes like
"refs/heads" as patterns, and that multiple patterns can be given.
Signed-off-by: Lea Wiemann <LeWiemann@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
grab_date() gets an extra parameter - atomname; this extra parameter is
checked to see if it has a ":<format>" extra component in it, and if so
that "<format>" string is passed to parse_date_format() to produce an
enum date_mode value which is then further passed to show_date().
In short it allows the user of git-for-each-ref to do things like this:
$ git-for-each-ref --format='%(taggerdate:default)' refs/tags/v1.5.2
Sun May 20 00:30:42 2007 -0700
$ git-for-each-ref --format='%(taggerdate:relative)' refs/tags/v1.5.2
4 months ago
$ git-for-each-ref --format='%(taggerdate:short)' refs/tags/v1.5.2
2007-05-20
$ git-for-each-ref --format='%(taggerdate:local)' refs/tags/v1.5.2
Sun May 20 08:30:42 2007
$ git-for-each-ref --format='%(taggerdate:iso8601)' refs/tags/v1.5.2
2007-05-20 00:30:42 -0700
$ git-for-each-ref --format='%(taggerdate:rfc2822)' refs/tags/v1.5.2
Sun, 20 May 2007 00:30:42 -0700
The default, when no ":<format>" is specified is ":default", leaving the
existing behaviour unchanged.
Signed-off-by: Andy Parkins <andyparkins@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for git-for-each-ref said that the refname variable
would return "the part after $GIT_DIR/refs/", which isn't true.
Signed-off-by: Andy Parkins <andyparkins@gmail.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Love it or hate it, some people actually still program in Tcl. Some
of those programs are meant for interfacing with Git. Programs such as
gitk and git-gui. It may be useful to have Tcl-safe output available
from for-each-ref, just like shell, Perl and Python already enjoy.
Thanks to Sergey Vlasov for pointing out the horrible flaws in the
first and second version of this patch, and steering me in the right
direction for Tcl value quoting.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <junkio@cox.net>
Two asterisks the SYNOPSIS section were mistaken as emphasis,
and the latter backtick in "`<key>`s" were not recognized as
closing backtick.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Update information about value of <format> used when it is left
unspecified. Add information about `%%` and `%xx` interpolation
(URL encoding).
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
