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