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.

Since 1.6.5 "git clone" honors the --recursive option to recursively check
out submodules too. As this option can easily be misinterpreted when it is
added to other commands like "git grep", add the new --recurse-submodules
option as an alias for --recursive so the same option can be used for all
commands recursing into submodules.
Signed-off-by: NJens Lehmann <Jens.Lehmann@web.de>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

"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: NMatthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Some people in #linux-rt noticed that describing what "--mirror" option does
with "it mirrors" is way insufficient.

Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: Darren 'Some People' Hart <darren@dvhart.com>
Cc: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: NUwe Kleine-König <u.kleine-koenig@pengutronix.de>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

so that the list of examples is formatted in the same way as for
git-fetch, and, more importantly, the different identation for the
code blocks in the examples (compared to the immediately preceding code
blocks from url.txt) doesn't look like misformatted, but is clarified by
the items' bullets.
Signed-off-by: NMichael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

After 5a518ad4 (clone: use --progress to force progress reporting),
-v/--verbose did not affect whether progress status was reported to
stderr, and users accustomed to using -v to do so since 21188b1e
(Implement git clone -v) may be confused.

Mitigate such risks by stating -v does not affect progress in the
documentation.
Signed-off-by: NTay Ray Chuan <rctay89@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

It is misleading to say that we pull refs from $GIT_DIR/refs/*, because we
may also consult the packed refs mechanism. These days we tend to treat
the "refs hierarchy" as more of an abstract namespace that happens to be
represented as $GIT_DIR/refs. At best, this is a minor inaccuracy, but at
worst it can confuse users who then look in $GIT_DIR/refs and find that it
is missing some of the refs they expected to see.

This patch drops most uses of "$GIT_DIR/refs/*", changing them into just
"refs/*", under the assumption that users can handle the concept of an
abstract refs namespace. There are a few things to note:

  - most cases just dropped the $GIT_DIR/ portion. But for cases where
    that left _just_ the word "refs", I changed it to "refs/" to help
    indicate that it was a hierarchy.  I didn't do the same for longer
    paths (e.g., "refs/heads" remained, instead of becoming
    "refs/heads/").

  - in some cases, no change was made, as the text was explicitly about
    unpacked refs (e.g., the discussion in git-pack-refs).

  - In some cases it made sense instead to note the existence of packed
    refs (e.g., in check-ref-format and rev-parse).
Signed-off-by: NJeff King <peff@peff.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Create a more inoformative section to describe template directory and
refer to it in config.txt and with the '--template' option of git-init
and git-clone commands.
Signed-off-by: NSteven Drake <sdrake@xnet.co.nz>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Follow the argument convention of git-pack-objects, such that a
separate option (--preogress) is used to force progress reporting
instead of -v/--verbose.

-v/--verbose now does not force progress reporting. Make git-clone.txt
say so.

This should cover all the bases in 21188b1e (Implement git clone -v),
which implemented the option to force progress reporting.
Signed-off-by: NTay Ray Chuan <rctay89@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Mention progress reporting behaviour in the descriptions for -q/
--quiet and -v/--verbose options, in the style of git-pack-objects.txt.
Signed-off-by: NTay Ray Chuan <rctay89@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Make transport code (viz. transport.c::fetch_refs_via_pack() and
transport-helper.c::standard_options()) that decides to show progress
check if stderr is a terminal, instead of stdout. After all, progress
reports (via the API in progress.[ch]) are sent to stderr.

Update the documentation for git-clone to say "standard error" as well.
Signed-off-by: NTay Ray Chuan <rctay89@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Document the --branch option as [-b <name>] in git clones synopsis.
Signed-off-by: NDavid Soria Parra <dsp@php.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Add the missing definite article ("the") in several places.

Change "note to..." to "note for...", since "note to" means that
that the note is addressed to someone (source: Google search).

Change "progressbar" to "progress bar" (source: Wikipedia).

Format git commands, options, and file names consistently using
back quotes (i.e. a fixed font in the resulting HTML document).
Signed-off-by: NBjörn Gustavsson <bgustavsson@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

When saying the initial branch is equal to the currently active
remote branch, it is probably intended that the branch heads
point to the same commit.  Maybe it would be more useful to a
new user to emphasize that the tree contents and history are the
same.

More important, probably, is that this new branch is set up so
that "git pull" merges changes from the corresponding remote
branch.  The next paragraph addresses that directly.  What the
reader needs to know to begin with is that (1) the initial branch
is your own; if you do not pull, it won't get updated, and that
(2) the initial branch starts out at the same commit as the
upstream.
Signed-off-by: NJonathan Nieder <jrnieder@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJohannes Gilger <heipei@hackvalue.de>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NMiklos Vajna <vmiklos@frugalware.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

We currently point the HEAD of a newly cloned repo to the
same ref as the parent repo's HEAD. While a user can then
"git checkout -b foo origin/foo" whichever branch they
choose, it is more convenient and more efficient to tell
clone which branch you want in the first place.

Based on a patch by Kirill A. Korinskiy.
Signed-off-by: NJeff King <peff@peff.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Many projects using submodules expect all submodules to be checked out
in order to build/work correctly. A common command sequence for
developers on such projects is:

	git clone url/to/project
	cd project
	git submodule update --init (--recursive)

This patch introduces the --recursive option to git-clone. The new
option causes git-clone to recursively clone and checkout all
submodules of the cloned project. Hence, the above command sequence
can be reduced to:

	git clone --recursive url/to/project

--recursive is ignored if no checkout is done by the git-clone.

The patch also includes documentation and a selftest.
Signed-off-by: NJohan Herland <johan@herland.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The effects of repacking on a repository with alternates are a bit
subtle. The two main things users will want are:

  1. Not to waste disk space by accidentally copying objects which could
     be shared.

  2. Copying all objects explicitly to break the dependency on the source
     repo.

This patch describes both under the "clone -s" documentation. It makes
sense to put it there rather than in git-repack.txt for both cases.

For (1), we are warning the user who is using "clone -s" about what _not_
to do, so we need to get their attention when reading about "clone -s".

For (2), we are telling them how git-repack can be used to accomplish a
task, but until they know that git-repack is the right tool, they have no
reason to look at the repack documentation.
Signed-off-by: NJeff King <peff@peff.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Cloning into an existing empty directory is now allowed:
commit 55892d23
("Allow cloning to an existing empty directory")
Signed-off-by: NAlexander Potashev <aspotashev@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NHolger Weiß <holger@zedat.fu-berlin.de>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The new -v option forces the progressbar, even in case the output
is not a terminal.  This can be useful if the caller is an IDE or
wrapper which wants to scrape the progressbar from stderr and show
its information in a different format.
Signed-off-by: NMiklos Vajna <vmiklos@frugalware.org>
Signed-off-by: NShawn O. Pearce <spearce@spearce.org>

The command line

	$ git clone --mirror $URL

is now a short-hand for

	$ git clone --bare $URL
	$ (cd $(basename $URL) && git remote add --mirror origin $URL)
Signed-off-by: NJohannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

"git clone" no longer calls "git-fetch-pack", so the documentation is a bit
stale. Instead, state that the -u option is to be used when accessing a
repository over ssh.
Signed-off-by: NSteve Haslam <shaslam@lastminute.com>
Signed-off-by: NJunio 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: NJonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: NJunio 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: NJonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: NJunio 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: NJonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: NJunio 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: NChristian Couder <chriscool@tuxfamily.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Since git-gc now always calls prune, even with --auto, unreferenced objects
may be removed by more operations than just git-gc. This is important for
clones created using --shared or --reference.
Signed-off-by: NBrandon Casey <casey@nrlssc.navy.mil>
Signed-off-by: NDmitry Potapov <dpotapov@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

It should be loud and clear.
Signed-off-by: NMiklos Vajna <vmiklos@frugalware.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

There is a scenario when using git clone -s and git gc --prune togother is
dangerous. Document this.
Signed-off-by: NMiklos Vajna <vmiklos@frugalware.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock
Asciidoc configuration:

@@ -149,7 +153,10 @@
 # Inline macros.
 # Backslash prefix required for escape processing.
 # (?s) re flag for line spanning.
-(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
+# Explicit so they can be nested.
+(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
 # Anchor: [[[id]]]. Bibliographic anchor.
 (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3
 # Anchor: [[id,xreflabel]]

This default regex now matches explicit values, and unfortunately in this
case gitlink was being matched by just 'link', causing the wrong inline
macro template to be applied. By renaming the macro, we can avoid being
matched by the wrong regex.
Signed-off-by: NDan McGee <dpmcgee@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NSergei Organov <osv@javad.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NHeikki Orsila <heikki.orsila@iki.fi>

Avoid abbreviation 'revs', improve the language a bit.
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

If we're counting, a smaller number is 'fewer' not 'less'
Signed-off-by: NMike Ralphson <mike@abacus.co.uk>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

This changes the behaviour of cloning from a repository on the
local machine, by defaulting to "-l" (use hardlinks to share
files under .git/objects) and making "-l" a no-op.  A new
option, --no-hardlinks, is also added to cause file-level copy
of files under .git/objects while still avoiding the normal
"pack to pipe, then receive and index pack" network transfer
overhead.  The old behaviour of local cloning without -l nor -s
is availble by specifying the source repository with the newly
introduced file:///path/to/repo.git/ syntax (i.e. "same as
network" cloning).

 * With --no-hardlinks (i.e. have all .git/objects/ copied via
   cpio) would not catch the source repository corruption, and
   also risks corrupted recipient repository if an
   alpha-particle hits memory cell while indexing and resolving
   deltas.  As long as the recipient is created uncorrupted, you
   have a good back-up.

 * same-as-network is expensive, but it would catch the breakage
   of the source repository.  It still risks corrupted recipient
   repository due to hardware failure.  As long as the recipient
   is created uncorrupted, you have a good back-up.

 * The new default on the same filesystem, as long as the source
   repository is healthy, it is very likely that the recipient
   would be, too.  Also it is very cheap.  You do not get any
   back-up benefit, though.

None of the method is resilient against the source repository
corruption, so let's discount that from the comparison.  Then
the difference with and without --no-hardlinks matters primarily
if you value the back-up benefit or not.  If you want to use the
cloned repository as a back-up, then it is cheaper to do a clone
with --no-hardlinks and two git-fsck (source before clone,
recipient after clone) than same-as-network clone, especially as
you are likely to do a git-fsck on the recipient if you are so
paranoid anyway.

Which leads me to believe that being able to use file:/// is
probably a good idea, if only for testability, but probably of
little practical value.  We default to hardlinked clone for
everyday use, and paranoids can use --no-hardlinks as a way to
make a back-up.
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Document that '--message=<msg>' is long version of '-m <msg>' in
git-commit, and that '--no-checkout' is long version of '-n' in
git-clone.
Signed-off-by: NJakub Narebski <jnareb@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Since git-clone is one of the many commands taking
URLs to remote repositories as an argument, it should include
the URL-types list from urls.txt.

Split up urls.txt into urls.txt and urls-remotes.txt.  The latter
should be used by anything besides git-clone where a discussion of
using .git/config and .git/remotes/ to name URLs just doesn't make
as much sense.
Signed-off-by: NAndrew Ruder <andy@aeruder.net>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

In several of the text messages, the tense of the verb is inconsistent.
For example, "Add" vs "Creates".  It is customary to use imperative for
command description.
Signed-off-by: NJunio C Hamano <gitster@pobox.com>