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