It was common in our documentation to surround short option names with
forward quotes, which renders as italic in HTML. Instead, use backquotes
which renders as monospace. This is one more step toward conformance to
Documentation/CodingGuidelines.
This was obtained with:
perl -pi -e "s/'(-[a-z])'/\`\$1\`/g" *.txt
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Under normal circumstances, and like other git commands,
git checkout will write progress info to stderr if
attached to a terminal. This option allows progress
to be forced even if not using a terminal. Also,
progress can be skipped if using option --no-progress.
Signed-off-by: Edmundo Carmona Antoranz <eantoranz@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This reverts commit 0d1a151783.
When trying to switch to a different branch, that happens to be
checked out in another working tree, the user shouldn't have to
give up the other safety measures (like protecting the local changes
that overlap the difference between the branches) while defeating
the "no two checkouts of the same branch" safety.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
During a 'rebase' (hence 'pull --rebase'), --ours/--theirs may
appear to be swapped to those who are not aware of the fact that
they are temporarily playing the role of the keeper of the more
authoritative history.
Add a note to clarify.
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Simon A. Eugster <simon.eugster@eps.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As a safeguard, checking out a branch already checked out by a different
worktree is disallowed. This behavior can be overridden with
--ignore-other-worktrees, however, this option is neither obvious nor
particularly discoverable. As a common safeguard override, --force is
more likely to come to mind. Therefore, overload it to also suppress the
check for a branch already checked out elsewhere.
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Now that "git worktree add" has achieved user-facing feature-parity with
"git checkout --to", retire the latter.
Move the actual linked worktree creation functionality,
prepare_linked_checkout() and its helpers, verbatim from checkout.c to
worktree.c.
This effectively reverts changes to checkout.c by 529fef2 (checkout:
support checking out into a new working directory, 2014-11-30) with the
exception of merge_working_tree() and switch_branches() which still
require specialized knowledge that a the checkout is occurring in a
newly-created linked worktree (signaled to them by the private
GIT_CHECKOUT_NEW_WORKTREE environment variable).
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Now that the git-worktree command exists, its documentation page is the
natural place for the linked worktree description to reside. Relocate
the "MULTIPLE WORKING TREES" description verbatim from git-checkout.txt
to git-worktree.txt.
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This was missed when "git prune --worktrees" became "git worktree prune".
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git checkout <pathspec> can be used to reset changes in the working tree.
Signed-off-by: Torsten Bögershausen <tboegi@web.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This should improve readability. Compare "thislongname" and
"thisLongName". The following keys are left in unchanged. We can
decide what to do with them later.
- am.keepcr
- core.autocrlf .safecrlf .trustctime
- diff.dirstat .noprefix
- gitcvs.usecrlfattr
- gui.blamehistoryctx .trustmtime
- pull.twohead
- receive.autogc
- sendemail.signedoffbycc .smtpsslcertpath .suppresscc
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The goal seems to be using multiple checkouts to reduce disk space.
But we have not reached an agreement how things should be. There are a
couple options.
- You may want to keep $SUB repos elsewhere (perhaps in a central
place) outside $SUPER. This is also true for nested submodules
where a superproject may be a submodule of another superproject.
- You may want to keep all $SUB repos in $SUPER/modules (or some
other place in $SUPER)
- We could even push it further and merge all $SUB repos into $SUPER
instead of storing them separately. But that would at least require
ref namespace enabled.
On top of that, git-submodule.sh expects $GIT_DIR/config to be
per-worktree, at least for the submodule.* part. Here I think we have
two options, either update config.c to also read
$GIT_DIR/config.worktree (which is per worktree) in addition to
$GIT_DIR/config (shared) and store worktree-specific vars in the new
place, or update git-submodule.sh to read/write submodule.* directly
from $GIT_DIR/config.submodule (per worktree).
These take time to address properly. Meanwhile, make a note to the
user that they should not use multiple worktrees in submodule context.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Noticed-by: Mark Levedahl <mlevedahl@gmail.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
(alias R=$GIT_COMMON_DIR/worktrees/<id>)
- linked checkouts are supposed to keep its location in $R/gitdir up
to date. The use case is auto fixup after a manual checkout move.
- linked checkouts are supposed to update mtime of $R/gitdir. If
$R/gitdir's mtime is older than a limit, and it points to nowhere,
worktrees/<id> is to be pruned.
- If $R/locked exists, worktrees/<id> is not supposed to be pruned. If
$R/locked exists and $R/gitdir's mtime is older than a really long
limit, warn about old unused repo.
- "git checkout --to" is supposed to make a hard link named $R/link
pointing to the .git file on supported file systems to help detect
the user manually deleting the checkout. If $R/link exists and its
link count is greated than 1, the repo is kept.
Helped-by: Marc Branchaud <marcnarc@xiplink.com>
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Helped-by: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git checkout --to" sets up a new working directory with a .git file
pointing to $GIT_DIR/worktrees/<id>. It then executes "git checkout"
again on the new worktree with the same arguments except "--to" is
taken out. The second checkout execution, which is not contaminated
with any info from the current repository, will actually check out and
everything that normal "git checkout" does.
Helped-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The @{-N} syntax always referred to the N-th last thing checked out,
which can be either a branch or a commit (for detached HEAD cases).
However, the documentation only mentioned branches.
Edit in a "/commit" in the appropriate places.
Reported-by: Kevin <ikke@ikke.info>
Signed-off-by: Thomas Rast <tr@thomasrast.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In the synopsis, the second form to detach HEAD at the named commit
labelled the argument as '<commit>'. While this is technically more
correct, because the feature to detach is not limited to the tip of
a named branch, it was found confusing and did not express the fact
that you have to give `--detach` if you are naming the commit you
want to detach HEAD at with a branch name.
Separate this case into two syntactical forms, mimicking the way how
the DESCRIPTION section shows this usage. Also update the text that
explains the syntax to name the commit to detach HEAD at to clarify.
Suggested-by: Benjamin Bergman <ben@benbergman.ca>
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The DWIM mode of checkout allows you to run "git checkout foo" when there
is no existing local ref or path called "foo", and there is exactly _one_
remote with a remote-tracking branch called "foo". Git will automatically
create a new local branch called "foo" using the remote-tracking "foo" as
its starting point and configured upstream.
For example, consider the following unconventional (but perfectly valid)
remote setup:
[remote "origin"]
fetch = refs/heads/*:refs/remotes/origin/*
[remote "frotz"]
fetch = refs/heads/*:refs/remotes/frotz/nitfol/*
Case 1: Assume both "origin" and "frotz" have remote-tracking branches called
"foo", at "refs/remotes/origin/foo" and "refs/remotes/frotz/nitfol/foo"
respectively. In this case "git checkout foo" should fail, because there is
more than one remote with a "foo" branch.
Case 2: Assume only "frotz" have a remote-tracking branch called "foo". In
this case "git checkout foo" should succeed, and create a local branch "foo"
from "refs/remotes/frotz/nitfol/foo", using remote branch "foo" from "frotz"
as its upstream.
The current code hardcodes the assumption that all remote-tracking branches
must match the "refs/remotes/$remote/*" pattern (which is true for remotes
with "conventional" refspecs, but not true for the "frotz" remote above).
When running "git checkout foo", the current code looks for exactly one ref
matching "refs/remotes/*/foo", hence in the above example, it fails to find
"refs/remotes/frotz/nitfol/foo", which causes it to fail both case #1 and #2.
The better way to handle the above example is to actually study the fetch
refspecs to deduce the candidate remote-tracking branches for "foo"; i.e.
assume "foo" is a remote branch being fetched, and then map "refs/heads/foo"
through the refspecs in order to get the corresponding remote-tracking
branches "refs/remotes/origin/foo" and "refs/remotes/frotz/nitfol/foo".
Finally we check which of these happens to exist in the local repo, and
if there is exactly one, we have an unambiguous match for "git checkout foo",
and may proceed.
This fixes most of the failing tests introduced in the previous patch.
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git checkout -- <paths>" is usually used to restore all modified
files in <paths>. In sparse checkout mode, this command is overloaded
with another meaning: to add back all files in <paths> that are
excluded by sparse patterns.
As the former makes more sense for day-to-day use. Switch it to the
default and the latter enabled with --ignore-skip-worktree-bits.
While at there, add info/sparse-checkout to gitrepository-layout.txt
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Document the behavior implemented in 70c9ac2 (DWIM "git checkout
frotz" to "git checkout -b frotz origin/frotz").
Signed-off-by: Chris Rorvick <chris@rorvick.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The forms of checkout that do not take a path are lumped together in
the DESCRIPTION section, but the description for this group is
dominated by explanation of the -b|-B form.
Split these apart for more clarity.
Signed-off-by: Chris Rorvick <chris@rorvick.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
While the synopsis section makes it clear that the new branch name
is the parameter to these flags, the option description did not.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Describe '-p' as a short form of '--patch' in synopsis and options. Also
refer the reader to the patch mode description of git-add documentation.
Helped-by: Jeff King <peff@peff.net>
Mentored-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
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.
The detached HEAD state is a source of much confusion for users
new to git. Here we try to document it better.
Reworked from http://article.gmane.org/gmane.comp.version-control.git/138440
Requested-by: Nicolas Pitre <nico@fluxnic.net>
Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
For example, one might use this when making a temporary merge to
test that two topics work well together.
Patch by Junio, with tests from Jeff King.
[jn: with some extra checks for bogus commandline usage]
Suggested-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
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>
The symmetric difference or merge-base operator ... as used by
rev-list and diff is actually three period characters. If it
gets replaced by an ellipsis glyph in the manual, that would
stop readers from copying and pasting it.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Internally, --track and --orphan still use the 'safe' -b, not -B.
Signed-off-by: Tay Ray Chuan <rctay89@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
git checkout can be used to switch branches and to retrieve files from
the index or an arbitrary tree. Split the description into
subsections corresponding to each mode to make each use easier to
understand.
Helped-by: Jeff King <peff@peff.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The present text is a try to enhance description accuracy. It is a
merge of the rewritten text made by native english speaker Chris Johnsen
and further changes of Junio. It came from the last thread messages of
--orphan patch.
Signed-off-by: Erick Mattos <erick.mattos@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Describe the A...B shortcuts for checkout and rebase [-i] which were
introduced in these commits:
619a64e ("checkout A...B" switches to the merge base between A and B, 2009-10-18)
61dfa1b ("rebase --onto A...B" replays history on the merge base between A and B, 2009-11-20)
230a456 (rebase -i: teach --onto A...B syntax, 2010-01-07)
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
To the first-time reader, it may not be obvious that ‘git checkout’
has two modes, nor that if no branch is specified it will read
from the index.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Similar to -b, --orphan creates a new branch, but it starts without any
commit. After running "git checkout --orphan newbranch", you are on a
new branch "newbranch", and the first commit you create from this state
will start a new history without any ancestry.
"git checkout --orphan" keeps the index and the working tree files
intact in order to make it convenient for creating a new history whose
trees resemble the ones from the original branch.
When creating a branch whose trees have no resemblance to the ones from
the original branch, it may be easier to start work on the new branch by
untracking and removing all working tree files that came from the
original branch, by running a 'git rm -rf .' immediately after running
"checkout --orphan".
Signed-off-by: Erick Mattos <erick.mattos@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>
This introduces a --patch mode for git-checkout. In the index usage
git checkout --patch -- [files...]
it lets the user discard edits from the <files> at the granularity of
hunks (by selecting hunks from 'git diff' and then reverse applying
them to the worktree).
We also accept a revision argument. In the case
git checkout --patch HEAD -- [files...]
we offer hunks from the difference between HEAD and the worktree, and
reverse applies them to both index and worktree, allowing you to
discard staged changes completely. In the non-HEAD usage
git checkout --patch <revision> -- [files...]
it offers hunks from the difference between the worktree and
<revision>. The chosen hunks are then applied to both index and
worktree.
The application to worktree and index is done "atomically" in the
sense that we first check if the patch applies to the index (it should
always apply to the worktree). If it does not, we give the user a
choice to either abort or apply to the worktree anyway.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
In the code we literally stick "refs/heads/" on the front
and see if it resolves, so that is probably the best
explanation.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
These can really be thought of as two different modes, since
the "<branch>" parameter is treated differently in the two
(in one it is the branch to be checked out, but in the other
it is really a start-point for branch creation).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Most of description for the branch creation options is
simply cut and paste from git-branch. There are two reasons
to fix this:
1. It can grow stale with respect to what's in "git
branch" (which it is now is).
2. It is not just an implementation detail, but rather the
desired mental model for the command that we are using
"git branch" here. Being explicit about that can help
the user understand what is going on.
It also makes sense to strip the branch creation options
from the synopsis, as they are making it a long,
hard-to-read line. They are still easily discovered by
reading the options list, and --track is explicitly
referenced when branch creation is described.
Signed-off-by: Jeff King <peff@peff.net>
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>
Otherwise, the sentence "Defaults to HEAD." can be mis-read to mean
that "git checkout -- hello.c" checks-out from HEAD.
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The command "git checkout" checks out from the index by default, not
HEAD (the introducing comment were correct, but the detailled
explanation added below were not).
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
If literal text (asciidoc `...`) can be rendered in a differently from
normal text for each output format (man, HTML), then we do not need
extra quotes or other wrapping around inline literal text segments.
config.txt
Change '`...`' to `...`. In asciidoc, the single quotes provide
emphasis, literal text should be distintive enough.
Change "`...`" to `...`. These double quotes do not work if present
in the described config value, so drop them.
git-checkout.txt
Change "`...`" to `...` or `"..."`. All instances are command line
argument examples. One "`-`" becomes `-`. Two others are involve
curly braces, so move the double quotes inside the literal region to
indicate that they might need to be quoted on the command line of
certain shells (tcsh).
git-merge.txt
Change "`...`" to `...`. All instances are used to describe merge
conflict markers. The quotes should are not important.
git-rev-parse.txt
Change "`...`" to `...`. All instances are around command line
arguments where no in-shell quoting should be necessary.
gitcli.txt
Change `"..."` to `...`. All instances are around command line
examples or single command arguments. They do not semanticly belong
inside the literal text, and they are not needed outside it.
glossary-content.txt
user-manual.txt
Change "`...`" to `...`. All instances were around command lines.
Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Matthieu Moy