<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-dug-update">
	<title>Update Your Working Copy With Changes From Others</title>
	<indexterm>
		<primary>update</primary>
	</indexterm>
	<indexterm>
		<primary>fetch changes</primary>
	</indexterm>
	<para>
		<figure id="tsvn-dug-update-dia-1">
			<title>Progress dialog showing finished update</title>
			<graphic fileref="../images/UpdateFinished.png"/>
		</figure>
		Periodically, you should ensure that changes done by others get
		incorporated in your local working copy. The process of
		getting changes from the server to your local copy is
		known as <emphasis>updating</emphasis>. Updating may be done on
		single files, a set of selected files, or recursively on
		entire directory hierarchies. To update, select the files
		and/or directories you want, <action>right click</action> and select
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Update</guimenuitem>
		</menuchoice>
		in the explorer context menu. A window will pop up displaying the 
		progress of the update as it runs.
		Changes done by others will be merged into your files,
		keeping any changes you may have done to the same files.
		The repository is <emphasis>not</emphasis> affected by an update.
	</para>
	<para>
		The progress dialog uses colour coding to highlight different
		update actions
		<variablelist>
			<varlistentry>
				<term>Purple</term>
				<listitem>
					<para>
					New item added to your WC.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Dark red</term>
				<listitem>
					<para>
					Redundant item deleted from your WC,
					or missing item replaced in your WC.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Green</term>
				<listitem>
					<para>
					Changes from repository successfully merged with your
					local changes.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Bright red</term>
				<listitem>
					<para>
					Changes from repository merged with local changes,
					resulting in conflicts which you need to resolve.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Black</term>
				<listitem>
					<para>
					Unchanged item in your WC updated with newer version
					from the repository.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</para>
	<para>
		This is the default colour scheme, but you can customise those colours
		using the settings dialog.
		Read <xref linkend="tsvn-dug-settings-colours"/> for more information.
	</para>
	<para>
		If you get any <emphasis>conflicts</emphasis> during an update (this
		can happen if others changed the same lines in the same file as
		you did and those changes don't match) then the dialog shows those
		conflicts in red. You can <action>double click</action> on these lines
		to start the external merge tool to resolve the conflicts.
	</para>
	<para>
		When the update is complete, the progress dialog shows a summary of the
		number of items updated, added, removed, conflicted, etc. below
		the file list. This summary information can be copied to the clipboard
		using <keycap>Ctrl+C</keycap>.
	</para>
	<?dbhh topicname="HIDD_UPDATE"?>
	<para>
		The standard Update command has no options and just updates your
		working copy to the HEAD revision of the repository, which is the
		most common use case. If you want more control over the update
		process, you should use
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Update to Revision...</guimenuitem>
		</menuchoice> instead.
		This allows you to update your working copy to a specific
		revision, not only to the most recent one.
		Suppose your working copy is at revision 100, but you want it
		to reflect the state which it had in revision 50 -
		then simply update to revision 50.
		In the same dialog you can also choose the <firstterm>depth</firstterm>
		at which to update the current folder. The terms used are described
		in <xref linkend="tsvn-dug-checkout-depth"/>. The default depth is
		<guilabel>Working copy</guilabel>, which preserves the existing depth setting.
		You can also choose whether to ignore any external projects in the update
		(i.e. projects referenced using <literal>svn:externals</literal>).
	</para>
	<caution>
		<para>
			If you update a file or folder to a specific revision, you should not
			make changes to those files. You will get <quote>out of date</quote>
			error messages when you try to commit them!
			If you want to undo changes to a file and start afresh from an earlier
			revision, you can rollback to a previous revision from the revision log
			dialog. Take a look at <xref linkend="tsvn-howto-rollback"/> for
			further instructions, and alternative methods.
		</para>
	</caution>
	<para>
		<menuchoice>
			<guimenuitem>Update to Revision</guimenuitem>
		</menuchoice>
		can occasionally be useful to see what your project looked like at
		some earlier point in its history.
		But in general, updating individual files to an earlier revision is
		not a good idea as it leaves your working copy in an inconsistent
		state. If the file you are updating has changed name, you may even
		find that the file just disappears from your working copy because
		no file of that name existed in the earlier revision. You should
		also note that the item will show a normal green overlay, so it is
		indistinguishable from files which are up-to-date.
	</para>
	<para>
		If you simply want a local copy of an old version of a file it is
		better to use the
		<menuchoice>
			<guimenu>Context Menu</guimenu>
			<guimenuitem>Save revision to...</guimenuitem>
		</menuchoice>
		command from the log dialog for that file.
	</para>
	<tip>
		<title>Multiple Files/Folders</title>
		<para>
			If you select multiple files and folders in the explorer and then select
			<menuchoice>
				<guimenuitem>Update</guimenuitem>
			</menuchoice>,
			all of those files/folders
			are updated one by one. TortoiseGit makes sure that all files/folders
			which are from the same repository are updated to the exact same
			revision! Even if between those updates another commit occurred.
		</para>
	</tip>
	<tip>
		<title>Local File Already Exists</title>
		<para>
			Sometimes when you try to update, the update fails with a message to
			say that there is already a local file of the same name. This typically
			happens when Git tries to checkout a newly versioned file, and finds
			that an unversioned file of the same name already exists in your working
			folder. Git will never overwrite an unversioned file - it might
			contain something you are working on, which coincidentally has the same
			filename as another developer has used for his newly committed file. 
		</para>
		<para>
			If you get this error message, the solution is simply to rename the local
			unversioned file. After completing the update, you can check whether
			the renamed file is still needed.
		</para>
		<para>
			If you keep getting error messages, use
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Check for Modifications</guimenuitem>
			</menuchoice>
			instead to list all the problem files. That way you can deal with them
			all at once.
		</para>
	</tip>
</sect1>
