summaryrefslogtreecommitdiff
path: root/Documentation/git-checkout.txt
AgeCommit message (Collapse)AuthorFilesLines
2012-04-26docs: stop using asciidoc no-inline-literalLibravatar Jeff King1-4/+4
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>
2011-05-05git-checkout.txt: better docs for '--patch'Libravatar Valentin Haenel1-3/+4
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>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-9/+0
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.
2011-02-27Merge branch 'js/detach-doc'Libravatar Junio C Hamano1-23/+121
* js/detach-doc: git-checkout.txt: improve detached HEAD documentation
2011-02-27Merge branch 'uk/checkout-ambiguous-ref'Libravatar Junio C Hamano1-2/+11
* uk/checkout-ambiguous-ref: Rename t2019 with typo "amiguous" that meant "ambiguous" checkout: rearrange update_refs_for_switch for clarity checkout: introduce --detach synonym for "git checkout foo^{commit}" checkout: split off a function to peel away branchname arg checkout: fix bug with ambiguous refs Conflicts: builtin/checkout.c
2011-02-21git-checkout.txt: improve detached HEAD documentationLibravatar Jay Soffian1-23/+121
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>
2011-02-08checkout: introduce --detach synonym for "git checkout foo^{commit}"Libravatar Junio C Hamano1-2/+11
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>
2010-11-03Change incorrect uses of "remote branch" meaning "remote-tracking"Libravatar Matthieu Moy1-1/+1
"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>
2010-09-27Fix missing 'does' in man-page for 'git checkout'Libravatar Linus Torvalds1-8/+8
Reported-by: Rainer Standke <rainer.standke@krankikom.de> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-08-20Documentation: do not convert ... operator to ellipsesLibravatar Jonathan Nieder1-1/+1
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>
2010-08-18Merge branch 'tc/checkout-B'Libravatar Junio C Hamano1-2/+19
* tc/checkout-B: builtin/checkout: handle -B from detached HEAD correctly builtin/checkout: learn -B builtin/checkout: reword hint for -b add tests for checkout -b
2010-07-11Merge branch 'maint'Libravatar Junio C Hamano1-1/+1
* maint: Documentation: Spelling fix in protocol-capabilities.txt checkout: accord documentation to what git does t0005: work around strange $? in ksh when program terminated by a signal
2010-07-09checkout: accord documentation to what git doesLibravatar Nicolas Sebrecht1-1/+1
Signed-off-by: Nicolas Sebrecht <nicolas.s.dev@gmx.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-06-25builtin/checkout: learn -BLibravatar Tay Ray Chuan1-2/+19
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>
2010-06-22Merge branch 'jn/checkout-doc' into maintLibravatar Junio C Hamano1-23/+31
* jn/checkout-doc: Documentation/checkout: clarify description Documentation/checkout: clarify description
2010-06-21Merge branch 'jn/checkout-doc'Libravatar Junio C Hamano1-23/+31
* jn/checkout-doc: Documentation/checkout: clarify description Documentation/checkout: clarify description
2010-06-21Merge branch 'em/checkout-orphan'Libravatar Junio C Hamano1-14/+21
* em/checkout-orphan: log_ref_setup: don't return stack-allocated array bash completion: add --orphan to 'git checkout' t3200: test -l with core.logAllRefUpdates options checkout --orphan: respect -l option always refs: split log_ref_write logic into log_ref_setup Documentation: alter checkout --orphan description
2010-06-11Documentation/checkout: clarify descriptionLibravatar Jonathan Nieder1-19/+21
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>
2010-06-02Documentation: alter checkout --orphan descriptionLibravatar Erick Mattos1-14/+21
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>
2010-06-02Merge branch 'maint'Libravatar Junio C Hamano1-0/+4
* maint: git-compat-util.h: use apparently more common __sgi macro to detect SGI IRIX Documentation: A...B shortcut for checkout and rebase Documentation/pretty-{formats,options}: better reference for "format:<string>"
2010-06-02Documentation: A...B shortcut for checkout and rebaseLibravatar Michael J Gruber1-0/+4
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>
2010-05-31Documentation/checkout: clarify descriptionLibravatar Jonathan Nieder1-11/+17
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>
2010-03-21git checkout: create unparented branch by --orphanLibravatar Erick Mattos1-1/+19
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>
2009-09-07Merge branch 'tr/reset-checkout-patch'Libravatar Junio C Hamano1-1/+12
* tr/reset-checkout-patch: stash: simplify defaulting to "save" and reject unknown options Make test case number unique tests: disable interactive hunk selection tests if perl is not available DWIM 'git stash save -p' for 'git stash -p' Implement 'git stash save --patch' Implement 'git checkout --patch' Implement 'git reset --patch' builtin-add: refactor the meat of interactive_add() Add a small patch-mode testing library git-apply--interactive: Refactor patch mode code Make 'git stash -k' a short form for 'git stash save --keep-index'
2009-08-29UI consistency: allow --force for where -f means forceLibravatar René Scharfe1-0/+2
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>
2009-08-15Implement 'git checkout --patch'Libravatar Thomas Rast1-1/+12
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>
2009-04-13docs/checkout: clarify what "non-branch" meansLibravatar Jeff King1-5/+5
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>
2009-04-13doc/checkout: split checkout and branch creation in synopsisLibravatar Jeff King1-18/+22
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>
2009-04-13doc/checkout: refer to git-branch(1) as appropriateLibravatar Jeff King1-19/+9
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>
2009-04-13doc: refer to tracking configuration as "upstream"Libravatar Jeff King1-1/+1
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>
2009-04-13doc: clarify --no-track optionLibravatar Jeff King1-1/+2
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>
2009-04-07Merge branch 'maint'Libravatar Junio C Hamano1-3/+7
* maint: Change double quotes to single quotes in message Documentation: clarify .gitattributes search git-checkout.txt: clarify that <branch> applies when no path is given. git-checkout.txt: fix incorrect statement about HEAD and index Conflicts: Documentation/git-checkout.txt
2009-04-07Merge branch 'maint-1.6.1' into maintLibravatar Junio C Hamano1-4/+8
* maint-1.6.1: Documentation: clarify .gitattributes search git-checkout.txt: clarify that <branch> applies when no path is given. git-checkout.txt: fix incorrect statement about HEAD and index
2009-04-07Merge branch 'maint-1.6.0' into maint-1.6.1Libravatar Junio C Hamano1-4/+8
* maint-1.6.0: Documentation: clarify .gitattributes search git-checkout.txt: clarify that <branch> applies when no path is given. git-checkout.txt: fix incorrect statement about HEAD and index
2009-04-07git-checkout.txt: clarify that <branch> applies when no path is given.Libravatar Matthieu Moy1-2/+6
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>
2009-04-07git-checkout.txt: fix incorrect statement about HEAD and indexLibravatar Matthieu Moy1-2/+2
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>
2009-03-17Documentation: remove extra quoting/emphasis around literal textsLibravatar Chris Johnsen1-2/+2
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>
2009-03-10Typo and language fixes for git-checkout.txtLibravatar Michael J Gruber1-17/+16
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-01-17checkout: implement "-" abbreviation, add docs and testsLibravatar Thomas Rast1-0/+4
Have '-' mean the same as '@{-1}', i.e., the last branch we were on. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-19Documentation: sync example output with git outputLibravatar Markus Heidelberg1-1/+0
Don't confuse the user with old git messages. Signed-off-by: Markus Heidelberg <markus.heidelberg@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-12-17Clarify documentation of "git checkout <tree-ish> paths" syntaxLibravatar Nanako Shiraishi1-1/+1
The SYNOPSIS section of the manual writes: git checkout [options] [<tree-ish>] [--] <paths>... but the DESCRIPTION says that this form checks the paths out "from the index, or from a named commit." A later sentence refers to the same argument as "<tree-ish> argument", but it is not clear that these two sentences are talking about the same command line argument for first-time readers. Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-19Documentation: Spelling fixLibravatar Fredrik Skolmli1-1/+1
Signed-off-by: Fredrik Skolmli <fredrik@frsk.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-09-29Merge branch 'jc/better-conflict-resolution'Libravatar Shawn O. Pearce1-7/+34
* jc/better-conflict-resolution: Fix AsciiDoc errors in merge documentation git-merge documentation: describe how conflict is presented checkout --conflict=<style>: recreate merge in a non-default style checkout -m: recreate merge when checking out of unmerged index git-merge-recursive: learn to honor merge.conflictstyle merge.conflictstyle: choose between "merge" and "diff3 -m" styles rerere: understand "diff3 -m" style conflicts with the original rerere.c: use symbolic constants to keep track of parsing states xmerge.c: "diff3 -m" style clips merge reduction level to EAGER or less xmerge.c: minimum readability fixups xdiff-merge: optionally show conflicts in "diff3 -m" style xdl_fill_merge_buffer(): separate out a too deeply nested function checkout --ours/--theirs: allow checking out one side of a conflicting merge checkout -f: allow ignoring unmerged paths when checking out of the index Conflicts: Documentation/git-checkout.txt builtin-checkout.c builtin-merge-recursive.c t/t7201-co.sh
2008-08-31checkout --conflict=<style>: recreate merge in a non-default styleLibravatar Junio C Hamano1-1/+9
This new option does essentially the same thing as -m option when checking unmerged paths out of the index, but it uses the specified style instead of configured merge.conflictstyle. Setting "merge.conflictstyle" to "diff3" is usually less useful than using the default "merge" style, because the latter allows a conflict that results by both sides changing the same region in a very similar way to get simplified substancially by reducing the common lines. However, when one side removed a group of lines (perhaps a function was moved to some other file) while the other side modified it, the default "merge" style does not give any clue as to why the hunk is left conflicting. You would need the original to understand what is going on. The recommended use would be not to set merge.conflictstyle variable so that you would usually use the default "merge" style conflict, and when the result in a path in a particular merge is too hard to understand, use "git checkout --conflict=diff3 $path" to check it out with the original to review what is going on. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-08-30checkout -m: recreate merge when checking out of unmerged indexLibravatar Junio C Hamano1-3/+8
This teaches git-checkout to recreate a merge out of unmerged index entries while resolving conflicts. With this patch, checking out an unmerged path from the index now have the following possibilities: * Without any option, an attempt to checkout an unmerged path will atomically fail (i.e. no other cleanly-merged paths are checked out either); * With "-f", other cleanly-merged paths are checked out, and unmerged paths are ignored; * With "--ours" or "--theirs, the contents from the specified stage is checked out; * With "-m" (we should add "--merge" as synonym), the 3-way merge is recreated from the staged object names and checked out. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-08-30checkout --ours/--theirs: allow checking out one side of a conflicting mergeLibravatar Junio C Hamano1-2/+9
This lets you to check out 'our' (or 'their') version of an unmerged path out of the index while resolving conflicts. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-08-30checkout -f: allow ignoring unmerged paths when checking out of the indexLibravatar Junio C Hamano1-6/+13
Earlier we made "git checkout $pathspec" to atomically refuse the operation of $pathspec matched any path with unmerged stages. This patch allows: $ git checkout -f a b c to ignore, instead of error out on, such unmerged paths. The fix to prevent checkout of an unmerged path from random stages is still there. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-08-22Extend "checkout --track" DWIM to support more casesLibravatar Alex Riesen1-3/+10
The code handles additionally "refs/remotes/<something>/name", "remotes/<something>/name", and "refs/<namespace>/name". Signed-off-by: Alex Riesen <raa.lkml@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-08-11checkout --track: make up a sensible branch name if '-b' was omittedLibravatar Johannes Schindelin1-1/+9
What does the user most likely want with this command? $ git checkout --track origin/next Exactly. A branch called 'next', that tracks origin's branch 'next'. Make it so. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-24checkout: mention '--' in the docsLibravatar SZEDER Gábor1-1/+1
'git checkout' uses '--' to separate options from paths, but it was not mentioned in the documentation Signed-off-by: SZEDER Gábor <szeder@ira.uka.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>