<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-blame">
	<title>Who Changed Which Line?</title>
	<indexterm>
		<primary>blame</primary>
	</indexterm>
	<indexterm>
		<primary>annotate</primary>
	</indexterm>
	<indexterm>
		<primary>praise</primary>
	</indexterm>
	<para>
		Sometimes you need to know not only what lines have changed, but also
		who exactly changed specific lines in a file. That's when the
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Blame...</guimenuitem>
		</menuchoice>
		command, sometimes also referred to as <firstterm>annotate</firstterm>
		command comes in handy.
	</para>
	<para>
		This command lists, for every line in a file, the author and the revision
		the line was changed.
	</para>
	<sect2 id="tgit-dug-blame-simple">
		<title>Blame for Files</title>
		<para>
			By default the blame file is viewed using <firstterm>TortoiseGitBlame</firstterm>,
			which highlights the different revisions to make it easier to read.
		</para>
		<para>
			<figure id="tgit-dug-blame-dia-2">
				<title>TortoiseGitBlame</title>
				<graphic fileref="../images/TortoiseBlame.png"/>
			</figure>
			TortoiseGitBlame, which is included with TortoiseGit.
			When you hover the mouse over a line in the blame info
			column, all lines with the same revision are shown with a darker
			background. Lines from other revisions which were changed by the same author
			are shown with a light background.
			The coloring may not work as clearly if you have your display set to
			256 color mode.
		</para>
		<para>
			If you <action>left click</action>
			on a line (on the blame info column on the left), all lines with the same revision are highlighted, and lines from
			other revisions by the same author are highlighted in a lighter color.
			This highlighting is sticky, allowing you to move the mouse without losing
			the highlights. Click on that revision again to turn off highlighting.
		</para>
		<para>
			The revision comments (log message) are shown in a hint box whenever
			the mouse hovers over the blame info column. If you want to copy the
			log message for that revision, use the context menu which appears when
			you right click on the blame info column.
		</para>
		<para>
			If you need a better visual indicator of where the oldest and newest
			changes are, select
			<menuchoice>
				<guimenu>View</guimenu>
				<guimenuitem>Colorize by age, continuous</guimenuitem>
			</menuchoice>.
			Then the background color intensity of the lines is related to its age.
			This will use a color gradient to show newer lines in yellow and older lines
			in white. The default coloring is quite light, but you can change it using the TortoiseGitBlame settings.
		</para>
		<para>
			Please also check out the <guimenuitem>View</guimenuitem> menu. There you can toggle the <guimenuitem>Ignore whitespace</guimenuitem> and also toggle the detection of moved/copied lines from other files and <guimenuitem>Follow renames</guimenuitem>.
		</para>
		<para>
			You can search within the Blame report using
			<menuchoice>
				<guimenu>Edit</guimenu>
				<guimenuitem>Find...</guimenuitem>
			</menuchoice>.
			This allows you to search for revision numbers, authors and the content of
			the file itself. Log messages are not included in the search - you should
			use the Log Dialog to search those.
		</para>
		<para>
			You can also jump to a specific line number using
			<menuchoice>
				<guimenu>Edit</guimenu>
				<guimenuitem>Go To Line...</guimenuitem>
			</menuchoice>.
		</para>
		<para>
			When the mouse is over the blame info columns, a context menu is
			available which helps with comparing revisions and examining history,
			using the commit of the line under the mouse as a reference.
			<menuchoice>
				<guimenu>Context menu</guimenu>
				<guimenuitem>Blame previous revision</guimenuitem>
			</menuchoice> generates a blame report for the same file, but using
			the previous revision as the upper limit. This gives you the blame
			report for the state of the file just before the line you are looking
			at was last changed.
			<menuchoice>
				<guimenu>Context menu</guimenu>
				<guimenuitem>Show changes</guimenuitem>
			</menuchoice> starts your diff viewer, showing you what changed in
			the referenced revision of the file. Please note, however, that these two options are only available if this line is not there since the initial commit of the file.
			<menuchoice>
				<guimenu>Context menu</guimenu>
				<guimenuitem>Show log</guimenuitem>
			</menuchoice> displays the revision log dialog starting with the
			referenced revision.
		</para>
		<para>
			The settings for TortoiseGitBlame can be accessed using
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Settings...</guimenuitem>
			</menuchoice>
			on the TortoiseGitBlame tab. Refer to
			<xref linkend="tgit-dug-settings-tortoiseblame"/>.
		</para>
	</sect2>
	<!--
	<sect2 id="tgit-dug-blame-diffs">
		<title>Blame Differences</title>
		<para>
			One of the limitations of the Blame report is that it only shows the file as
			it was in a particular revision, and shows the last person to change each line.
			Sometimes you want to know what change was made, as well as who made it. What
			you need here is a combination of the diff and blame reports.
		</para>
		<para>
			The revision log dialog includes several options which allow you to do this.
			<variablelist>
				<varlistentry>
					<term>Blame Revisions</term>
					<listitem>
						<para>
							In the top pane, select 2 revisions, then select
							<menuchoice>
								<guimenu>Context menu</guimenu>
								<guimenuitem>Blame revisions</guimenuitem>
							</menuchoice>.
							This will fetch the blame data for the 2 revisions, then
							use the diff viewer to compare the two blame files.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Blame Changes</term>
					<listitem>
						<para>
							Select one revision in the top pane, then pick one file
							in the bottom pane and select
							<menuchoice>
								<guimenu>Context menu</guimenu>
								<guimenuitem>Blame changes</guimenuitem>
							</menuchoice>.
							This will fetch the blame data for the selected revision
							and the previous revision, then use the diff viewer to
							compare the two blame files.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Compare and Blame with Working BASE</term>
					<listitem>
						<para>
							Show the log for a single file, and in the top pane, select
							a single revision, then select
							<menuchoice>
								<guimenu>Context menu</guimenu>
								<guimenuitem>Compare and Blame with Working BASE</guimenuitem>
							</menuchoice>.
							This will fetch the blame data for the selected revision,
							and for the file in the working BASE, then use the diff
							viewer to compare the two blame files.
						</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</para>
	</sect2>
	-->
	<para>
		You can find more information at <gitdoclink cmd="git-blame" section="1"/>.
	</para>
</sect1>
