doc/source/en/TortoiseGit/tsvn_dug/dug_checkout.xml

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