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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">\r
   3 <sect1 id="tsvn-dug-ignore">\r
   4         <title>Ignoring Files And Directories</title>\r
   5         <indexterm>\r
   6                 <primary>ignore</primary>\r
   7         </indexterm>\r
   8         <indexterm>\r
   9                 <primary>unversioned files/folders</primary>\r
  10         </indexterm>\r
  11         <?dbhh topicname="HIDD_IGNORE"?>\r
  12         <para>\r
  13                 <figure id="tsvn-dug-ignoring-dia-1">\r
  14                         <title>Explorer context menu for unversioned files</title>\r
  15                         <graphic fileref="../images/ContextMenuFileIgnore.png"/>\r
  16                 </figure>\r
  17                 In most projects you will have files and folders that should not be subject\r
  18                 to version control. These might include files created by the compiler,\r
  19                 <filename>*.obj, *.lst</filename>, maybe an output folder used to store\r
  20                 the executable. Whenever you commit changes, TortoiseGit shows your unversioned\r
  21                 files, which fills up the file list in the commit dialog. Of course you\r
  22                 can turn off this display, but then you might forget to add a new source\r
  23                 file.\r
  24         </para>\r
  25         <para>\r
  26                 The best way to avoid these problems is to add the derived files\r
  27                 to the project's ignore list. That way they will never show up in\r
  28                 the commit dialog, but genuine unversioned source files will still\r
  29                 be flagged up.\r
  30         </para>\r
  31         <para>\r
  32                 If you <action>right click</action> on a single unversioned file,\r
  33                 and select the command\r
  34                 <menuchoice>\r
  35                         <guimenu>TortoiseGit</guimenu>\r
  36                         <guimenuitem>Add to Ignore List</guimenuitem>\r
  37                 </menuchoice>\r
  38                 from the context menu, a submenu appears allowing you to select just that\r
  39                 file, or all files with the same extension.\r
  40                 If you select multiple files, there is no submenu and you can only add\r
  41                 those specific files/folders.\r
  42         </para>\r
  43         <para>\r
  44                 If you want to remove one or more items from the ignore list,\r
  45                 <action>right click</action> on those items and select\r
  46                 <menuchoice>\r
  47                         <guimenu>TortoiseGit</guimenu>\r
  48                         <guimenuitem>Remove from Ignore List</guimenuitem>\r
  49                 </menuchoice>\r
  50                 You can also access a folder's <literal>svn:ignore</literal>\r
  51                 property directly. That allows you to specify more general\r
  52                 patterns using filename globbing, described in the section below.\r
  53                 Read <xref linkend="tsvn-dug-propertypage"/> for more information\r
  54                 on setting properties directly. Please be aware that each ignore pattern \r
  55                 has to be placed on a separate line. Separating them by spaces does not work.\r
  56         </para>\r
  57         <tip>\r
  58                 <title>The Global Ignore List</title>\r
  59                 <para>\r
  60                         Another way to ignore files is to add them to the\r
  61                         <firstterm>global ignore list</firstterm>. The big difference here\r
  62                         is that the global ignore list is a client property.\r
  63                         It applies to <emphasis>all</emphasis> Git projects, but on\r
  64                         the client PC only. In general it is better to use the\r
  65                         <filename>svn:ignore</filename> property where possible, because it\r
  66                         can be applied to specific project areas, and it works for\r
  67                         everyone who checks out the project. Read\r
  68                         <xref linkend="tsvn-dug-settings-main"/> for more information. \r
  69                 </para>\r
  70         </tip>\r
  71         <tip>\r
  72                 <title>Ignoring Versioned Items</title>\r
  73                 <para>\r
  74                         Versioned files and folders can never be ignored - that's a feature\r
  75                         of Git. If you versioned a file by mistake, read\r
  76                         <xref linkend="tsvn-howto-unversion"/> for instructions on how to\r
  77                         <quote>unversion</quote> it.\r
  78                 </para>\r
  79         </tip>\r
  80         <sect2 id="tsvn-dug-ignore-glob">\r
  81                 <title>Pattern Matching in Ignore Lists</title>\r
  82                 <indexterm>\r
  83                         <primary>globbing</primary>\r
  84                 </indexterm>\r
  85                 <indexterm>\r
  86                         <primary>pattern matching</primary>\r
  87                 </indexterm>\r
  88                 <para>\r
  89                         Git's ignore patterns make use of filename globbing,\r
  90                         a technique originally used in Unix to specify files using\r
  91                         meta-characters as wildcards. The following characters have\r
  92                         special meaning:\r
  93                         <variablelist>\r
  94                                 <varlistentry>\r
  95                                         <term>*</term>\r
  96                                         <listitem>\r
  97                                                 <para>\r
  98                                                         Matches any string of characters, including\r
  99                                                         the empty string (no characters).\r
 100                                                 </para>\r
 101                                         </listitem>\r
 102                                 </varlistentry>\r
 103                                 <varlistentry>\r
 104                                         <term>?</term>\r
 105                                         <listitem>\r
 106                                                 <para>\r
 107                                                         Matches any single character.\r
 108                                                 </para>\r
 109                                         </listitem>\r
 110                                 </varlistentry>\r
 111                                 <varlistentry>\r
 112                                         <term>[...]</term>\r
 113                                         <listitem>\r
 114                                                 <para>\r
 115                                                         Matches any one of the characters enclosed in the\r
 116                                                         square brackets. Within the brackets, a pair of\r
 117                                                         characters separated by <quote>-</quote>\r
 118                                                         matches any character lexically between the two.\r
 119                                                         For example <literal>[AGm-p]</literal> matches\r
 120                                                         any one of <literal>A</literal>, <literal>G</literal>,\r
 121                                                         <literal>m</literal>, <literal>n</literal>,\r
 122                                                         <literal>o</literal> or <literal>p</literal>.\r
 123                                                 </para>\r
 124                                         </listitem>\r
 125                                 </varlistentry>\r
 126                         </variablelist>\r
 127                 </para>\r
 128                 <para>\r
 129                         Pattern matching is case sensitive, which can cause problems\r
 130                         on Windows. You can force case insensitivity the hard way\r
 131                         by pairing characters, eg. to ignore <literal>*.tmp</literal>\r
 132                         regardless of case, you could use a pattern like\r
 133                         <literal>*.[Tt][Mm][Pp]</literal>.\r
 134                 </para>\r
 135                 <para>\r
 136                         If you want an official definition for globbing, you can find\r
 137                         it in the IEEE specifications for the shell command language\r
 138                         <ulink url="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13">\r
 139                                 <citetitle>Pattern Matching Notation</citetitle>\r
 140                         </ulink>.\r
 141                 </para>\r
 142                 <tip>\r
 143                         <title>No Paths in Global Ignore List</title>\r
 144                         <para>\r
 145                                 You should not include path information in your pattern.\r
 146                                 The pattern matching is intended to be used against plain\r
 147                                 file names and folder names.\r
 148                                 If you want to ignore all <literal>CVS</literal> folders,\r
 149                                 just add <literal>CVS</literal> to the ignore list. There is\r
 150                                 no need to specify <literal>CVS */CVS</literal> as you did in\r
 151                                 earlier versions.\r
 152                                 If you want to ignore all <literal>tmp</literal> folders\r
 153                                 when they exist within a <literal>prog</literal> folder but\r
 154                                 not within a <literal>doc</literal> folder you should use the\r
 155                                 <literal>svn:ignore</literal> property instead. There is no\r
 156                                 reliable way to achieve this using global ignore patterns.\r
 157                         </para>\r
 158                 </tip>\r
 159         </sect2>\r
 160 </sect1>\r