<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-wcstatus">
	<title>Getting Status Information</title>
	<indexterm>
		<primary>status</primary>
	</indexterm>
	<indexterm>
		<primary>view changes</primary>
	</indexterm>
	<indexterm>
		<primary>working tree status</primary>
	</indexterm>
	<para>
		While you are working on your working tree you often need to know
		which files you have changed/added/removed or renamed, or even which
		files got changed and committed by others.
	</para>
	<sect2 id="tgit-dug-wcstatus-1">
		<title>Icon Overlays</title>
		<indexterm>
			<primary>overlays</primary>
		</indexterm>
		<indexterm>
			<primary>icons</primary>
		</indexterm>
		<para>
			<figure id="tgit-dug-wcstatus-dia-1">
				<title>Explorer showing icon overlays</title>
				<graphic fileref="../images/Overlays.png"/>
			</figure>
		</para>
		<para>
			Now that you have checked out a working tree
			you can see your files in the windows explorer with
			changed icons. This is one of the reasons why TortoiseGit is so
			popular. TortoiseGit adds a so called overlay icon to each
			file icon which overlaps the original file icon. Depending on
			the Git status of the file the overlay icon is different.
		</para>
		<para>
			<graphic fileref="../images/InGitIcon.png"/>
			A fresh checked out working tree has a green checkmark as overlay.
			That means the Git status is <emphasis>normal</emphasis>.
		</para>
		<para>
			<graphic fileref="../images/ModifiedIcon.png"/>
			As soon as you start editing a file,
			the status changes to <emphasis>modified</emphasis>
			and the icon overlay then changes to a red exclamation
			mark. That way you can easily see which files were changed
			since you last updated your working tree and need to be committed.
		</para>
		<para>
			<graphic fileref="../images/ConflictIcon.png"/>
			If during an update a <emphasis>conflict</emphasis> occurs then
			the icon changes to a yellow exclamation mark.
		</para>
		<para>
			<graphic fileref="../images/ReadOnlyIcon.png"/>
			This tells you that this file is marked as "assume-valid".
			This overlay is optional.
		</para>
		<para>
			<graphic fileref="../images/LockedIcon.png"/>
			This tells you that this file is marked as "skip-worktree".
			This overlay is optional.
		</para>
		<para>
			<graphic fileref="../images/DeletedIcon.png"/>
			This icon shows you that some files or folders inside the current folder
			have been scheduled to be <emphasis>deleted</emphasis> from version control.
		</para>
		<para>
			<graphic fileref="../images/AddedIcon.png"/>
			The plus sign tells you that a file has been scheduled to be
			<emphasis>added</emphasis> to version control.
		</para>
		<para>
			<graphic fileref="../images/IgnoredIcon.png"/>
			The bar sign tells you that a file or folder is
			<emphasis>ignored</emphasis> for version control purposes.
			This overlay is optional.
		</para>
		<para>
			<graphic fileref="../images/UnversionedIcon.png"/>
			This icon shows files and folders which are not under version control,
			but have not been ignored.
			This overlay is optional.
		</para>
		<para>
			In fact, you may find that not all of these icons are used on your system.
			This is because the number of overlays allowed by Windows is very limited
			and if you are also using an old version of TortoiseCVS or tools with overlay handlers such as SkyDrive, DropBox or GoogleDrive, then there are
			not enough overlay slots available.
			TortoiseGit tries to be a <quote>Good Citizen (TM)</quote>
			and limits its use of overlays to give other apps a chance too.
		</para>
		<para>
			If you have problems with overlays, please see the online
			<ulink url="https://tortoisegit.org/support/faq/#ovlnotshowing"><citetitle>FAQ</citetitle></ulink>.
		</para>
		<para>
			For a description of how icon overlays correspond to Git
			status and other technical details, read
			<xref linkend="tgit-app-internals-overlays"/>.
		</para>
	</sect2>
	<sect2 id="tgit-dug-wcstatus-winprops">
		<title>Explorer Properties</title>
		<indexterm>
			<primary>windows properties</primary>
			<primary>explorer properties</primary>
		</indexterm>
		<para>
			<figure id="tgit-dug-propertypage-dia-1">
				<title>Explorer property page, Git tab</title>
				<graphic fileref="../images/Properties.png"/>
			</figure>
			TortoiseGit provides a property page in Windows Explorer for files/folders under Git version control.
			There you can see all relevant information about the selected file/directory.
			Just select a file or directory and select
			<menuchoice>
				<guimenu>Windows Menu</guimenu>
				<guimenuitem>properties</guimenuitem>
			</menuchoice>
			in the context menu (note: this is the normal properties menu entry
			the explorer provides, not the one in the TortoiseGit submenu!).
		</para>
	</sect2>
	<sect2 id="tgit-dug-wcstatus-2">
		<?dbhh topicname="HIDD_CHANGEDFILES"?>
		<title>Status</title>
		<indexterm>
			<primary>status</primary>
		</indexterm>
		<indexterm>
			<primary>modifications</primary>
		</indexterm>
		<para>
			<figure id="tgit-dug-wcstatus-dia-2">
				<title>Check for Modifications</title>
				<graphic fileref="../images/RepoStatus.png"/>
			</figure>
			It's often very useful to know which files you have
			changed and also which files got changed and
			committed by others. That's where the command
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Check For Modifications...</guimenuitem>
			</menuchoice>
			comes in handy.
			This dialog will show you every file that has changed in any
			way in your working tree, as well as any unversioned files
			you may have.
		</para>
		<!--
		<para>
			If you click on the
			<guibutton>Check Repository</guibutton> then you can also
			look for changes in the repository. That way
			you can check before an update if there's a possible conflict.
			You can also update selected files from the repository without
			updating the whole folder. By default, the <guibutton>Check Repository</guibutton>
			button only fetches the remote status with the checkout depth
			of the working tree. If you want to see all files and folders
			in the repository, even those you have not checked out, then you
			have to hold down the <keycap>Shift</keycap> key when you
			click on the <guibutton>Check Repository</guibutton> button.
		</para>
		-->
		<para>
			The dialog uses color coding to highlight the status.
			<variablelist>
				<varlistentry>
					<term>Blue</term>
					<listitem>
						<para>
						Locally modified items.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Purple</term>
					<listitem>
						<para>
						Added items.
						Items which have been added with history have a
						<literal>+</literal> sign in the
						<guilabel>Text status</guilabel> column,
						and a tooltip shows where the item was copied from.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Dark red</term>
					<listitem>
						<para>
						Deleted or missing items.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Green</term>
					<listitem>
						<para>
						Items modified locally and in the repository.
						The changes will be merged on update.
						These <emphasis>may</emphasis> produce conflicts on update.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Bright red</term>
					<listitem>
						<para>
						Items modified locally and deleted in repository,
						or modified in repository and deleted locally.
						These <emphasis>will</emphasis> produce conflicts on update.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Black</term>
					<listitem>
						<para>
						Unchanged and unversioned items.
						</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</para>
		<para>
			This is the default color scheme, but you can customise those colors
			using the settings dialog.
			Read <xref linkend="tgit-dug-settings-colours"/> for more information.
		</para>
		<para>
			From the context menu of the dialog you can show a diff of the
			changes. Check the local changes <emphasis>you</emphasis> made using
			<menuchoice>
				<guimenu>Context Menu</guimenu>
				<guimenuitem>Compare with Base</guimenuitem>
			</menuchoice>.
			Check the changes in the repository made by others using
			<menuchoice>
				<guimenu>Context Menu</guimenu>
				<guimenuitem>Show Differences as Unified Diff</guimenuitem>
			</menuchoice>.
		</para>
		<para>
			You can also revert changes in individual files. If you have deleted
			a file accidentally, it will show up as <emphasis>Missing</emphasis>
			and you can use <emphasis>Revert</emphasis> to recover it.
		</para>
		<para>
			Unversioned and ignored files can be sent to the recycle bin from here using
			<menuchoice>
				<guimenu>Context Menu</guimenu>
				<guimenuitem>Delete</guimenuitem>
			</menuchoice>.
			If you want to delete files permanently (bypassing the recycle bin) hold
			the <keycap>Shift</keycap> key while clicking on <guilabel>Delete</guilabel>.
		</para>
		<para>
			If you want to examine a file in detail, you can drag it from here
			into another application such as a text editor or IDE.
		</para>
		<para>
			The columns are customizable. If you
			<action>right click</action> on any column header you will see a
			context menu allowing you to select which columns are displayed.
			You can also change column width by using the drag handle which
			appears when you move the mouse over a column boundary. These
			customizations are preserved, so you will see the same headings
			next time.
		</para>
		<para>
			If you are working on several unrelated tasks at once, you can also
			group files together into changelists.
			Read <xref linkend="tgit-dug-commit-changelists"/> for more information.
		</para>
		<para>
			At the bottom of the dialog you have several options to select which entries to show (such as ignored or untracked/unversioned files).
			It is also possible to view all files which were marked as "Assume valid" or "Skip worktree" here (using <guilabel>Show ignore local changes flagged files</guilabel>).
			Resetting those flags (it's also possible to edit this flag using file properties in explorer on the <guilabel>Git</guilabel> tab).
		</para>
		<para>
			<guilabel>Save unified diff</guilabel>: Generates an unified patch containing the uncommitted changes and opens it with the configured diff viewer. If you want to pass your changes to other people, consider <xref linkend="tgit-dug-patch"/>.
		</para>
		<para>
			<guilabel>Stash</guilabel>: Is a drop-down menu for quick access to Git stash (cf. <xref linkend="tgit-dug-stash"/>). This feature allows you to put aside uncommitted changes in order to work on an unrelated issue and get the changes back afterwards easily.
		</para>
		<para>
			<guilabel>Commit</guilabel>: Opens the commit dialog (cf. <xref linkend="tgit-dug-commit"/>) with the very same folder/files the current dialog was opened on. If you want to pre-populate the commit dialog with only a subset of files, select the files and choose <guimenuitem>Commit...</guimenuitem> in the context menu.
		</para>
<!--
		<tip>
			<para>
				If you want a flat view of your working tree, i.e. showing all files
				and folders at every level of the folder hierarchy, then the
				<guilabel>Check for Modifications</guilabel> dialog is the
				easiest way to achieve that. Just check the
				<guilabel>Show unmodified files</guilabel> checkbox to show
				all files in your working tree.
			</para>
		</tip>
-->
	</sect2>
	<sect2 id="tgit-dug-diffing">
		<title>Viewing Diffs</title>
		<indexterm>
			<primary>diffing</primary>
		</indexterm>
		<para>
			Often you want to look inside your files, to have a look at what
			you've changed. You can accomplish this by selecting a file which
			has changed, and selecting <guimenuitem>Diff</guimenuitem> from
			TortoiseGit's context menu. This starts the external
			diff-viewer, which will then compare the current file with the
			pristine copy (<literal>BASE</literal> revision), which was stored
			after the last checkout or update.
		</para>
		<tip>
			<para>
				Even when not inside a working tree or when you have multiple
				versions of the file lying around, you can still display diffs:
			</para>
			<para>
				Select the two files you want to compare in explorer
				(e.g. using <keycap>Ctrl</keycap> and the mouse) and
				choose <guimenuitem>Diff</guimenuitem> from TortoiseGit's
				context menu. The file clicked last (the one with the focus,
				i.e. the dotted rectangle) will be regarded as the later
				one.
			</para>
		</tip>
	</sect2>
</sect1>
