| blob | ab79195599fc52faffb1a149c5fe76e856973d89 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect1 id="tgit-dug-checkout">\r
4 <title>Checking Out A Working Tree (Switch to commit)</title>\r
5 <indexterm>\r
6 <primary>checkout</primary>\r
7 </indexterm>\r
8 <indexterm>\r
9 <primary>Switch</primary>\r
10 </indexterm>\r
11 <indexterm>\r
12 <primary>create working tree</primary>\r
13 </indexterm>\r
14 <?dbhh topicname="HIDD_GITSWITCH"?>\r
15 <para>\r
16 The Switch/Checkout dialog can be used to checkout a specific version to the working tree (i.e., all files are updated to match their state of the selected version). Normally, a specific version will be represented by a (local) branch which is set as the current branch (cf. <xref linkend="tgit-dug-branchtag"/> and <xref linkend="repositories-and-branches"/>).\r
17 </para>\r
18 <para>\r
19 Select a git repository directory in windows explorer\r
20 <action>Right click</action> to pop up the\r
21 context menu and select the command\r
22 <menuchoice>\r
23 <guimenu>TortoiseGit</guimenu>\r
24 <guimenuitem>Switch/Checkout...</guimenuitem>\r
25 </menuchoice>,\r
26 which brings up the following dialog box:\r
27 <figure id="tgit-dug-checkout-dia-1">\r
28 <title>The Switch/Checkout dialog</title>\r
29 <graphic fileref="../images/SwitchCheckOut.png"/>\r
30 </figure>\r
31 If you enter a branch name at <guilabel>Create New Branch</guilabel>, a new branch will be created. Also, the new branch will be set as the current branch (HEAD).\r
32 </para>\r
33 <para>\r
34 You can click on the <guibutton>...</guibutton> to browse the references/branches/log to choose a branch to checkout.\r
35 </para>\r
36 <para>\r
37 Check <guilabel>Force</guilabel> will overwrite uncommitted changes in the working tree with the selected version.\r
38 </para>\r
39 <para>\r
40 When you selected a remote branch, you can check <guilabel>Track</guilabel> in order to track the remote branch.\r
41 When you open the pull or sync dialog, the remote branch will be pre-selected automatically.\r
42 </para>\r
43 <!--\r
44 <sect2 id="tgit-dug-checkout-depth">\r
45 <title>Checkout Depth</title>\r
46 <para>\r
47 You can choose the <firstterm>depth</firstterm> you want to checkout,\r
48 which allows you to specify the depth of recursion into child folders.\r
49 If you want just a few sections of a large tree, You can checkout\r
50 the top level folder only, then update selected folders recursively.\r
51 <variablelist>\r
52 <varlistentry>\r
53 <term>Fully recursive</term>\r
54 <listitem>\r
55 <para>\r
56 Checkout the entire tree, including all child folders\r
57 and sub-folders.\r
58 </para>\r
59 </listitem>\r
60 </varlistentry>\r
61 <varlistentry>\r
62 <term>Immediate children, including folders</term>\r
63 <listitem>\r
64 <para>\r
65 Checkout the specified directory, including all files\r
66 and child folders, but do not populate the child folders.\r
67 </para>\r
68 </listitem>\r
69 </varlistentry>\r
70 <varlistentry>\r
71 <term>Only file children</term>\r
72 <listitem>\r
73 <para>\r
74 Checkout the specified directory, including all files\r
75 but do not checkout any child folders.\r
76 </para>\r
77 </listitem>\r
78 </varlistentry>\r
79 <varlistentry>\r
80 <term>Only this item</term>\r
81 <listitem>\r
82 <para>\r
83 Checkout the directory only. Do not populate it with\r
84 files or child folders.\r
85 </para>\r
86 </listitem>\r
87 </varlistentry>\r
88 <varlistentry>\r
89 <term>Working tree</term>\r
90 <listitem>\r
91 <para>\r
92 Retain the depth specified in the working tree. This\r
93 option is not used in the checkout dialog, but it is\r
94 the default in all other dialogs which have a depth\r
95 setting.\r
96 </para>\r
97 </listitem>\r
98 </varlistentry>\r
99 </variablelist>\r
100 </para>\r
101 <para>\r
102 If you check out a sparse working tree (i.e., by choosing something other\r
103 than <literal>fully recursive</literal> for the checkout depth), you can\r
104 fetch additional sub-folders by using the repository browser\r
105 (<xref linkend="tgit-dug-repobrowser" />) or the check for modifications dialog\r
106 (<xref linkend="tgit-dug-wcstatus-2" />).\r
107 </para>\r
108 <para>\r
109 In the repository browser,\r
110 <action>Right click</action> on the checked out folder, then use\r
111 <menuchoice>\r
112 <guimenu>TortoiseGit</guimenu>\r
113 <guimenuitem>Repo-Browser</guimenuitem>\r
114 </menuchoice>\r
115 to bring up the repository browser. Find the sub-folder you would like\r
116 to add to your working tree, then use\r
117 <menuchoice>\r
118 <guimenu>Context menu</guimenu>\r
119 <guimenuitem>Update item to revision...</guimenuitem>\r
120 </menuchoice>\r
121 That menu will only be visible if the selected item does not exist yet\r
122 in your working tree, but the parent item does exist.\r
123 </para>\r
124 <para>\r
125 In the check for modifications dialog, first click on the button\r
126 <guibutton>Check repository</guibutton>. The dialog will show all\r
127 the files and folders which are in the repository but which you\r
128 have not checked out as <literal>remotely added</literal>.\r
129 <action>Right click</action> on the folder(s) you would like to add\r
130 to your working tree, then use\r
131 <menuchoice>\r
132 <guimenu>Context menu</guimenu>\r
133 <guimenuitem>Update</guimenuitem>\r
134 </menuchoice>.\r
135 </para>\r
136 <para>\r
137 This feature is very useful when you only want to checkout parts of a\r
138 large tree, but you want the convenience of updating a single working\r
139 copy. Suppose you have a large tree which has sub-folders\r
140 <literal>Project01</literal> to <literal>Project99</literal>,\r
141 and you only want to checkout\r
142 <literal>Project03</literal>,\r
143 <literal>Project25</literal> and\r
144 <literal>Project76/SubProj</literal>.\r
145 Use these steps:\r
146 </para>\r
147 <orderedlist>\r
148 <listitem>\r
149 <para>\r
150 Checkout the parent folder with depth\r
151 <quote>Only this item</quote>\r
152 You now have an empty top level folder.\r
153 </para>\r
154 </listitem>\r
155 <listitem>\r
156 <para>\r
157 Select the new folder and use\r
158 <menuchoice>\r
159 <guimenu>TortoiseGit</guimenu>\r
160 <guimenuitem>Repo browser</guimenuitem>\r
161 </menuchoice>\r
162 to display the repository content.\r
163 </para>\r
164 </listitem>\r
165 <listitem>\r
166 <para>\r
167 Right click on <literal>Project03</literal> and\r
168 <menuchoice>\r
169 <guimenu>Context menu</guimenu>\r
170 <guimenuitem>Update item to revision...</guimenuitem>\r
171 </menuchoice>.\r
172 Keep the default settings and click on\r
173 <guibutton>OK</guibutton>. You now have\r
174 that folder fully populated.\r
175 </para>\r
176 <para>\r
177 Repeat the same process for <literal>Project25</literal>.\r
178 </para>\r
179 </listitem>\r
180 <listitem>\r
181 <para>\r
182 Navigate to <literal>Project76/SubProj</literal> and\r
183 do the same. This time note that the <literal>Project76</literal>\r
184 folder has no content except for <literal>SubProj</literal>,\r
185 which itself is fully populated. Git has created the\r
186 intermediate folders for you without populating them.\r
187 </para>\r
188 </listitem>\r
189 </orderedlist>\r
190 <tip>\r
191 <title>Working tree depth cannot be reduced</title>\r
192 <para>\r
193 Once you have checked out a working tree to a particular\r
194 depth you can increase that depth later to get more content.\r
195 However you cannot reduce the depth again to remove content.\r
196 That feature may be added in a later version of Git.\r
197 </para>\r
198 </tip>\r
199 <tip>\r
200 <title>Using an older server</title>\r
201 <para>\r
202 Pre-1.5 servers do not understand the working tree depth\r
203 request, so they cannot always deal with requests efficiently.\r
204 The command will still work, but an older server may send all\r
205 the data, leaving the client to filter out what is not required,\r
206 which may mean a lot of network traffic. If possible you should\r
207 upgrade your server to 1.5.\r
208 </para>\r
209 </tip>\r
210 </sect2>\r
211 -->\r
212 <!--\r
213 <para>\r
214 If the project contains references to external projects which you do\r
215 <emphasis>not</emphasis> want checked out at the same time, use the\r
216 <guilabel>Omit externals</guilabel> checkbox.\r
217 </para>\r
218 -->\r
219 <important>\r
220 <para>\r
221 If you checkout/switch to a <guilabel>Tag</guilabel> or <guilabel>Commit</guilabel>,\r
222 you should create a new branch. Otherwise you will\r
223 work at "no branch" (detached HEAD state; i.e., there is no current branch, cf. <xref linkend="git-checkout(1)__detached_head"/>).\r
224 This can be easily fixed by creating a branch at this version and switching to it.\r
225 </para>\r
226 </important>\r
227 \r
228 <tip>\r
229 <title>Exporting</title>\r
230 <para>\r
231 Sometimes you may want to create a local copy without any of those\r
232 <filename>.git</filename> directories, e.g. to create a zipped\r
233 tarball of your source.\r
234 Read <xref linkend="tgit-dug-export"/> to find out how to do that.\r
235 </para>\r
236 </tip>\r
237 </sect1>\r