<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tgit-dug-changelists">
	<title>Change Lists</title>
	<?dbhh topicname="HIDD_CREATECHANGELIST"?>
	<indexterm>
		<primary>changelist</primary>
	</indexterm>
	<para>
		In an ideal world, you only ever work on one thing at a time, and your
		working tree contains only one set of logical changes. OK, back to reality.
		It often happens that you have to work on several unrelated tasks at once,
		and when you look in the commit dialog, all the changes are mixed in together.
		The <firstterm>changelist</firstterm> feature helps you group files together,
		making it easier to see what you are doing. Of course this can only work if
		the changes do not overlap. If two different tasks affect the same file, there
		is no way to separate the changes.
	</para>
	<tip>
		<para>
			There is a similar functionality in Git called stashing (<xref linkend="tgit-dug-stash"/>).
		</para>
		<para>
			Generally you should consider to create a new branch as Git commits are just local, you're not messing with everybody's repository, but just your own.
		</para>
	</tip>
	<para>
		You can see changelists in several places, but the most important ones are
		the commit dialog and the check-for-modifications dialog. Let's start
		in the check-for-modifications dialog after you have worked on several
		features and many files. When you first open the dialog, all the changed
		files are listed together. Suppose you now want to organize things and
		group those files according to feature.
	</para>
	<para>
		Select one or more files and use
		<menuchoice>
			<guimenu>Context Menu</guimenu>
			<guimenuitem>Move to changelist</guimenuitem>
		</menuchoice>
		to add an item to a changelist. Initially there will be no changelists,
		so the first time you do this you will create a new changelist.
		Give it name which describes what you are using it for, and click
		<guibutton>OK</guibutton>. The dialog will now change to show
		groups of items.
	</para>
<!--
	<para>
		Once you have created a changelist you can drag and drop items into it,
		either from another changelist, or from Windows Explorer. Dragging from
		Explorer can be useful as it allows you to add items to a changelist
		before the file is modified. You could do that from the check-for-modifications
		dialog, but only by displaying all unmodified files.
	</para>
-->
	<para>
		<figure id="tgit-dug-commit-dia-changelist">
			<title>Commit dialog with Changelists</title>
			<graphic fileref="../images/Changelist.png"/>
		</figure>
		In the commit dialog you can see those same files, grouped by changelist.
		Apart from giving an immediate visual indication of groupings, you can
		also use the group headings to select which files to commit.
	</para>
	<para>
		Click on the group header to select all
		entries, then check one of the selected entries to check all.
	</para>
	<para>
		TortoiseGit reserves one changelist name for its own use, namely
		<literal>ignore-on-commit</literal>. This is used to mark versioned
		files which you almost never want to commit even though they have local
		changes. This feature is described in <xref linkend="tgit-dug-commit-ignore"/>.
	</para>
	<para>
		When you commit files belonging to a changelist then normally you would expect
		that the changelist membership is no longer needed. So by default, files are
		removed from changelists automatically on commit. <!--If you wish to retain the
		file in its changelist, use the <guilabel>Keep changelists</guilabel>
		checkbox at the bottom of the commit dialog.-->
	</para>
	<tip>
		<para>
			Changelists are purely a local TortoiseGit client feature. Creating and removing
			changelists will not affect the repository, nor anyone else's working
			copy. They are simply a convenient way for you to organize your files.
		</para>
	</tip>
</sect1>
