Various documentation fixups.
* po/maint-docs:
Doc branch: show -vv option and alternative
Doc clean: add See Also link
Doc add: link gitignore
Doc: separate gitignore pattern sources
Doc: shallow clone deepens _to_ new depth
Indicate that the -v option can be given twice in the short options.
Without it users pass over the option. Also indicate the alternate
'git remote show' method.
Signed-off-by: Philip Oakley <philipoakley@iee.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We have ways of setting the upstream information, but if we want to
unset it, we need to resort to modifying the configuration manually.
Teach branch an --unset-upstream option that unsets this information.
Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The existing --set-uptream option can cause confusion, as it uses the
usual branch convention of assuming a starting point of HEAD if none
is specified, causing
git branch --set-upstream origin/master
to create a new local branch 'origin/master' that tracks the current
branch. As --set-upstream already exists, we can't simply change its
behaviour. To work around this, introduce --set-upstream-to which
accepts a compulsory argument indicating what the new upstream branch
should be and one optinal argument indicating which branch to change,
defaulting to HEAD.
The new options allows us to type
git branch --set-upstream-to origin/master
to set the current branch's upstream to be origin's master.
Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
A couple of commands learn --column option to produce columnar output.
By Nguyễn Thái Ngọc Duy (9) and Zbigniew Jędrzejewski-Szmek (1)
* nd/columns:
tag: add --column
column: support piping stdout to external git-column process
status: add --column
branch: add --column
help: reuse print_columns() for help -a
column: add dense layout support
t9002: work around shells that are unable to set COLUMNS to 1
column: add columnar layout
Stop starting pager recursively
Add column layout skeleton and git-column
Even with "-q"uiet option, "checkout" used to report setting up tracking.
Also "branch" learns "-q"uiet option to squelch informational message.
By Jeff King
* jk/branch-quiet:
teach "git branch" a --quiet option
checkout: suppress tracking message with "-q"
There's currently no way to suppress the informational
"deleted branch..." or "set up tracking..." messages. This
patch provides a "-q" option to do so.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Indicate that the commit parameter of --contains defaults to HEAD.
Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Most of the exact option strings to be typed by end users are
already set in typewriter font by using `--option`, but a few places
used '--option' to call for italics or with no quoting. Uniformly
use `--option`.
Also add a full-stop after a sentence that missed one.
Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* jc/request-pull-show-head-4:
request-pull: use the annotated tag contents
fmt-merge-msg.c: Fix an "dubious one-bit signed bitfield" sparse error
environment.c: Fix an sparse "symbol not declared" warning
builtin/log.c: Fix an "Using plain integer as NULL pointer" warning
fmt-merge-msg: use branch.$name.description
request-pull: use the branch description
request-pull: state what commit to expect
request-pull: modernize style
branch: teach --edit-description option
format-patch: use branch description in cover letter
branch: add read_branch_desc() helper function
Conflicts:
builtin/branch.c
Using branch.$name.description as the configuration key, give users a
place to write about what the purpose of the branch is and things like
that, so that various subsystems, e.g. "push -s", "request-pull", and
"format-patch --cover-letter", can later be taught to use this
information.
The "-m" option similar to "commit/tag" is deliberately omitted, as the
whole point of branch description is about giving descriptive information
(the name of the branch itself is a better place for information that fits
on a single-line).
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"branch -v" without other options or parameters still works in the list
mode, but that is not because there is "-v" but because there is no
parameter nor option.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Allow pattern arguments for the list mode just like for git tag -l.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Currently, there is no way to invoke the list mode explicitly, without
giving -v to force verbose output.
Introduce a --list option which invokes the list mode. This will be
beneficial for invoking list mode with pattern matching, which otherwise
would be interpreted as branch creation.
Along with --list, test also combinations of existing options.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Long forms are better to memorize and more reliably uniform across
commands.
Names follow precedents, e.g. "git log --remotes".
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Use the value from 'core.abbrev' configuration variable unless user
specifies the length on command line when showing commit object name
in "branch -v" output.
Signed-off-by: Namhyung Kim <namhyung@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The point of these sections is generally to:
1. Give credit where it is due.
2. Give the reader an idea of where to ask questions or
file bug reports.
But they don't do a good job of either case. For (1), they
are out of date and incomplete. A much more accurate answer
can be gotten through shortlog or blame. For (2), the
correct contact point is generally git@vger, and even if you
wanted to cc the contact point, the out-of-date and
incomplete fields mean you're likely sending to somebody
useless.
So let's drop the fields entirely from all manpages except
git(1) itself. We already point people to the mailing list
for bug reports there, and we can update the Authors section
to give credit to the major contributors and point to
shortlog and blame for more information.
Each page has a "This is part of git" footer, so people can
follow that to the main git manpage.
"remote branch" is a branch hosted in a remote repository, while
"remote-tracking branch" is a copy of such branch, hosted locally.
The distinction is subtle when the copy is up-to-date, but rather
fundamental to understand what "git fetch" and "git push" do.
This patch should fix all incorrect usages in Documentation/ directory.
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint:
t1010-mktree: Adjust expected result to code and documentation
combined diff: correctly handle truncated file
Document new "already-merged" rule for branch -d
v1.7.0-rc0~18^2 (branch -d: base the "already-merged" safety on the
branch it merges with, 2009-12-29) taught ‘git branch’ a new heuristic
for when it is safe to delete a branch without forcing the issue. It
is safe to delete a branch "topic" without second thought if:
- the branch "topic" is set up to pull from a (remote-tracking,
usually) branch and is fully merged in that "upstream" branch, or
- there is no branch.topic.merge configuration and branch "topic" is
fully merged in the current HEAD.
Update the man page to acknowledge the new rules.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This option is mostly useless these days because we turn on
reflogs by default in non-bare repos.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Make git-branch, git-show-branch, git-grep, and all the diff-based
programs accept an optional argument <when> for --color. The argument
is a colorbool: "always", "never", or "auto". If no argument is given,
"always" is used; --no-color is an alias for --color=never. This makes
the command-line interface consistent with other GNU tools, such as `ls'
and `grep', and with the git-config color options. Note that, without
an argument, --color and --no-color work exactly as before.
To implement this, two internal changes were made:
1. Allow the first argument of git_config_colorbool() to be NULL,
in which case it returns -1 if the argument isn't "always", "never",
or "auto".
2. Add OPT_COLOR_FLAG(), OPT__COLOR(), and parse_opt_color_flag_cb()
to the option parsing library. The callback uses
git_config_colorbool(), so color.h is now a dependency
of parse-options.c.
Signed-off-by: Mark Lodato <lodatom@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add --set-upstream option to branch that works like --track, except that
when branch exists already, its upstream info is changed without changing
the ref value.
Based-on-patch-from: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Ilari Liusvaara <ilari.liusvaara@elisanet.fi>
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.
The documentation seems to assume that the starting point for a new
branch is the tip of an existing (ordinary) branch, but that is not
the most common case. More often, "git branch" is used to begin
a branch from a remote-tracking branch, a tag, or an interesting
commit (e.g. origin/pu^2). Clarify the language so it can apply
to these cases. Thanks to Sean Estabrooks for the wording.
Also add a pointer to the user's manual for the bewildered.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Update the documentation for --merged and --no-merged to explain
the meaning of the optional parameter introduced in commit 049716b
(branch --merged/--no-merged: allow specifying arbitrary commit,
2008-07-08).
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git branch, checkout, clean, mv and tag all have an option -f to override
certain checks. This patch makes them accept the long option --force as
a synonym.
While we're at it, document that checkout support --quiet as synonym for
its short option -q.
Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Change the <name> placeholder to <tagname> in the SYNOPSIS section of
git-tag documentation, and describe it in the OPTIONS section in a way
similar to how documentation for git-branch does.
Add SEE ALSO section to list the other documentation pages these two pages
refer to.
Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The term "tracking" often creates confusion between remote
tracking branches and local branches which track a remote
branch. The term "upstream" captures more clearly the idea
of "branch A is based on branch B in some way", so it makes
sense to mention it.
At the same time, upstream branches are used for more
than just git-pull these days; let's mention that here.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It is not really about ignoring the config option; it is
about turning off tracking, _even if_ the config option is
set.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This information is easily accessible when we are
calculating the relationship. The only reason not to print
it all the time is that it consumes a fair bit of screen
space, and may not be of interest to the user.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* dm/maint-docco:
Documentation: reword example text in git-bisect.txt.
Documentation: reworded the "Description" section of git-bisect.txt.
Documentation: minor grammatical fixes in git-branch.txt.
Documentation: minor grammatical fixes in git-blame.txt.
Documentation: reword the "Description" section of git-bisect.txt.
Documentation: minor grammatical fixes in git-archive.txt.
'git branch -f a b' resets a to b when a exists, rather then deleting a.
Say so in the documentation.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git-branch --merged" is a handy way to list all the branches that have
already been merged to the current branch, but it did not allow checking
against anything but the current branch. Having to switch branches only
to list the branches that are merged with another branch made the feature
practically useless.
This updates the option parser so that "git branch --merged next" is
accepted when you are on 'master' branch.
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>
Following what appears to be the predominant style, format
names of commands and commandlines both as `teletype text`.
While we're at it, add articles ("a" and "the") in some
places, italicize the name of the command in the manual page
synopsis line, and add a comma or two where it seems appropriate.
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>
As the "git" man page describes the "git" command at the end-user
level, it seems better to move it to man section 1.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
