]>
Commit | Line | Data |
---|---|---|
d787d311 NTND |
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 | ||
4e43b7ff NTND |
32 | THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. |
33 | ||
d787d311 NTND |
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 a | |
63 | convenient shortcut for: | |
64 | + | |
65 | ------------ | |
66 | $ git branch <new-branch> | |
67 | $ git switch <new-branch> | |
68 | ------------ | |
69 | ||
70 | -C <new-branch>:: | |
71 | --force-create <new-branch>:: | |
72 | Similar to `--create` except that if `<new-branch>` already | |
73 | exists, it will be reset to `<start-point>`. This is a | |
74 | convenient shortcut for: | |
75 | + | |
76 | ------------ | |
77 | $ git branch -f <new-branch> | |
78 | $ git switch <new-branch> | |
79 | ------------ | |
80 | ||
81 | -d:: | |
82 | --detach:: | |
83 | Switch to a commit for inspection and discardable | |
84 | experiments. See the "DETACHED HEAD" section in | |
85 | linkgit:git-checkout[1] for details. | |
86 | ||
87 | --guess:: | |
88 | --no-guess:: | |
89 | If `<branch>` is not found but there does exist a tracking | |
90 | branch in exactly one remote (call it `<remote>`) with a | |
91 | matching name, treat as equivalent to | |
92 | + | |
93 | ------------ | |
94 | $ git switch -c <branch> --track <remote>/<branch> | |
95 | ------------ | |
96 | + | |
97 | If the branch exists in multiple remotes and one of them is named by | |
98 | the `checkout.defaultRemote` configuration variable, we'll use that | |
99 | one for the purposes of disambiguation, even if the `<branch>` isn't | |
100 | unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` | |
101 | to always checkout remote branches from there if `<branch>` is | |
102 | ambiguous but exists on the 'origin' remote. See also | |
103 | `checkout.defaultRemote` in linkgit:git-config[1]. | |
104 | + | |
105 | `--guess` is the default behavior. Use `--no-guess` to disable it. | |
64f1f58f DL |
106 | + |
107 | The default behavior can be set via the `checkout.guess` configuration | |
108 | variable. | |
d787d311 NTND |
109 | |
110 | -f:: | |
111 | --force:: | |
112 | An alias for `--discard-changes`. | |
113 | ||
114 | --discard-changes:: | |
115 | Proceed even if the index or the working tree differs from | |
116 | `HEAD`. Both the index and working tree are restored to match | |
117 | the switching target. If `--recurse-submodules` is specified, | |
118 | submodule content is also restored to match the switching | |
119 | target. This is used to throw away local changes. | |
120 | ||
121 | -m:: | |
122 | --merge:: | |
123 | If you have local modifications to one or more files that are | |
124 | different between the current branch and the branch to which | |
125 | you are switching, the command refuses to switch branches in | |
126 | order to preserve your modifications in context. However, | |
127 | with this option, a three-way merge between the current | |
128 | branch, your working tree contents, and the new branch is | |
129 | done, and you will be on the new branch. | |
130 | + | |
131 | When a merge conflict happens, the index entries for conflicting | |
132 | paths are left unmerged, and you need to resolve the conflicts | |
133 | and mark the resolved paths with `git add` (or `git rm` if the merge | |
134 | should result in deletion of the path). | |
135 | ||
136 | --conflict=<style>:: | |
137 | The same as `--merge` option above, but changes the way the | |
138 | conflicting hunks are presented, overriding the | |
139 | `merge.conflictStyle` configuration variable. Possible values are | |
ddfc44a8 | 140 | "merge" (default), "diff3", and "zdiff3". |
d787d311 NTND |
141 | |
142 | -q:: | |
143 | --quiet:: | |
144 | Quiet, suppress feedback messages. | |
145 | ||
146 | --progress:: | |
147 | --no-progress:: | |
148 | Progress status is reported on the standard error stream | |
149 | by default when it is attached to a terminal, unless `--quiet` | |
150 | is specified. This flag enables progress reporting even if not | |
151 | attached to a terminal, regardless of `--quiet`. | |
152 | ||
153 | -t:: | |
d3115660 | 154 | --track [direct|inherit]:: |
d787d311 NTND |
155 | When creating a new branch, set up "upstream" configuration. |
156 | `-c` is implied. See `--track` in linkgit:git-branch[1] for | |
157 | details. | |
158 | + | |
159 | If no `-c` option is given, the name of the new branch will be derived | |
160 | from the remote-tracking branch, by looking at the local part of the | |
161 | refspec configured for the corresponding remote, and then stripping | |
162 | the initial part up to the "*". This would tell us to use `hack` as | |
163 | the local branch when branching off of `origin/hack` (or | |
164 | `remotes/origin/hack`, or even `refs/remotes/origin/hack`). If the | |
165 | given name has no slash, or the above guessing results in an empty | |
166 | name, the guessing is aborted. You can explicitly give a name with | |
167 | `-c` in such a case. | |
168 | ||
169 | --no-track:: | |
170 | Do not set up "upstream" configuration, even if the | |
171 | `branch.autoSetupMerge` configuration variable is true. | |
172 | ||
173 | --orphan <new-branch>:: | |
174 | Create a new 'orphan' branch, named `<new-branch>`. All | |
175 | tracked files are removed. | |
176 | ||
177 | --ignore-other-worktrees:: | |
178 | `git switch` refuses when the wanted ref is already | |
179 | checked out by another worktree. This option makes it check | |
180 | the ref out anyway. In other words, the ref can be held by | |
181 | more than one worktree. | |
182 | ||
183 | --recurse-submodules:: | |
184 | --no-recurse-submodules:: | |
185 | Using `--recurse-submodules` will update the content of all | |
acbfae32 | 186 | active submodules according to the commit recorded in the |
d787d311 | 187 | superproject. If nothing (or `--no-recurse-submodules`) is |
b3cec573 | 188 | used, submodules working trees will not be updated. Just |
d787d311 NTND |
189 | like linkgit:git-submodule[1], this will detach `HEAD` of the |
190 | submodules. | |
191 | ||
192 | EXAMPLES | |
193 | -------- | |
194 | ||
195 | The following command switches to the "master" branch: | |
196 | ||
197 | ------------ | |
198 | $ git switch master | |
199 | ------------ | |
200 | ||
201 | After working in the wrong branch, switching to the correct branch | |
202 | would be done using: | |
203 | ||
204 | ------------ | |
205 | $ git switch mytopic | |
206 | ------------ | |
207 | ||
208 | However, your "wrong" branch and correct "mytopic" branch may differ | |
209 | in files that you have modified locally, in which case the above | |
210 | switch would fail like this: | |
211 | ||
212 | ------------ | |
213 | $ git switch mytopic | |
214 | error: You have local changes to 'frotz'; not switching branches. | |
215 | ------------ | |
216 | ||
217 | You can give the `-m` flag to the command, which would try a three-way | |
218 | merge: | |
219 | ||
220 | ------------ | |
221 | $ git switch -m mytopic | |
222 | Auto-merging frotz | |
223 | ------------ | |
224 | ||
225 | After this three-way merge, the local modifications are _not_ | |
226 | registered in your index file, so `git diff` would show you what | |
227 | changes you made since the tip of the new branch. | |
228 | ||
229 | To switch back to the previous branch before we switched to mytopic | |
230 | (i.e. "master" branch): | |
231 | ||
232 | ------------ | |
233 | $ git switch - | |
234 | ------------ | |
235 | ||
236 | You can grow a new branch from any commit. For example, switch to | |
237 | "HEAD~3" and create branch "fixup": | |
238 | ||
239 | ------------ | |
240 | $ git switch -c fixup HEAD~3 | |
241 | Switched to a new branch 'fixup' | |
242 | ------------ | |
243 | ||
244 | If you want to start a new branch from a remote branch of the same | |
245 | name: | |
246 | ||
247 | ------------ | |
248 | $ git switch new-topic | |
249 | Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin' | |
250 | Switched to a new branch 'new-topic' | |
251 | ------------ | |
252 | ||
253 | To check out commit `HEAD~3` for temporary inspection or experiment | |
254 | without creating a new branch: | |
255 | ||
256 | ------------ | |
257 | $ git switch --detach HEAD~3 | |
258 | HEAD is now at 9fc9555312 Merge branch 'cc/shared-index-permbits' | |
259 | ------------ | |
260 | ||
261 | If it turns out whatever you have done is worth keeping, you can | |
262 | always create a new name for it (without switching away): | |
263 | ||
264 | ------------ | |
265 | $ git switch -c good-surprises | |
266 | ------------ | |
267 | ||
268 | SEE ALSO | |
269 | -------- | |
270 | linkgit:git-checkout[1], | |
271 | linkgit:git-branch[1] | |
272 | ||
273 | GIT | |
274 | --- | |
275 | Part of the linkgit:git[1] suite |