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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
   3 <sect1 id="tsvn-dug-update">\r
   4         <title>Update Your Working Copy With Changes From Others</title>\r
   5         <indexterm>\r
   6                 <primary>update</primary>\r
   7         </indexterm>\r
   8         <indexterm>\r
   9                 <primary>fetch changes</primary>\r
  10         </indexterm>\r
  11         <para>\r
  12                 <figure id="tsvn-dug-update-dia-1">\r
  13                         <title>Progress dialog showing finished update</title>\r
  14                         <graphic fileref="../images/UpdateFinished.png"/>\r
  15                 </figure>\r
  16                 Periodically, you should ensure that changes done by others get\r
  17                 incorporated in your local working copy. The process of\r
  18                 getting changes from the server to your local copy is\r
  19                 known as <emphasis>updating</emphasis>. Updating may be done on\r
  20                 single files, a set of selected files, or recursively on\r
  21                 entire directory hierarchies. To update, select the files\r
  22                 and/or directories you want, <action>right click</action> and select\r
  23                 <menuchoice>\r
  24                         <guimenu>TortoiseGit</guimenu>\r
  25                         <guimenuitem>Update</guimenuitem>\r
  26                 </menuchoice>\r
  27                 in the explorer context menu. A window will pop up displaying the \r
  28                 progress of the update as it runs.\r
  29                 Changes done by others will be merged into your files,\r
  30                 keeping any changes you may have done to the same files.\r
  31                 The repository is <emphasis>not</emphasis> affected by an update.\r
  32         </para>\r
  33         <para>\r
  34                 The progress dialog uses colour coding to highlight different\r
  35                 update actions\r
  36                 <variablelist>\r
  37                         <varlistentry>\r
  38                                 <term>Purple</term>\r
  39                                 <listitem>\r
  40                                         <para>\r
  41                                         New item added to your WC.\r
  42                                         </para>\r
  43                                 </listitem>\r
  44                         </varlistentry>\r
  45                         <varlistentry>\r
  46                                 <term>Dark red</term>\r
  47                                 <listitem>\r
  48                                         <para>\r
  49                                         Redundant item deleted from your WC,\r
  50                                         or missing item replaced in your WC.\r
  51                                         </para>\r
  52                                 </listitem>\r
  53                         </varlistentry>\r
  54                         <varlistentry>\r
  55                                 <term>Green</term>\r
  56                                 <listitem>\r
  57                                         <para>\r
  58                                         Changes from repository successfully merged with your\r
  59                                         local changes.\r
  60                                         </para>\r
  61                                 </listitem>\r
  62                         </varlistentry>\r
  63                         <varlistentry>\r
  64                                 <term>Bright red</term>\r
  65                                 <listitem>\r
  66                                         <para>\r
  67                                         Changes from repository merged with local changes,\r
  68                                         resulting in conflicts which you need to resolve.\r
  69                                         </para>\r
  70                                 </listitem>\r
  71                         </varlistentry>\r
  72                         <varlistentry>\r
  73                                 <term>Black</term>\r
  74                                 <listitem>\r
  75                                         <para>\r
  76                                         Unchanged item in your WC updated with newer version\r
  77                                         from the repository.\r
  78                                         </para>\r
  79                                 </listitem>\r
  80                         </varlistentry>\r
  81                 </variablelist>\r
  82         </para>\r
  83         <para>\r
  84                 This is the default colour scheme, but you can customise those colours\r
  85                 using the settings dialog.\r
  86                 Read <xref linkend="tsvn-dug-settings-colours"/> for more information.\r
  87         </para>\r
  88         <para>\r
  89                 If you get any <emphasis>conflicts</emphasis> during an update (this\r
  90                 can happen if others changed the same lines in the same file as\r
  91                 you did and those changes don't match) then the dialog shows those\r
  92                 conflicts in red. You can <action>double click</action> on these lines\r
  93                 to start the external merge tool to resolve the conflicts.\r
  94         </para>\r
  95         <para>\r
  96                 When the update is complete, the progress dialog shows a summary of the\r
  97                 number of items updated, added, removed, conflicted, etc. below\r
  98                 the file list. This summary information can be copied to the clipboard\r
  99                 using <keycap>Ctrl+C</keycap>.\r
 100         </para>\r
 101         <?dbhh topicname="HIDD_UPDATE"?>\r
 102         <para>\r
 103                 The standard Update command has no options and just updates your\r
 104                 working copy to the HEAD revision of the repository, which is the\r
 105                 most common use case. If you want more control over the update\r
 106                 process, you should use\r
 107                 <menuchoice>\r
 108                         <guimenu>TortoiseGit</guimenu>\r
 109                         <guimenuitem>Update to Revision...</guimenuitem>\r
 110                 </menuchoice> instead.\r
 111                 This allows you to update your working copy to a specific\r
 112                 revision, not only to the most recent one.\r
 113                 Suppose your working copy is at revision 100, but you want it\r
 114                 to reflect the state which it had in revision 50 -\r
 115                 then simply update to revision 50.\r
 116                 In the same dialog you can also choose the <firstterm>depth</firstterm>\r
 117                 at which to update the current folder. The terms used are described\r
 118                 in <xref linkend="tsvn-dug-checkout-depth"/>. The default depth is\r
 119                 <guilabel>Working copy</guilabel>, which preserves the existing depth setting.\r
 120                 You can also choose whether to ignore any external projects in the update\r
 121                 (i.e. projects referenced using <literal>svn:externals</literal>).\r
 122         </para>\r
 123         <caution>\r
 124                 <para>\r
 125                         If you update a file or folder to a specific revision, you should not\r
 126                         make changes to those files. You will get <quote>out of date</quote>\r
 127                         error messages when you try to commit them!\r
 128                         If you want to undo changes to a file and start afresh from an earlier\r
 129                         revision, you can rollback to a previous revision from the revision log\r
 130                         dialog. Take a look at <xref linkend="tsvn-howto-rollback"/> for\r
 131                         further instructions, and alternative methods.\r
 132                 </para>\r
 133         </caution>\r
 134         <para>\r
 135                 <menuchoice>\r
 136                         <guimenuitem>Update to Revision</guimenuitem>\r
 137                 </menuchoice>\r
 138                 can occasionally be useful to see what your project looked like at\r
 139                 some earlier point in its history.\r
 140                 But in general, updating individual files to an earlier revision is\r
 141                 not a good idea as it leaves your working copy in an inconsistent\r
 142                 state. If the file you are updating has changed name, you may even\r
 143                 find that the file just disappears from your working copy because\r
 144                 no file of that name existed in the earlier revision. You should\r
 145                 also note that the item will show a normal green overlay, so it is\r
 146                 indistinguishable from files which are up-to-date.\r
 147         </para>\r
 148         <para>\r
 149                 If you simply want a local copy of an old version of a file it is\r
 150                 better to use the\r
 151                 <menuchoice>\r
 152                         <guimenu>Context Menu</guimenu>\r
 153                         <guimenuitem>Save revision to...</guimenuitem>\r
 154                 </menuchoice>\r
 155                 command from the log dialog for that file.\r
 156         </para>\r
 157         <tip>\r
 158                 <title>Multiple Files/Folders</title>\r
 159                 <para>\r
 160                         If you select multiple files and folders in the explorer and then select\r
 161                         <menuchoice>\r
 162                                 <guimenuitem>Update</guimenuitem>\r
 163                         </menuchoice>,\r
 164                         all of those files/folders\r
 165                         are updated one by one. TortoiseGit makes sure that all files/folders\r
 166                         which are from the same repository are updated to the exact same\r
 167                         revision! Even if between those updates another commit occurred.\r
 168                 </para>\r
 169         </tip>\r
 170         <tip>\r
 171                 <title>Local File Already Exists</title>\r
 172                 <para>\r
 173                         Sometimes when you try to update, the update fails with a message to\r
 174                         say that there is already a local file of the same name. This typically\r
 175                         happens when Git tries to checkout a newly versioned file, and finds\r
 176                         that an unversioned file of the same name already exists in your working\r
 177                         folder. Git will never overwrite an unversioned file - it might\r
 178                         contain something you are working on, which coincidentally has the same\r
 179                         filename as another developer has used for his newly committed file. \r
 180                 </para>\r
 181                 <para>\r
 182                         If you get this error message, the solution is simply to rename the local\r
 183                         unversioned file. After completing the update, you can check whether\r
 184                         the renamed file is still needed.\r
 185                 </para>\r
 186                 <para>\r
 187                         If you keep getting error messages, use\r
 188                         <menuchoice>\r
 189                                 <guimenu>TortoiseGit</guimenu>\r
 190                                 <guimenuitem>Check for Modifications</guimenuitem>\r
 191                         </menuchoice>\r
 192                         instead to list all the problem files. That way you can deal with them\r
 193                         all at once.\r
 194                 </para>\r
 195         </tip>\r
 196 </sect1>\r