summaryrefslogtreecommitdiff
path: root/Documentation/git-checkout.txt
AgeCommit message (Collapse)AuthorFilesLines
2021-12-15Merge branch 'en/zdiff3'Libravatar Junio C Hamano1-2/+1
"Zealous diff3" style of merge conflict presentation has been added. * en/zdiff3: update documentation for new zdiff3 conflictStyle xdiff: implement a zealous diff3, or "zdiff3"
2021-12-10Merge branch 'ja/doc-cleanup'Libravatar Junio C Hamano1-18/+18
Doc update. * ja/doc-cleanup: init doc: --shared=0xxx does not give umask but perm bits doc: git-init: clarify file modes in octal. doc: git-http-push: describe the refs as pattern pairs doc: uniformize <URL> placeholders' case doc: use three dots for indicating repetition instead of star doc: git-ls-files: express options as optional alternatives doc: use only hyphens as word separators in placeholders doc: express grammar placeholders between angle brackets doc: split placeholders as individual tokens doc: fix git credential synopsis
2021-12-01update documentation for new zdiff3 conflictStyleLibravatar Elijah Newren1-2/+1
Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-11-09doc: use only hyphens as word separators in placeholdersLibravatar Jean-Noël Avila1-18/+18
According to CodingGuidelines, multi-word placeholders should use hyphens as word separators. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com> Reviewed-by: Eli Schwartz <eschwartz@archlinux.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-09-27Documentation: call out commands that nuke untracked files/directoriesLibravatar Elijah Newren1-2/+3
Some commands have traditionally also removed untracked files (or directories) that were in the way of a tracked file we needed. Document these cases. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-27Merge branch 'dl/checkout-guess'Libravatar Junio C Hamano1-1/+4
"git checkout" learned to use checkout.guess configuration variable and enable/disable its "--[no-]guess" option accordingly. * dl/checkout-guess: checkout: learn to respect checkout.guess Documentation/config/checkout: replace sq with backticks
2020-10-27Merge branch 'dl/checkout-p-merge-base'Libravatar Junio C Hamano1-0/+4
"git checkout -p A...B [-- <path>]" did not work, even though the same command without "-p" correctly used the merge-base between commits A and B. * dl/checkout-p-merge-base: t2016: add a NEEDSWORK about the PERL prerequisite add-patch: add NEEDSWORK about comparing commits Doc: document "A...B" form for <tree-ish> in checkout and switch builtin/checkout: fix `git checkout -p HEAD...` bug
2020-10-08checkout: learn to respect checkout.guessLibravatar Denton Liu1-1/+4
The current behavior of git checkout/switch is that --guess is currently enabled by default. However, some users may not wish for this to happen automatically. Instead of forcing users to specify --no-guess manually each time, teach these commands the checkout.guess configuration variable that gives users the option to set a default behavior. Teach the completion script to recognize the new config variable and disable DWIM logic if it is set to false. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-07Doc: document "A...B" form for <tree-ish> in checkout and switchLibravatar Denton Liu1-0/+4
Using "A...B" has been supported for the <tree-ish> argument for a while. However, its support has never been explicitly documented. Explicitly document it so that users know that it is available. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-09-06git-checkout.txt: document -d short option for --detachLibravatar Eric Sunshine1-0/+1
`git checkout` learned -d as short option for --detach in 163e3b2975 (switch: add short option for --detach, 2019-03-29) but the documentation was never updated to reflect the change. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-04-06doc: --recurse-submodules mostly applies to active submodulesLibravatar Damien Robert1-1/+1
The documentation refers to "initialized" or "populated" submodules, to explain which submodules are affected by '--recurse-submodules', but the real terminology here is 'active' submodules. Update the documentation accordingly. Some terminology: - Active is defined in gitsubmodules(7), it only involves the configuration variables 'submodule.active', 'submodule.<name>.active' and 'submodule.<name>.url'. The function submodule.c::is_submodule_active checks that a submodule is active. - Populated means that the submodule's working tree is present (and the gitfile correctly points to the submodule repository), i.e. either the superproject was cloned with ` --recurse-submodules`, or the user ran `git submodule update --init`, or `git submodule init [<path>]` and `git submodule update [<path>]` separately which populated the submodule working tree. This does not involve the 3 configuration variables above. - Initialized (at least in the context of the man pages involved in this patch) means both "populated" and "active" as defined above, i.e. what `git submodule update --init` does. The --recurse-submodules option mostly affects active submodules. An exception is `git fetch` where the option affects populated submodules. As a consequence, in `git pull --recurse-submodules` the fetch affects populated submodules, but the resulting working tree update only affects active submodules. In the documentation of `git-pull`, let's distinguish between the fetching part which affects populated submodules, and the updating of worktrees, which only affects active submodules. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> Helped-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-04-06doc: document --recurse-submodules for reset and restoreLibravatar Damien Robert1-1/+1
Also unify the formulation about --no-recurse-submodules for checkout and switch, which we reuse for restore. And correct the formulation about submodules' HEAD in read-tree, which we reuse in reset. Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-04checkout, restore: support the --pathspec-from-file optionLibravatar Alexandr Miloslavskiy1-0/+15
Decisions taken for simplicity: 1) For now, `--pathspec-from-file` is declared incompatible with `--patch`, even when <file> is not `stdin`. Such use case it not really expected. 2) It is not allowed to pass pathspec in both args and file. `you must specify path(s) to restore` block was moved down to be able to test for `pathspec.nr` instead, because testing for `argc` is no longer correct. `git switch` does not support the new options because it doesn't expect `<pathspec>` arguments. Signed-off-by: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-04doc: checkout: synchronize <pathspec> descriptionLibravatar Alexandr Miloslavskiy1-9/+15
`git add` shows an example of good writing, follow it. Signed-off-by: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-04doc: checkout: fix broken text referenceLibravatar Alexandr Miloslavskiy1-6/+4
Signed-off-by: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-04doc: checkout: remove duplicate synopsisLibravatar Alexandr Miloslavskiy1-2/+1
It was added in [1]. I understand that the duplicate change was not intentional and comes from an oversight. Also, in explanation, there was only one section for two synopsis entries. Fix both problems by removing duplicate synopsis. <paths> vs <pathspec> is resolved in next patch. [1] Commit b59698ae ("checkout doc: clarify command line args for "checkout paths" mode" 2017-10-11) Signed-off-by: Alexandr Miloslavskiy <alexandr.miloslavskiy@syntevo.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-07-09Merge branch 'nd/switch-and-restore'Libravatar Junio C Hamano1-100/+122
Two new commands "git switch" and "git restore" are introduced to split "checking out a branch to work on advancing its history" and "checking out paths out of the index and/or a tree-ish to work on advancing the current history" out of the single "git checkout" command. * nd/switch-and-restore: (46 commits) completion: disable dwim on "git switch -d" switch: allow to switch in the middle of bisect t2027: use test_must_be_empty Declare both git-switch and git-restore experimental help: move git-diff and git-reset to different groups doc: promote "git restore" user-manual.txt: prefer 'merge --abort' over 'reset --hard' completion: support restore t: add tests for restore restore: support --patch restore: replace --force with --ignore-unmerged restore: default to --source=HEAD when only --staged is specified restore: reject invalid combinations with --staged restore: add --worktree and --staged checkout: factor out worktree checkout code restore: disable overlay mode by default restore: make pathspec mandatory restore: take tree-ish from --source option instead checkout: split part of it to new command 'restore' doc: promote "git switch" ...
2019-05-19Merge branch 'dl/branch-from-3dot-merge-base'Libravatar Junio C Hamano1-0/+4
"git branch new A...B" and "git checkout -b new A...B" have been taught that in their contexts, the notation A...B means "the merge base between these two commits", just like "git checkout A...B" detaches HEAD at that commit. * dl/branch-from-3dot-merge-base: branch: make create_branch accept a merge base rev t2018: cleanup in current test
2019-05-07branch: make create_branch accept a merge base revLibravatar Denton Liu1-0/+4
When we ran something like $ git checkout -b test master... it would fail with the message fatal: Not a valid object name: 'master...'. This was caused by the call to `create_branch` where `start_name` is expected to be a valid rev. However, git-checkout allows the branch to be a valid _merge base_ rev (i.e. with a "...") so it was possible for an invalid rev to be passed in. Make `create_branch` accept a merge base rev so that this case does not error out. As a side-effect, teach git-branch how to handle merge base revs as well. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-07checkout: split part of it to new command 'restore'Libravatar Nguyễn Thái Ngọc Duy1-1/+2
Previously the switching branch business of 'git checkout' becomes a new command 'switch'. This adds the restore command for the checking out paths path. Similar to git-switch, a new man page is added to describe what the command will become. The implementation will be updated shortly to match the man page. A couple main differences from 'git checkout <paths>': - 'restore' by default will only update worktree. This matters more when --source is specified ('checkout <tree> <paths>' updates both worktree and index). - 'restore --staged' can be used to restore the index. This command overlaps with 'git reset <paths>'. - both worktree and index could also be restored at the same time (from a tree) when both --staged and --worktree are specified. This overlaps with 'git checkout <tree> <paths>' - default source for restoring worktree and index is the index and HEAD respectively. A different (tree) source could be specified as with --source (*). - when both index and worktree are restored, --source must be specified since the default source for these two individual targets are different (**) - --no-overlay is enabled by default, if an entry is missing in the source, restoring means deleting the entry (*) I originally went with --from instead of --source. I still think --from is a better name. The short option -f however is already taken by force. And I do think short option is good to have, e.g. to write -s@ or -s@^ instead of --source=HEAD. (**) If you sit down and think about it, moving worktree's source from the index to HEAD makes sense, but nobody is really thinking it through when they type the commands. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-16Merge branch 'nd/checkout-m-doc-update'Libravatar Junio C Hamano1-0/+2
Doc about the above. * nd/checkout-m-doc-update: checkout.txt: note about losing staged changes with --merge
2019-04-02switch: implicit dwim, use --no-guess to disable itLibravatar Nguyễn Thái Ngọc Duy1-15/+23
This is already the default in git-checkout. The real change in here is just minor cleanup. The main excuse is to explain why dwim is kept default. Contrary to detach mode that is easy to get into and confusing to get back out. Automatically creating a tracking branch often does not kick in as often (you would need a branch of the same name on a remote). And since the branch creation is reported clearly, the user should be able to undo/delete it if it's unwanted. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-02checkout: split part of it to new command 'switch'Libravatar Nguyễn Thái Ngọc Duy1-0/+4
"git checkout" doing too many things is a source of confusion for many users (and it even bites old timers sometimes). To remedy that, the command will be split into two new ones: switch and restore. The good old "git checkout" command is still here and will be until all (or most of users) are sick of it. See the new man page for the final design of switch. The actual implementation though is still pretty much the same as "git checkout" and not completely aligned with the man page. Following patches will adjust their behavior to match the man page. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-02git-checkout.txt: fix monospace typesetLibravatar Nguyễn Thái Ngọc Duy1-81/+81
Add backticks where we have none, replace single quotes with backticks and replace double-quotes. Drop double-quotes from nested constructions such as `"@{-1}"`. Helped-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-02doc: document --overwrite-ignoreLibravatar Nguyễn Thái Ngọc Duy1-0/+6
I added this option in git-checkout and git-merge in c1d7036b6b (checkout,merge: disallow overwriting ignored files with --no-overwrite-ignore - 2011-11-27) but did not remember to update documentation. This completes that commit. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-02git-checkout.txt: fix one syntax lineLibravatar Nguyễn Thái Ngọc Duy1-1/+1
<branch> can be omitted in this syntax, and it's actually documented a few paragraphs down: You could omit <branch>, in which case the command degenerates to "check out the current branch", which is a glorified no-op with rather expensive side-effects to show only the tracking information, if exists, for the current branch. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-02git-checkout.txt: spell out --no-optionLibravatar Nguyễn Thái Ngọc Duy1-4/+7
It's easier to search for and also less cryptic. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-21checkout.txt: note about losing staged changes with --mergeLibravatar Nguyễn Thái Ngọc Duy1-0/+2
If you have staged changes in path A and perform 'checkout --merge' (which could result in conflicts in a totally unrelated path B), changes in A will be gone. Which is unexpected. We are supposed to keep all changes, or kick and scream otherwise. This is the result of how --merge is implemented, from the very first day in 1be0659efc (checkout: merge local modifications while switching branches., 2006-01-12): 1. a merge is done, unmerged entries are collected 2. a hard switch to a new branch is done, then unmerged entries added back There is no trivial fix for this. Going with 3-way merge one file at a time loses rename detection. Going with 3-way merge by trees requires teaching the algorithm to pick up staged changes. And even if we detect staged changes with --merge and abort for safety, an option to continue --merge is very weird. Such an option would keep worktree changes, but drop staged changes. Because the problem has been with us since the introduction of --merge and everybody has been pretty happy (except Phillip, who found this problem), I'll just take a note here to acknowledge it and wait for merge wizards to come in and work their magic. There may be a way forward [1]. [1] CABPp-BFoL_U=bzON4SEMaQSKU2TKwnOgNqjt5MUaOejTKGUJxw@mail.gmail.com Reported-by: Phillip Wood <phillip.wood@dunelm.org.uk> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-07Merge branch 'tg/checkout-no-overlay'Libravatar Junio C Hamano1-0/+10
"git checkout --no-overlay" can be used to trigger a new mode of checking out paths out of the tree-ish, that allows paths that match the pathspec that are in the current index and working tree and are not in the tree-ish. * tg/checkout-no-overlay: revert "checkout: introduce checkout.overlayMode config" checkout: introduce checkout.overlayMode config checkout: introduce --{,no-}overlay option checkout: factor out mark_cache_entry_for_checkout function checkout: clarify comment read-cache: add invalidate parameter to remove_marked_cache_entries entry: support CE_WT_REMOVE flag in checkout_entry entry: factor out unlink_entry function move worktree tests to t24*
2019-02-24Merge branch 'yn/checkout-doc-fix'Libravatar Junio C Hamano1-1/+1
Doc fix. * yn/checkout-doc-fix: checkout doc: fix an unmatched double-quote pair
2019-02-23checkout doc: fix an unmatched double-quote pairLibravatar Yoichi Nakayama1-1/+1
Signed-off-by: Yoichi Nakayama <yoichi.nakayama@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-05Merge branch 'ja/doc-style-fix'Libravatar Junio C Hamano1-8/+8
Doc typo/stylo fixes. * ja/doc-style-fix: doc: tidy asciidoc style
2019-01-23doc: tidy asciidoc styleLibravatar Jean-Noël Avila1-8/+8
This mainly refers to enforcing indentation on additional lines of items of lists. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-08checkout: introduce --{,no-}overlay optionLibravatar Thomas Gummerer1-0/+10
Currently 'git checkout' is defined as an overlay operation, which means that if in 'git checkout <tree-ish> -- [<pathspec>]' we have an entry in the index that matches <pathspec>, but that doesn't exist in <tree-ish>, that entry will not be removed from the index or the working tree. Introduce a new --{,no-}overlay option, which allows using 'git checkout' in non-overlay mode, thus removing files from the working tree if they do not exist in <tree-ish> but match <pathspec>. Note that 'git checkout -p <tree-ish> -- [<pathspec>]' already works this way, so no changes are needed for the patch mode. We disallow 'git checkout --overlay -p' to avoid confusing users who would expect to be able to force overlay mode in 'git checkout -p' this way. Untracked files are not affected by this change, so 'git checkout --no-overlay HEAD -- untracked' will not remove untracked from the working tree. This is so e.g. 'git checkout --no-overlay HEAD -- dir/' doesn't delete all untracked files in dir/, but rather just resets the state of files that are known to git. Suggested-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Thomas Gummerer <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-11-14checkout: disambiguate dwim tracking branches and local filesLibravatar Nguyễn Thái Ngọc Duy1-0/+4
When checkout dwim is added in [1], it is restricted to only dwim when certain conditions are met and fall back to default checkout behavior otherwise. It turns out falling back could be confusing. One of the conditions to turn git checkout frotz to git checkout -b frotz origin/frotz is that frotz must not exist as a file. But when the user comes to expect "git checkout frotz" to create the branch "frotz" and there happens to be a file named "frotz", git's silently reverting "frotz" file content is not helping. This is reported in Git mailing list [2] and even used as an example of "Git is bad" elsewhere [3]. We normally try to do the right thing, but when there are multiple "right things" to do, it's best to leave it to the user to decide. Check this case, ask the user to to disambiguate: - "git checkout -- foo" will check out path "foo" - "git checkout foo --" will dwim and create branch "foo" [4] For users who do not want dwim, use --no-guess. It's useless in this particular case because "git checkout --no-guess foo --" will just fail. But it could be used by scripts. [1] 70c9ac2f19 (DWIM "git checkout frotz" to "git checkout -b frotz origin/frotz" - 2009-10-18) [2] https://public-inbox.org/git/CACsJy8B2TVr1g+k+eSQ=pBEO3WN4_LtgLo9gpur8X7Z9GOFL_A@mail.gmail.com/ [3] https://news.ycombinator.com/item?id=18230655 [4] a047fafc78 (checkout: allow dwim for branch creation for "git checkout $branch --" - 2013-10-18) Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-23doc: fix ASCII art tab spacingLibravatar Andreas Heiduk1-7/+7
Followup to 5dd05ebf ("doc: fix merge-base ASCII art tab spacing", 2016-10-21) Signed-off-by: Andreas Heiduk <asheiduk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-11checkout & worktree: introduce checkout.defaultRemoteLibravatar Ævar Arnfjörð Bjarmason1-0/+9
Introduce a checkout.defaultRemote setting which can be used to designate a remote to prefer (via checkout.defaultRemote=origin) when running e.g. "git checkout master" to mean origin/master, even though there's other remotes that have the "master" branch. I want this because it's very handy to use this workflow to checkout a repository and create a topic branch, then get back to a "master" as retrieved from upstream: ( cd /tmp && rm -rf tbdiff && git clone git@github.com:trast/tbdiff.git && cd tbdiff && git branch -m topic && git checkout master ) That will output: Branch 'master' set up to track remote branch 'master' from 'origin'. Switched to a new branch 'master' But as soon as a new remote is added (e.g. just to inspect something from someone else) the DWIMery goes away: ( cd /tmp && rm -rf tbdiff && git clone git@github.com:trast/tbdiff.git && cd tbdiff && git branch -m topic && git remote add avar git@github.com:avar/tbdiff.git && git fetch avar && git checkout master ) Will output (without the advice output added earlier in this series): error: pathspec 'master' did not match any file(s) known to git. The new checkout.defaultRemote config allows me to say that whenever that ambiguity comes up I'd like to prefer "origin", and it'll still work as though the only remote I had was "origin". Also adjust the advice.checkoutAmbiguousRemoteBranchName message to mention this new config setting to the user, the full output on my git.git is now (the last paragraph is new): $ ./git --exec-path=$PWD checkout master error: pathspec 'master' did not match any file(s) known to git. hint: 'master' matched more than one remote tracking branch. hint: We found 26 remotes with a reference that matched. So we fell back hint: on trying to resolve the argument as a path, but failed there too! hint: hint: If you meant to check out a remote tracking branch on, e.g. 'origin', hint: you can do so by fully qualifying the name with the --track option: hint: hint: git checkout --track origin/<name> hint: hint: If you'd like to always have checkouts of an ambiguous <name> prefer hint: one remote, e.g. the 'origin' remote, consider setting hint: checkout.defaultRemote=origin in your config. I considered splitting this into checkout.defaultRemote and worktree.defaultRemote, but it's probably less confusing to break our own rules that anything shared between config should live in core.* than have two config settings, and I couldn't come up with a short name under core.* that made sense (core.defaultRemoteForCheckout?). See also 70c9ac2f19 ("DWIM "git checkout frotz" to "git checkout -b frotz origin/frotz"", 2009-10-18) which introduced this DWIM feature to begin with, and 4e85333197 ("worktree: make add <path> <branch> dwim", 2017-11-26) which added it to git-worktree. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-12-13Merge branch 'ks/doc-checkout-previous'Libravatar Junio C Hamano1-4/+4
@{-N} in "git checkout @{-N}" may refer to a detached HEAD state, but the documentation was not clear about it, which has been fixed. * ks/doc-checkout-previous: Doc/checkout: checking out using @{-N} can lead to detached state
2017-12-06Merge branch 'sb/submodule-recursive-checkout-detach-head'Libravatar Junio C Hamano1-0/+2
"git checkout --recursive" may overwrite and rewind the history of the branch that happens to be checked out in submodule repositories, which might not be desirable. Detach the HEAD but still allow the recursive checkout to succeed in such a case. * sb/submodule-recursive-checkout-detach-head: Documentation/checkout: clarify submodule HEADs to be detached recursive submodules: detach HEAD from new state
2017-11-28Doc/checkout: checking out using @{-N} can lead to detached stateLibravatar Kaartic Sivaraam1-4/+4
@{-N} is a syntax for the N-th last "checkout" and not the N-th last "branch". Therefore, in some cases using `git checkout @{-$N}` DOES lead to a "detached HEAD" state. This can also be ensured by the commit message of 75d6e552a (Documentation: @{-N} can refer to a commit, 2014-01-19) which clearly specifies how @{-N} can be used to refer not only to a branch but also to a commit. Correct the misleading sentence which states that @{-N} doesn't detach HEAD. Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-10-17Merge branch 'jc/doc-checkout'Libravatar Junio C Hamano1-14/+16
Doc update. * jc/doc-checkout: checkout doc: clarify command line args for "checkout paths" mode
2017-10-11checkout doc: clarify command line args for "checkout paths" modeLibravatar Junio C Hamano1-14/+16
There are "git checkout [-p][<tree-ish>][--][<paths>...]" in the SYNOPSIS section, and "git checkout [-p][<tree-ish>][--]<paths>..." as the header for the section that explains the "check out paths from index/tree-ish" mode. It is unclear if we require at least one path, or it is entirely optional. Actually, both are wrong. Without the "-p(atch)" option, you must have <pathspec> (otherwise, with a commit that is a <tree-ish>, you would be checking out that commit to build a new history on top of it). With it, it is already clear that you are checking out paths, it is optional. In other words, you cannot omit both. The source of the confusion is that -p(atch) is described as if it is just another "optional" part and its description is lumped together with the non patch mode, even though the actual end user experience is vastly different. Let's split the entry into two, and describe the regular mode and the patch mode separately. This allows us to make it clear that the regular mode MUST be given at least one pathspec, that the patch mode can be invoked with either '-p' or '--patch' but one of these must be given, and that the pathspec is entirely optional in the patch mode. Also, revamp the explanation of "checkout paths" by removing extraneous description at the beginning, that says "checking out paths is not checking out a branch". Explaining what it is for and when the user wants to use it upfront is the most direct way to help the readers. Noticed-by: Robert P J Day Helped-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-09-14doc: fix minor typos (extra/duplicated words)Libravatar Evan Zacks1-1/+1
Following are several fixes for duplicated words ("of of") and one case where an extra article ("a") slipped in. Signed-off-by: Evan Zacks <zackse@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-07-28Documentation/checkout: clarify submodule HEADs to be detachedLibravatar Stefan Beller1-0/+2
Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-16builtin/checkout: add --recurse-submodules switchLibravatar Stefan Beller1-0/+7
This exposes a flag to recurse into submodules in builtin/checkout making use of the code implemented in prior patches. A new failure mode is introduced in the submodule update library, as the directory/submodule conflict is not solved in prior patches. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-09-21checkout.txt: document a common case that ignores ambiguation rulesLibravatar Nguyễn Thái Ngọc Duy1-0/+12
Normally we err on the safe side: if something can be seen as both an SHA1 and a pathspec, we stop and scream. In checkout, there is one exception added in 859fdab (git-checkout: improve error messages, detect ambiguities. - 2008-07-23), to allow the common case "git checkout branch". Let's document this exception. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-28doc: typeset short command-line options as literalLibravatar Matthieu Moy1-2/+2
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>
2015-11-01checkout: add --progress optionLibravatar Edmundo Carmona Antoranz1-0/+6
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>
2015-08-03Merge branch 'se/doc-checkout-ours-theirs'Libravatar Junio C Hamano1-0/+15
A "rebase" replays changes of the local branch on top of something else, as such they are placed in stage #3 and referred to as "theirs", while the changes in the new base, typically a foreign work, are placed in stage #2 and referred to as "ours". Clarify the "checkout --ours/--theirs". * se/doc-checkout-ours-theirs: checkout: document subtlety around --ours/--theirs
2015-07-13Merge branch 'es/worktree-add'Libravatar Junio C Hamano1-72/+0
Update to the "linked checkout" in 2.5.0-rc1. Instead of "checkout --to" that does not do what "checkout" normally does, move the functionality to "git worktree add". * es/worktree-add: (24 commits) Revert "checkout: retire --ignore-other-worktrees in favor of --force" checkout: retire --ignore-other-worktrees in favor of --force worktree: add: auto-vivify new branch when <branch> is omitted worktree: add: make -b/-B default to HEAD when <branch> is omitted worktree: extract basename computation to new function checkout: require worktree unconditionally checkout: retire --to option tests: worktree: retrofit "checkout --to" tests for "worktree add" worktree: add -b/-B options worktree: add --detach option worktree: add --force option worktree: introduce "add" command checkout: drop 'checkout_opts' dependency from prepare_linked_checkout checkout: make --to unconditionally verbose checkout: prepare_linked_checkout: drop now-unused 'new' argument checkout: relocate --to's "no branch specified" check checkout: fix bug with --to and relative HEAD Documentation/git-worktree: add EXAMPLES section Documentation/git-worktree: add high-level 'lock' overview Documentation/git-worktree: split technical info from general description ...