doc/source/en/TortoiseGit/tsvn_dug/dug_changelist.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
   3 <sect1 id="tsvn-dug-changelists">\r
   4         <title>Change Lists</title>\r
   5         <indexterm>\r
   6                 <primary>changelist</primary>\r
   7         </indexterm>\r
   8         <para>\r
   9                 In an ideal world, you only ever work on one thing at a time, and your\r
  10                 working tree contains only one set of logical changes. OK, back to reality.\r
  11                 It often happens that you have to work on several unrelated tasks at once,\r
  12                 and when you look in the commit dialog, all the changes are mixed in together.\r
  13                 The <firstterm>changelist</firstterm> feature helps you group files together,\r
  14                 making it easier to see what you are doing. Of course this can only work if\r
  15                 the changes do not overlap. If two different tasks affect the same file, there\r
  16                 is no way to separate the changes.\r
  17         </para>\r
  18         <important>\r
  19                 <para>\r
  20                         The changelist feature in TortoiseGit is only available in Windows XP \r
  21                         and later, as it depends on a shell capability which is not present\r
  22                         in Windows 2000.\r
  23                         Sorry, but Win2K is really quite old now, so please don't complain.\r
  24                 </para>\r
  25         </important>\r
  26         <para>\r
  27                 You can see changelists in several places, but the most important ones are\r
  28                 the commit dialog and the check-for-modifications dialog. Let's start\r
  29                 in the check-for-modifications dialog after you have worked on several\r
  30                 features and many files. When you first open the dialog, all the changed\r
  31                 files are listed together. Suppose you now want to organise things and\r
  32                 group those files according to feature.\r
  33         </para>\r
  34         <para>\r
  35                 Select one or more files and use\r
  36                 <menuchoice>\r
  37                         <guimenu>Context Menu</guimenu>\r
  38                         <guimenuitem>Move to changelist</guimenuitem>\r
  39                 </menuchoice>\r
  40                 to add an item to a changelist. Initially there will be no changelists,\r
  41                 so the first time you do this you will create a new changelist.\r
  42                 Give it name which describes what you are using it for, and click\r
  43                 <guibutton>OK</guibutton>. The dialog will now change to show\r
  44                 groups of items.\r
  45         </para>\r
  46         <para>\r
  47                 Once you have created a changelist you can drag and drop items into it,\r
  48                 either from another changelist, or from Windows Explorer. Dragging from\r
  49                 Explorer can be useful as it allows you to add items to a changelist\r
  50                 before the file is modified. You could do that from the check-for-modifications\r
  51                 dialog, but only by displaying all unmodified files.\r
  52         </para>\r
  53         <para>\r
  54                 <figure id="tsvn-dug-commit-dia-changelist">\r
  55                         <title>Commit dialog with Changelists</title>\r
  56                         <graphic fileref="../images/Changelist.png"/>\r
  57                 </figure>\r
  58                 In the commit dialog you can see those same files, grouped by changelist.\r
  59                 Apart from giving an immediate visual indication of groupings, you can\r
  60                 also use the group headings to select which files to commit.\r
  61         </para>\r
  62         <para>\r
  63                 On XP, there is a context menu when you right click on a group heading\r
  64                 which gives you the choice to check or uncheck all group entries. On Vista however\r
  65                 the context menu is not necessary. Click on the group header to select all\r
  66                 entries, then check one of the selected entries to check all.\r
  67         </para>\r
  68         <para>\r
  69                 TortoiseGit reserves one changelist name for its own use, namely\r
  70                 <literal>ignore-on-commit</literal>. This is used to mark versioned\r
  71                 files which you almost never want to commit even though they have local\r
  72                 changes. This feature is described in <xref linkend="tsvn-dug-commit-ignore"/>.\r
  73         </para>\r
  74         <para>\r
  75                 When you commit files belonging to a changelist then normally you would expect\r
  76                 that the changelist membership is no longer needed. So by default, files are\r
  77                 removed from changelists automatically on commit. If you wish to retain the\r
  78                 file in its changelist, use the <guilabel>Keep changelists</guilabel>\r
  79                 checkbox at the bottom of the commit dialog.\r
  80         </para>\r
  81         <tip>\r
  82                 <para>\r
  83                         Changelists are purely a local client feature. Creating and removing\r
  84                         changelists will not affect the repository, nor anyone else's working\r
  85                         copy. They are simply a convenient way for you to organise your files.\r
  86                 </para>\r
  87         </tip>\r
  88 </sect1>\r