<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-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 copy 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>
  <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 organise 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="tsvn-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>
    TortoiseSVN 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="tsvn-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 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 organise your files.
    </para>
  </tip>
  <warning>
    <para>
      Note that if you use changelists, externals will no longer show up
      in their own groups anymore. Once there are changelists, files
      and folders are grouped by changelist, not by external anymore.
    </para>
  </warning>
</sect1>
