<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-commit">
	<title>Committing Your Changes To The Repository</title>
	<indexterm>
		<primary>commit</primary>
	</indexterm>
	<indexterm>
		<primary>send changes</primary>
	</indexterm>
	<indexterm>
		<primary>check in</primary>
	</indexterm>
	<?dbhh topicname="HIDD_COMMITDLG"?>
	<para>
		Storing the changes you made to your working tree is known as
		<firstterm>committing</firstterm> the changes. you can use
		<menuchoice>
			<guimenu>TortoiseGit</guimenu>
			<guimenuitem>Check for Modifications</guimenuitem>
		</menuchoice>
		first, to see which files have changed locally.
	</para>
	<sect2 id="tgit-dug-commit-basics">
		<title>The Commit Dialog</title>
		<para>
			If there are no conflicts,
			you are ready to commit your changes. Select any file
			and/or folders you want to commit, then
			<menuchoice>
				<guimenu>TortoiseGit</guimenu>
				<guimenuitem>Commit...</guimenuitem>
			</menuchoice>.
			<figure id="tgit-dug-commit-dia-1">
				<title>The Commit dialog</title>
				<graphic fileref="../images/Commit.png"/>
			</figure>
		</para>
		<para>
			The commit dialog will show you every changed file,
			including added, deleted and unversioned files. If you don't
			want a changed file to be committed, just uncheck that
			file. If you want to include an unversioned file,
			just check that file to add it to the commit.
		</para>
		<para>
			Default commit dialog just list select paths and their child directory files.
			If you want to list all files of project, you can just click <guibutton>
			Whole Project</guibutton>.
		</para>
		<tip>
			<title>Many unversioned files in the commit dialog</title>
			<para>
				If you think that the commit dialog shows you too
				many unversioned (e.g. compiler generated or editor backup)
				files, there are several ways to handle this. You can:
				<itemizedlist>
					<listitem>
						<para>
							add the file to the <literal>.gitignore</literal> list
							using
							<menuchoice>
								<guimenu>TortoiseGit</guimenu>
								<guimenuitem>Add to ignore list</guimenuitem>
							</menuchoice>
						</para>
					</listitem>
				</itemizedlist>
				Read <xref linkend="tgit-dug-ignore"/> for more information.
			</para>
		</tip>
		<para>
			<action>Double clicking</action> on any modified file in the commit
			dialog will launch the external diff tool to show your changes.
			The context menu will give you more options, as shown in the screenshot.
			You can also drag files from here into another application such as a
			text editor or an IDE.
		</para>
		<para>
			You can select or deselect items by clicking on the checkbox to the
			left of the item.
		</para>
		<para>
			The columns displayed in the bottom pane 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>
			The color code of the different items is described in <xref linkend="tgit-dug-wcstatus-2"/>.
		<para>
		</para>
		<para>
			Please note that the commit dialog always shows staged files - even if it was started on a different folder (this is by design in order to not forget to commit those, e.g. in case of a merge). Also, in the lower left there is the checkbox <guilabel>Show whole project</guilabel>. Use this to override the file/folder filter and show all changed files for the whole repository. This setting is remembered for a repository - even if you started the commit dialog on a single file.
		</para>
		<tip>
			<title>Drag and Drop</title>
			<para>
				You can drag files into the commit dialog from elsewhere, as
				long as the working tree is the very same.
				For example, you may have a huge working tree with several
				explorer windows open to look at distant folders of the
				hierarchy. If you want to avoid committing from the top
				level folder (with a lengthy folder crawl to check for changes)
				you can open the commit dialog for one folder and drag in items
				from the other windows to include within the same atomic commit.
			</para>
			<para>
				You can drag unversioned files which reside within a working tree
				into the commit dialog, and they will be Git added automatically.
			</para>
		</tip>
		<important>
			<title>Commits are just local</title>
			<para>
				Please note, that all commits are just local and only affect your local working tree. In order to share them with others you need to push them to a remote repository. See <xref linkend="tgit-dug-push"/> and <xref linkend="tgit-dug-sync"/> for more information.
			</para>
		</important>
	</sect2>
	<sect2 id="tgit-dug-commit-changelists">
		<title>Change Lists</title>
		<para>
			The commit dialog supports changelist feature to help
			with grouping related files together. Find out about this feature
			in <xref linkend="tgit-dug-changelists"/>.
		</para>
	</sect2>
	<sect2 id="tgit-dug-commit-ignore">
		<title>Excluding Items from the Commit List</title>
		<para>
			Sometimes you have versioned files that change frequently but that you
			really don't want to commit. Sometimes this indicates a flaw in your
			build process - why are those files versioned? should you be using
			template files? But occasionally it is inevitable. A classic reason
			is that your IDE changes a timestamp in the project file every time
			you build. The project file has to be versioned as it includes all the
			build settings, but it doesn't need to be committed just because the
			timestamp changed.
		</para>
		<para>
			To help out in awkward cases like this, there is a Git flag for files
			called <literal>skip-worktree</literal> - then files are treated as
			unmodified and Git also refuses to merge those on merge/pull
			(cf. <gitdoclink cmd="git-update-index" section="1" anchor="_skip_worktree_bit"/>).
			As another way to tackle cases like this, we have reserved a changelist
			called <literal>ignore-on-commit</literal>. Any file added to this
			changelist will automatically be unchecked in the commit dialog.
			You can still commit changes, but you have to select it manually
			in the commit dialog.
		</para>
	</sect2>
	<sect2 id="tgit-dug-commit-restore">
		<title>Commit only parts of files</title>
		<para>
			Sometimes you want to only commit parts of the changes
			you made to a file. Such a situation usually happens when
			you're working on something but then an urgent fix needs
			to be committed, and that fix happens to be in the same file
			you're working on.
		</para>
		<para>
			<action>right click</action> on the file and use
			<menuchoice>
				<guimenu>Context Menu</guimenu>
				<guimenuitem>Restore after commit</guimenuitem>
			</menuchoice>.
			This will create a copy of the file as it is. Then you
			can edit the file, e.g. in TortoiseGitMerge and undo all
			the changes you don't want to commit. After saving those
			changes you can commit the file.
			<tip>
				<title>Using TortoiseGitMerge</title>
				<para>
					If you use TortoiseGitMerge to edit the file, you can either edit
					the changes as you're used to, or mark
					all the changes that you want to include. <action>right click</action>
					on a modified block and use
					<menuchoice>
						<guimenu>Context Menu</guimenu>
						<guimenuitem>Mark this block</guimenuitem>
					</menuchoice>
					to include that change.
					Finally <action>right click</action>
					and use
					<menuchoice>
						<guimenu>Context Menu</guimenu>
						<guimenuitem>Use left file except marked blocks</guimenuitem>
					</menuchoice>
					which will invert your changes (unmarked blocks) that you
					don't want to them to appear in current commit.
				</para>
			</tip>
		</para>
		<para>
			After the commit is done, the copy of the file is restored
			automatically, and you have the file with all your modifications
			that were not committed back.
		</para>
	</sect2>
	<sect2 id="tgit-dug-commit-log">
		<title>Commit Log Messages</title>
		<?dbhh topicname="HIDD_AUTOTEXTTESTDLG"?>
		<?dbhh topicname="HIDD_HISTORYDLG"?>
		<para>
			Be sure to enter a log message which describes the changes you are
			committing. This will help you to see what happened and when, as you
			browse through the project log messages at a later date. The message
			can be as long or as brief as you like; many projects have guidelines
			for what should be included, the language to use, and sometimes even
			a strict format.
		</para>
		<para>
			You can apply simple formatting to your log messages using a convention
			similar to that used within emails.
			To apply styling to <literal>text</literal>, use
			<literal>*text*</literal> for bold,
			<literal>_text_</literal> for underlining, and
			<literal>^text^</literal> for italics.
		</para>
		<para>
			<figure id="tgit-dug-commit-dia-2">
				<title>The Commit Dialog Spellchecker</title>
				<graphic fileref="../images/CommitSpellcheck.png"/>
			</figure>
			TortoiseGit includes a spellchecker to help you get your log messages
			right (cf. <xref linkend="tgit-intro-instalsl-spell"/>). This will highlight any misspelled words. Use the context menu
			to access the suggested corrections. Of course, it doesn't know
			<emphasis>every</emphasis> technical term that you do, so correctly
			spelt words will sometimes show up as errors. But don't worry. You can
			just add them to your personal dictionary using the context menu.
		</para>
		<para>
			The log message window also includes a filename and function auto-completion
			facility. This uses regular expressions to extract class and function names
			from the (text) files you are committing, as well as the filenames themselves.
			If a word you are typing matches anything in the list (after you have typed at
			least 3 characters, or pressed <keycap>Ctrl+Space</keycap>),
			a drop-down appears allowing you to select the full name.
			The regular expressions supplied with TortoiseGit are held in the TortoiseGit
			installation <filename>bin</filename> folder. You can also define your own
			regexes and store them in <filename>%APPDATA%\TortoiseGit\autolist.txt</filename>.
			Of course your private autolist will not be overwritten when you update your
			installation of TortoiseGit. If you are unfamiliar with regular expressions,
			take a look at the introduction at
			<ulink url="https://en.wikipedia.org/wiki/Regular_expression">
				<citetitle>https://en.wikipedia.org/wiki/Regular_expression</citetitle>
			</ulink>,
			and the online documentation and tutorial at
			<ulink url="https://www.regular-expressions.info/">
				<citetitle>https://www.regular-expressions.info/</citetitle>
			</ulink>.
		</para>
		<para>
			Getting the regex just right can be tricky, so to help you sort out a
			suitable expression there is a test dialog which allows you to enter
			an expression and then type in filenames to test it against.
			Start it from the command prompt using the command
			<literal>TortoiseGitProc.exe /command:autotexttest</literal>.
		</para>
		<para>
			You can re-use previously entered log messages. Just use the command
			<menuchoice>
				<guimenu>Context Menu</guimenu>
				<guimenuitem>Paste Recent messages</guimenuitem>
			</menuchoice>
			to view a list of the last few
			messages you entered for this working tree. The number of stored messages
			can be customized in the TortoiseGit settings dialog.
		</para>
		<para>
			The log message window also includes a commit message snippet facility.
			These snippets are shown in the autocomplete drop-down once you type
			a snippet shortcut, and selecting the snippet in the autocomplete drop-down
			then inserts the full text of the snippet.
			The snippets supplied with TortoiseGit are held in the TortoiseGit
			installation <filename>bin</filename> folder. You can also define your own
			snippets and store them in <filename>%APPDATA%\TortoiseGit\snippet.txt</filename>.
			<literal>#</literal> is the comment character. Use escape sequences <literal>\t</literal>, <literal>\r</literal>, <literal>\n</literal>, and <literal>\\</literal>.
		</para>
		<para>
			You can add your name and email address to the end of the log message by clicking
			<guibutton>Add Signed-off-by</guibutton>.
		</para>
		<para>
			You can clear all stored commit messages from the <guilabel>Saved data</guilabel>
			page of TortoiseGit's settings, or you can clear individual messages from
			within the <guilabel>Recent messages</guilabel> dialog using the
			<keycap>Delete</keycap> key.
		</para>
		<para>
			If you want to include the checked paths in your log message, you can use
			the command
			<menuchoice>
				<guimenu>Context Menu</guimenu>
				<guimenuitem>Paste filename list</guimenuitem>
			</menuchoice>
			in the edit control.
		</para>
		<para>
			Another way to insert the paths into the log message is to simply
			drag the files from the file list onto the edit control.
		</para>
		<tip>
			<title>Using keyboard</title>
			<para>
				You can access the <guilabel>OK</guilabel> button from keyboard by pressing <keycap>Ctrl+return</keycap>.
			</para>
		</tip>
		<tip>
			<title>Integration with Bug Tracking Tools</title>
			<para>
				If you have activated the bug tracking system, you can set one or more
				Issues in the <guilabel>Bug-ID / Issue-No:</guilabel> text box. Multiple
				issues should be comma separated. Alternatively, if you are using
				regex-based bug tracking support, just add your issue references
				as part of the log message.
				Learn more in <xref linkend="tgit-dug-bugtracker"/>.
			</para>
		</tip>
		<tip>
			<title>Adjust the size of message text box</title>
			<para>
				Move your mouse to the gap between "Message" group box and
				"Changes made" group box, then drag the separator.
			</para>
		</tip>
		<tip>
			<title>Commit to a new branch</title>
			<para>
				If you want to commit to a fresh branch (based on the current branch), you can check the <guibutton>new branch</guibutton> checkbox and enter a branch name in the displayed textbox.
			</para>
		</tip>
		<tip>
			<title>Commit multiple times in a row and directly pushing changes</title>
			<para>
				The main button <guibutton>Commit</guibutton> has a drop-down menu.
				There are the options <guimenuitem>ReCommit</guimenuitem> and <guimenuitem>Commit &amp; push</guimenuitem>.
				The option <guimenuitem>ReCommit</guimenuitem> commits your changes and leaves the Commit dialog open, so that you can continue committing.
				The last option <guimenuitem>Commit &amp; push</guimenuitem> will commit your changes and immediately push your changes.
				If no remote tracking branch is configured for the current active branch, the push dialog (cf. <xref linkend="tgit-dug-push"/>) is opened.
			</para>
		</tip>
	</sect2>
	<sect2 id="tgit-dug-commit-progress">
		<title>Commit Progress</title>
		<para>
			After pressing <guibutton>Commit</guibutton>, a dialog appears displaying
			the progress of the commit.
			<figure id="tgit-dug-commit-dia-3">
				<title>The Progress dialog showing a commit in progress</title>
				<graphic fileref="../images/CommitProgress.png"/>
			</figure>
		</para>
		<para>
			In the lower left, there is a menu button which provides shortcuts to further steps, such as <guimenuitem>ReCommit</guimenuitem> (resets the commit dialog and allows you to continue committing) or <guimenuitem>Push</guimenuitem> in order to push your commit to a remote repository.
		</para>
<!--
		<para>
			The progress dialog uses color coding to highlight different
			commit actions
			<variablelist>
				<varlistentry>
					<term>Blue</term>
					<listitem>
						<para>
						Committing a modification.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Purple</term>
					<listitem>
						<para>
						Committing a new addition.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Dark red</term>
					<listitem>
						<para>
						Committing a deletion or a replacement.
						</para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Black</term>
					<listitem>
						<para>
						All other 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>
-->
	</sect2>
	<para>
		You can find more information at <gitdoclink cmd="git-commit" section="1"/>.
	</para>
</sect1>
