]>
Commit | Line | Data |
---|---|---|
1 | git-switch(1) | |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-switch - Switch branches | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'git switch' [<options>] [--no-guess] <branch> | |
12 | 'git switch' [<options>] --detach [<start-point>] | |
13 | 'git switch' [<options>] (-c|-C) <new-branch> [<start-point>] | |
14 | 'git switch' [<options>] --orphan <new-branch> | |
15 | ||
16 | DESCRIPTION | |
17 | ----------- | |
18 | Switch to a specified branch. The working tree and the index are | |
19 | updated to match the branch. All new commits will be added to the tip | |
20 | of this branch. | |
21 | ||
22 | Optionally a new branch could be created with either `-c`, `-C`, | |
23 | automatically from a remote branch of same name (see `--guess`), or | |
24 | detach the working tree from any branch with `--detach`, along with | |
25 | switching. | |
26 | ||
27 | Switching branches does not require a clean index and working tree | |
28 | (i.e. no differences compared to `HEAD`). The operation is aborted | |
29 | however if the operation leads to loss of local changes, unless told | |
30 | otherwise with `--discard-changes` or `--merge`. | |
31 | ||
32 | THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. | |
33 | ||
34 | OPTIONS | |
35 | ------- | |
36 | <branch>:: | |
37 | Branch to switch to. | |
38 | ||
39 | <new-branch>:: | |
40 | Name for the new branch. | |
41 | ||
42 | <start-point>:: | |
43 | The starting point for the new branch. Specifying a | |
44 | `<start-point>` allows you to create a branch based on some | |
45 | other point in history than where HEAD currently points. (Or, | |
46 | in the case of `--detach`, allows you to inspect and detach | |
47 | from some other point.) | |
48 | + | |
49 | You can use the `@{-N}` syntax to refer to the N-th last | |
50 | branch/commit switched to using "git switch" or "git checkout" | |
51 | operation. You may also specify `-` which is synonymous to `@{-1}`. | |
52 | This is often used to switch quickly between two branches, or to undo | |
53 | a branch switch by mistake. | |
54 | + | |
55 | As a special case, you may use `A...B` as a shortcut for the merge | |
56 | base of `A` and `B` if there is exactly one merge base. You can leave | |
57 | out at most one of `A` and `B`, in which case it defaults to `HEAD`. | |
58 | ||
59 | -c <new-branch>:: | |
60 | --create <new-branch>:: | |
61 | Create a new branch named `<new-branch>` starting at | |
62 | `<start-point>` before switching to the branch. This is the | |
63 | transactional equivalent of | |
64 | + | |
65 | ------------ | |
66 | $ git branch <new-branch> | |
67 | $ git switch <new-branch> | |
68 | ------------ | |
69 | + | |
70 | that is to say, the branch is not reset/created unless "git switch" is | |
71 | successful (e.g., when the branch is in use in another worktree, not | |
72 | just the current branch stays the same, but the branch is not reset to | |
73 | the start-point, either). | |
74 | ||
75 | -C <new-branch>:: | |
76 | --force-create <new-branch>:: | |
77 | Similar to `--create` except that if `<new-branch>` already | |
78 | exists, it will be reset to `<start-point>`. This is a | |
79 | convenient shortcut for: | |
80 | + | |
81 | ------------ | |
82 | $ git branch -f <new-branch> | |
83 | $ git switch <new-branch> | |
84 | ------------ | |
85 | ||
86 | -d:: | |
87 | --detach:: | |
88 | Switch to a commit for inspection and discardable | |
89 | experiments. See the "DETACHED HEAD" section in | |
90 | linkgit:git-checkout[1] for details. | |
91 | ||
92 | --guess:: | |
93 | --no-guess:: | |
94 | If `<branch>` is not found but there does exist a tracking | |
95 | branch in exactly one remote (call it `<remote>`) with a | |
96 | matching name, treat as equivalent to | |
97 | + | |
98 | ------------ | |
99 | $ git switch -c <branch> --track <remote>/<branch> | |
100 | ------------ | |
101 | + | |
102 | If the branch exists in multiple remotes and one of them is named by | |
103 | the `checkout.defaultRemote` configuration variable, we'll use that | |
104 | one for the purposes of disambiguation, even if the `<branch>` isn't | |
105 | unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` | |
106 | to always checkout remote branches from there if `<branch>` is | |
107 | ambiguous but exists on the 'origin' remote. See also | |
108 | `checkout.defaultRemote` in linkgit:git-config[1]. | |
109 | + | |
110 | `--guess` is the default behavior. Use `--no-guess` to disable it. | |
111 | + | |
112 | The default behavior can be set via the `checkout.guess` configuration | |
113 | variable. | |
114 | ||
115 | -f:: | |
116 | --force:: | |
117 | An alias for `--discard-changes`. | |
118 | ||
119 | --discard-changes:: | |
120 | Proceed even if the index or the working tree differs from | |
121 | `HEAD`. Both the index and working tree are restored to match | |
122 | the switching target. If `--recurse-submodules` is specified, | |
123 | submodule content is also restored to match the switching | |
124 | target. This is used to throw away local changes. | |
125 | ||
126 | -m:: | |
127 | --merge:: | |
128 | If you have local modifications to one or more files that are | |
129 | different between the current branch and the branch to which | |
130 | you are switching, the command refuses to switch branches in | |
131 | order to preserve your modifications in context. However, | |
132 | with this option, a three-way merge between the current | |
133 | branch, your working tree contents, and the new branch is | |
134 | done, and you will be on the new branch. | |
135 | + | |
136 | When a merge conflict happens, the index entries for conflicting | |
137 | paths are left unmerged, and you need to resolve the conflicts | |
138 | and mark the resolved paths with `git add` (or `git rm` if the merge | |
139 | should result in deletion of the path). | |
140 | ||
141 | --conflict=<style>:: | |
142 | The same as `--merge` option above, but changes the way the | |
143 | conflicting hunks are presented, overriding the | |
144 | `merge.conflictStyle` configuration variable. Possible values are | |
145 | "merge" (default), "diff3", and "zdiff3". | |
146 | ||
147 | -q:: | |
148 | --quiet:: | |
149 | Quiet, suppress feedback messages. | |
150 | ||
151 | --progress:: | |
152 | --no-progress:: | |
153 | Progress status is reported on the standard error stream | |
154 | by default when it is attached to a terminal, unless `--quiet` | |
155 | is specified. This flag enables progress reporting even if not | |
156 | attached to a terminal, regardless of `--quiet`. | |
157 | ||
158 | -t:: | |
159 | --track [direct|inherit]:: | |
160 | When creating a new branch, set up "upstream" configuration. | |
161 | `-c` is implied. See `--track` in linkgit:git-branch[1] for | |
162 | details. | |
163 | + | |
164 | If no `-c` option is given, the name of the new branch will be derived | |
165 | from the remote-tracking branch, by looking at the local part of the | |
166 | refspec configured for the corresponding remote, and then stripping | |
167 | the initial part up to the "*". This would tell us to use `hack` as | |
168 | the local branch when branching off of `origin/hack` (or | |
169 | `remotes/origin/hack`, or even `refs/remotes/origin/hack`). If the | |
170 | given name has no slash, or the above guessing results in an empty | |
171 | name, the guessing is aborted. You can explicitly give a name with | |
172 | `-c` in such a case. | |
173 | ||
174 | --no-track:: | |
175 | Do not set up "upstream" configuration, even if the | |
176 | `branch.autoSetupMerge` configuration variable is true. | |
177 | ||
178 | --orphan <new-branch>:: | |
179 | Create a new unborn branch, named `<new-branch>`. All | |
180 | tracked files are removed. | |
181 | ||
182 | --ignore-other-worktrees:: | |
183 | `git switch` refuses when the wanted ref is already | |
184 | checked out by another worktree. This option makes it check | |
185 | the ref out anyway. In other words, the ref can be held by | |
186 | more than one worktree. | |
187 | ||
188 | --recurse-submodules:: | |
189 | --no-recurse-submodules:: | |
190 | Using `--recurse-submodules` will update the content of all | |
191 | active submodules according to the commit recorded in the | |
192 | superproject. If nothing (or `--no-recurse-submodules`) is | |
193 | used, submodules working trees will not be updated. Just | |
194 | like linkgit:git-submodule[1], this will detach `HEAD` of the | |
195 | submodules. | |
196 | ||
197 | EXAMPLES | |
198 | -------- | |
199 | ||
200 | The following command switches to the "master" branch: | |
201 | ||
202 | ------------ | |
203 | $ git switch master | |
204 | ------------ | |
205 | ||
206 | After working in the wrong branch, switching to the correct branch | |
207 | would be done using: | |
208 | ||
209 | ------------ | |
210 | $ git switch mytopic | |
211 | ------------ | |
212 | ||
213 | However, your "wrong" branch and correct "mytopic" branch may differ | |
214 | in files that you have modified locally, in which case the above | |
215 | switch would fail like this: | |
216 | ||
217 | ------------ | |
218 | $ git switch mytopic | |
219 | error: You have local changes to 'frotz'; not switching branches. | |
220 | ------------ | |
221 | ||
222 | You can give the `-m` flag to the command, which would try a three-way | |
223 | merge: | |
224 | ||
225 | ------------ | |
226 | $ git switch -m mytopic | |
227 | Auto-merging frotz | |
228 | ------------ | |
229 | ||
230 | After this three-way merge, the local modifications are _not_ | |
231 | registered in your index file, so `git diff` would show you what | |
232 | changes you made since the tip of the new branch. | |
233 | ||
234 | To switch back to the previous branch before we switched to mytopic | |
235 | (i.e. "master" branch): | |
236 | ||
237 | ------------ | |
238 | $ git switch - | |
239 | ------------ | |
240 | ||
241 | You can grow a new branch from any commit. For example, switch to | |
242 | "HEAD~3" and create branch "fixup": | |
243 | ||
244 | ------------ | |
245 | $ git switch -c fixup HEAD~3 | |
246 | Switched to a new branch 'fixup' | |
247 | ------------ | |
248 | ||
249 | If you want to start a new branch from a remote branch of the same | |
250 | name: | |
251 | ||
252 | ------------ | |
253 | $ git switch new-topic | |
254 | Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin' | |
255 | Switched to a new branch 'new-topic' | |
256 | ------------ | |
257 | ||
258 | To check out commit `HEAD~3` for temporary inspection or experiment | |
259 | without creating a new branch: | |
260 | ||
261 | ------------ | |
262 | $ git switch --detach HEAD~3 | |
263 | HEAD is now at 9fc9555312 Merge branch 'cc/shared-index-permbits' | |
264 | ------------ | |
265 | ||
266 | If it turns out whatever you have done is worth keeping, you can | |
267 | always create a new name for it (without switching away): | |
268 | ||
269 | ------------ | |
270 | $ git switch -c good-surprises | |
271 | ------------ | |
272 | ||
273 | CONFIGURATION | |
274 | ------------- | |
275 | ||
276 | include::includes/cmd-config-section-all.txt[] | |
277 | ||
278 | include::config/checkout.txt[] | |
279 | ||
280 | SEE ALSO | |
281 | -------- | |
282 | linkgit:git-checkout[1], | |
283 | linkgit:git-branch[1] | |
284 | ||
285 | GIT | |
286 | --- | |
287 | Part of the linkgit:git[1] suite |