Documentation for "git fetch --depth" has been updated for clarity.
* ss/clone-depth-single-doc:
docs: clarify that --depth for git-fetch works with newly initialized repos
docs: say "commits" in the --depth option wording for git-clone
docs: clarify that passing --depth to git-clone implies --single-branch
It is not wrong to talk about "revisions" here, but in this context
revisions are always commits, and that is how we already name it in the
git-fetch docs. So align the docs by always referring to "commits".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It is confusing to document how --depth behaves as part of the
--single-branch docs. Better move that part to the --depth docs, saying
that it implies --single-branch by default.
Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The "--reference" option is not the only way to provide a repository
to borrow objects from. A repository that borrows from another
repository can be cloned with "clone --local" and the resulting
repository will borrow from the same repository, which the user
may want to "--dissociate" from.
Signed-off-by: Alex Riesen <raa.lkml@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
While use of the --reference option to borrow objects from an
existing local repository of the same project is an effective way to
reduce traffic when cloning a project over the network, it makes the
resulting "borrowing" repository dependent on the "borrowed"
repository. After running
git clone --reference=P $URL Q
the resulting repository Q will be broken if the borrowed repository
P disappears.
The way to allow the borrowed repository to be removed is to repack
the borrowing repository (i.e. run "git repack -a -d" in Q); while
power users may know it very well, it is not easily discoverable.
Teach a new "--dissociate" option to "git clone" to run this
repacking for the user.
Helped-by: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Current text claims optimization, implying the use of
hardlinks, when this option ratchets down the level of
efficiency. This change explains the difference made by
using this option, namely copying instead of hardlinking,
and why it may be useful.
Signed-off-by: Albert L. Lash, IV <alash3@bloomberg.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Now that git supports data transfer from or to a shallow clone, these
limitations are not true anymore.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This reverts commit dacd2bcc41.
"It fails reliably without corrupting the receiving repository when
it should fail" may be better than the situation before the receiving
end was hardened recently, but the fact that sometimes the push does
not go through still remains. It is better to advice the users that
they cannot push from a shallow repository as a limitation before
they decide to use (or not to use) a shallow clone.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The document says one cannot push from a shallow clone. But that is
not true (maybe it was at some point in the past). The client does not
stop such a push nor does it give any indication to the receiver that
this is a shallow push. If the receiver accepts it, it's in.
Since 52fed6e (receive-pack: check connectivity before concluding "git
push" - 2011-09-02), receive-pack is prepared to deal with broken
push, a shallow push can't cause any corruption. Update the document
to reflect that.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The 3.x tree has been out for a while now. The -2.6 repository name
survived the initial release [1], but kernel.org now only lists
'linux.git' (for aegl as well as torvalds) [2].
[1]: http://article.gmane.org/gmane.linux.kernel/1147422
On 2011-05-30 01:47:57 GMT, Linus Torvalds wrote:
> ... yes, that means that my git tree is still called
> "linux-2.6.git" on kernel.org.
[2]: http://git.kernel.org/cgit/
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
There may be times when using one of your local repositories as a
reference for a new clone make sense, but the implied version-bump in
the old example isn't one of them. I think a more intuitive example
is multi-user system with a central reference clone, and the new paths
hint at this use case.
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
There are other examples in git-clone.txt demonstrating both '--bare'
and '-l -s'.
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
White-spaces, missing braces, standardize --[no-]foo.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In the earlier days, we used to spell the name of the system as GIT,
to simulate as if it were typeset with capital G and IT in small
caps. Later we stopped doing so at around 1.6.5 days.
Let's stop doing so throughout the documentation. The name to refer
to the whole system (and the concept it embodies) is "Git"; the
command end-users type is "git". And document this in the coding
guideline.
Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This change was already done by 0e615b252f (Matthieu Moy, Tue Nov 2
2010, Replace "remote tracking" with "remote-tracking"), but new
instances of remote tracking (without dash) were introduced in the
meantime.
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Jeff King <peff@peff.net>
A repository created with "git clone --single" had its fetch
refspecs set up just like a clone without "--single", leading the
subsequent "git fetch" to slurp all the other branches, defeating
the whole point of specifying "only this branch".
* rt/maint-clone-single:
clone --single: limit the fetch refspec to fetched branch
After running "git clone --single", the resulting repository has the
usual default "+refs/heads/*:refs/remotes/origin/*" wildcard fetch
refspec installed, which means that a subsequent "git fetch" will
end up grabbing all the other branches.
Update the fetch refspec to cover only the singly cloned ref instead
to correct this.
That means:
If "--single" is used without "--branch" or "--mirror", the
fetch refspec covers the branch on which remote's HEAD points to.
If "--single" is used with "--branch", it'll cover only the branch
specified in the "--branch" option.
If "--single" is combined with "--mirror", then it'll cover all
refs of the cloned repository.
If "--single" is used with "--branch" that specifies a tag, then
it'll cover only the ref for this tag.
Signed-off-by: Ralf Thielow <ralf.thielow@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This is basically the same as using "file://", but is a
little less subtle for the end user. It also allows relative
paths to be specified.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The --local flag is not "treat this like a local
repository", but rather "if we are local, turn on
optimizations". Therefore it does nothing in the case of:
git clone --local file:///path/to/repo
Let's make that more clear in the documentation.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Because a tag ref cannot be put to HEAD, HEAD will become detached.
This is consistent with "git checkout <tag>".
This is mostly useful in shallow clone, where it allows you to clone a
tag in addtion to branches.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When --single-branch is given, only one branch, either HEAD or one
specified by --branch, will be fetched. Also only tags that point to
the downloaded history are fetched.
This helps most in shallow clones, where it can reduce the download to
minimum and that is why it is enabled by default when --depth is given.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Clone does all of init, "remote add", fetch, and checkout
without giving the user a chance to intervene and set any
configuration. This patch allows you to set config options
in the newly created repository after the clone, but before
we do any other operations.
In many cases, this is a minor convenience over something
like:
git clone git://...
git config core.whatever true
But in some cases, it can bring extra efficiency by changing
how the fetch or checkout work. For example, setting
line-ending config before the checkout avoids having to
re-checkout all of the contents with the correct line
endings.
It also provides a mechanism for passing information to remote
helpers during a clone; the helpers may read the git config
to influence how they operate.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
--separate-git-dir tells git to create git dir at the specified
location, instead of where it is supposed to be. A .git file that
points to that location will be put in place so that it appears normal
to repo discovery process.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@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.
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: Jens Lehmann <Jens.Lehmann@web.de>
Signed-off-by: Junio 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: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio 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: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint:
Git 1.7.0.3
.mailmap: Map the the first submissions of MJG by e-mail
Documentation/git-clone: Transform description list into item list
Documentation/urls: Remove spurious example markers
Documentation/gitdiffcore: Remove misleading date in heading
Documentation/git-reflog: Fix formatting of command lists
* maint-1.6.6:
Documentation/git-clone: Transform description list into item list
Documentation/urls: Remove spurious example markers
Documentation/gitdiffcore: Remove misleading date in heading
Documentation/git-reflog: Fix formatting of command lists
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: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* tc/transport-verbosity:
transport: update flags to be in running order
fetch and pull: learn --progress
push: learn --progress
transport->progress: use flag authoritatively
clone: support multiple levels of verbosity
push: support multiple levels of verbosity
fetch: refactor verbosity option handling into transport.[ch]
Documentation/git-push: put --quiet before --verbose
Documentation/git-pull: put verbosity options before merge/fetch ones
Documentation/git-clone: mention progress in -v
Conflicts:
transport.h
* sd/init-template:
wrap-for-bin: do not export an empty GIT_TEMPLATE_DIR
t/t0001-init.sh: add test for 'init with init.templatedir set'
init: having keywords without value is not a global error.
Add a "TEMPLATE DIRECTORY" section to git-init[1].
Add `init.templatedir` configuration variable.
After 5a518ad (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 21188b1
(Implement git clone -v) may be confused.
Mitigate such risks by stating -v does not affect progress in the
documentation.
Signed-off-by: Tay Ray Chuan <rctay89@gmail.com>
Signed-off-by: Junio 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: Jeff King <peff@peff.net>
Signed-off-by: Junio 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: Steven Drake <sdrake@xnet.co.nz>
Signed-off-by: Junio 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 21188b1 (Implement git clone -v),
which implemented the option to force progress reporting.
Signed-off-by: Tay Ray Chuan <rctay89@gmail.com>
Signed-off-by: Junio 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: Tay Ray Chuan <rctay89@gmail.com>
Signed-off-by: Junio 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: Tay Ray Chuan <rctay89@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document the --branch option as [-b <name>] in git clones synopsis.
Signed-off-by: David Soria Parra <dsp@php.net>
Signed-off-by: Junio 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: Björn Gustavsson <bgustavsson@gmail.com>
Signed-off-by: Junio 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: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* maint-1.6.3:
git-clone: add missing comma in --reference documentation
git-cvsserver: no longer use deprecated 'git-subcommand' commands
clone: disconnect transport after fetching
