| blob | 7590f633917546d30ab9c4682c63a501c9db314a |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">\r
3 <sect2 id="tsvn-dug-settings-overlay">\r
4 <title>Icon Overlay Settings</title>\r
5 <?dbhh topicname="HIDD_SETTINGSOVERLAY"?>\r
6 <para>\r
7 <figure id="tsvn-dug-settings-dia-overlay">\r
8 <title>The Settings Dialog, Icon Overlays Page</title>\r
9 <graphic fileref="../images/SettingsOverlay.png"/>\r
10 </figure>\r
11 This page allows you to choose the items for which TortoiseGit will\r
12 display icon overlays.\r
13 </para>\r
14 <para>\r
15 By default, overlay icons and context menus will appear in all open/save\r
16 dialogs as well as in Windows Explorer. If you want them to appear\r
17 <emphasis>only</emphasis> in Windows Explorer, check the\r
18 <guilabel>Show overlays and context menu only in explorer</guilabel> box.\r
19 </para>\r
20 <para>\r
21 Ignored items and Unversioned items are not usually given an overlay.\r
22 If you want to show an overlay in these cases, just check the boxes.\r
23 </para>\r
24 <para>\r
25 You can also choose to mark folders as\r
26 modified if they contain unversioned items. This could be useful for\r
27 reminding you that you have created new files which are not yet versioned.\r
28 This option is only available when you use the <emphasis>default</emphasis>\r
29 status cache option (see below).\r
30 </para>\r
31 <para>\r
32 Since it takes quite a while to fetch the status of a working copy,\r
33 TortoiseGit uses a cache to store the status so the explorer\r
34 doesn't get hogged too much when showing the overlays.\r
35 You can choose which type of cache TortoiseGit should use according\r
36 to your system and working copy size here:\r
37 <variablelist>\r
38 <varlistentry>\r
39 <term>Default</term>\r
40 <listitem>\r
41 <para>\r
42 Caches all status information in a separate process\r
43 (<filename>TSVNCache.exe</filename>). That process\r
44 watches all drives for changes and fetches the status\r
45 again if files inside a working copy get modified.\r
46 The process runs with the least possible priority so\r
47 other programs don't get hogged because of it. That \r
48 also means that the status information is not\r
49 <emphasis>real time</emphasis> but it can take a few\r
50 seconds for the overlays to change.\r
51 </para>\r
52 <para>\r
53 Advantage: the overlays show the status recursively,\r
54 i.e. if a file deep inside a working copy is modified,\r
55 all folders up to the working copy root will also\r
56 show the modified overlay. And since the process can\r
57 send notifications to the shell, the overlays on the left\r
58 tree view usually change too.\r
59 </para>\r
60 <para>\r
61 Disadvantage: the process runs constantly, even if you're not \r
62 working on your projects. It also uses around 10-50 MB of RAM \r
63 depending on number and size of your working copies. In the\r
64 current implementation it doesn't check the contents of the files,\r
65 it just checks the last modification time against the time stored\r
66 in the git index file.\r
67 </para>\r
68 </listitem>\r
69 </varlistentry>\r
70 <varlistentry>\r
71 <term>Shell Extended</term>\r
72 <listitem>\r
73 <para>\r
74 Caching is done directly inside the shell extension\r
75 dll.\r
76 Each time you navigate to another folder, the status\r
77 information is fetched again (recursively).\r
78 </para>\r
79 <para>\r
80 Advantage: can show the status in <emphasis>real time</emphasis>.\r
81 </para>\r
82 <para>\r
83 Disadvantage: only one folder is cached and for big working copies,\r
84 it can take much more time to show a folder in explorer than\r
85 with the default cache or with shell mode.\r
86 </para>\r
87 </listitem>\r
88 </varlistentry>\r
89 <varlistentry>\r
90 <term>Shell</term>\r
91 <listitem>\r
92 <para>\r
93 Caching is done directly inside the shell extension\r
94 dll, but only for the currently visible folder.\r
95 Each time you navigate to another folder, the status\r
96 information is fetched again.\r
97 </para>\r
98 <para>\r
99 Advantage: needs only very little memory (around 1 MB of RAM)\r
100 and can show the status in <emphasis>real time</emphasis>.\r
101 </para>\r
102 <para>\r
103 Disadvantage: Since only one folder is cached, the overlays\r
104 don't show the status recursively. For big working copies,\r
105 it can take more time to show a folder in explorer than\r
106 with the default cache.\r
107 </para>\r
108 </listitem>\r
109 </varlistentry>\r
110 <varlistentry>\r
111 <term>None</term>\r
112 <listitem>\r
113 <para>\r
114 With this setting, the TortoiseGit does not fetch the status\r
115 at all in Explorer. Because of that, files don't get an overlay\r
116 and folders only get a 'normal' overlay if they're versioned.\r
117 No other overlays are shown, and no extra columns are available\r
118 either.\r
119 </para>\r
120 <para>\r
121 Advantage: uses absolutely no additional memory and does\r
122 not slow down the Explorer at all while browsing.\r
123 </para>\r
124 <para>\r
125 Disadvantage: Status information of files and folders is not\r
126 shown in Explorer. To see if your working copies are modified,\r
127 you have to use the <quote>Check for modifications</quote> dialog.\r
128 </para>\r
129 </listitem>\r
130 </varlistentry>\r
131 </variablelist>\r
132 </para>\r
133 <para>\r
134 The next group allows you to select which classes of storage should\r
135 show overlays. By default, only hard drives are selected.\r
136 You can even disable all icon overlays, but where's the fun in that?\r
137 </para>\r
138 <para>\r
139 Network drives can be very slow, so by default\r
140 icons are not shown for working copies located on network shares.\r
141 </para>\r
142 <para>\r
143 USB Flash drives appear to be a special case in that the drive type\r
144 is identified by the device itself. Some appear as fixed drives,\r
145 and some as removable drives.\r
146 </para>\r
147 <para>\r
148 The <guilabel>Exclude Paths</guilabel> are used to tell TortoiseGit\r
149 those paths for which it should <emphasis>not</emphasis> show icon\r
150 overlays and status columns.\r
151 This is useful if you have some very big working copies containing\r
152 only libraries which you won't change at all and therefore don't\r
153 need the overlays. For example:\r
154 </para>\r
155 <para>\r
156 <filename>f:\development\SVN\Git</filename> will disable\r
157 the overlays <emphasis>only</emphasis> on that specific folder. You\r
158 still can see the overlays on all files and folder inside that folder.\r
159 </para>\r
160 <para>\r
161 <filename>f:\development\SVN\Git*</filename> will disable the\r
162 overlays on <emphasis>all</emphasis> files and folders whose path\r
163 starts with <filename>f:\development\SVN\Git</filename>. That\r
164 means you won't see overlays for any files and folders below that\r
165 path.\r
166 </para>\r
167 <para>\r
168 The same applies to the <guilabel>Include Paths</guilabel>. Except that\r
169 for those paths the overlays are shown even if the overlays are disabled\r
170 for that specific drive type, or by an exclude path specified above.\r
171 </para>\r
172 <para>\r
173 Users sometimes ask how these three settings interact, and the definitive\r
174 answer is:\r
175 <screen>\r
176 if (path is in include list)\r
177 show overlays\r
178 if (path is allowed drive type) AND (path is not in exclude list)\r
179 show overlays\r
180 </screen>\r
181 The include list <emphasis>always</emphasis> makes the overlays show.\r
182 Otherwise, overlays are shown for all marked drive types\r
183 <emphasis>unless</emphasis> the path is excluded.\r
184 </para>\r
185 <para>\r
186 TSVNCache.exe also uses these paths to restrict its scanning. If you\r
187 want it to look only in particular folders, disable all drive types\r
188 and include only the folders you specifically want to be scanned.\r
189 </para>\r
190 <tip>\r
191 <title>Exclude <literal>SUBST</literal> Drives</title>\r
192 <indexterm>\r
193 <primary>SUBST drives</primary>\r
194 </indexterm>\r
195 <para>\r
196 It is often convenient to use a <literal>SUBST</literal> drive\r
197 to access your working copies, e.g. using the command\r
198 <screen>\r
199 subst T: C:\TortoiseGit\trunk\doc\r
200 </screen>\r
201 However this can cause the overlays not to update, as\r
202 <literal>TSVNCache</literal> will only receive one notification when\r
203 a file changes, and that is normally for the original path. This means\r
204 that your overlays on the <literal>subst</literal> path may never\r
205 be updated.\r
206 </para>\r
207 <para>\r
208 An easy way to work around this is to exclude the original path\r
209 from showing overlays, so that the overlays show up on the\r
210 <literal>subst</literal> path instead.\r
211 </para>\r
212 </tip>\r
213 <para>\r
214 Sometimes you will exclude areas that contain working copies,\r
215 which saves TSVNCache from scanning and monitoring for changes,\r
216 but you still want a visual indication that such folders are versioned.\r
217 The <guilabel>Show excluded folders as 'normal'</guilabel> checkbox\r
218 allows you to do this. With this option, versioned folders in any\r
219 excluded area (drive type not checked, or specifically excluded)\r
220 will show up as normal and up-to-date, with a green check\r
221 mark. This reminds you that you are looking at a working copy, even\r
222 though the folder overlays may not be correct. Files do not get an\r
223 overlay at all. Note that the context menus still work, even though\r
224 the overlays are not shown.\r
225 </para>\r
226 <para>\r
227 As a special exception to this, drives <literal>A:</literal>\r
228 and <literal>B:</literal> are never considered for the\r
229 <guilabel>Show excluded folders as 'normal'</guilabel> option.\r
230 This is because Windows is forced to look on the drive, which can\r
231 result in a delay of several seconds when starting Explorer, even\r
232 if your PC does have a floppy drive.\r
233 </para>\r
234 <sect3 id="tsvn-dug-settings-icon-set">\r
235 <title>Icon Set Selection</title>\r
236 <?dbhh topicname="HIDD_OVERLAYICONS"?>\r
237 <para>\r
238 <figure id="tsvn-dug-settings-dia-icons">\r
239 <title>The Settings Dialog, Icon Set Page</title>\r
240 <graphic fileref="../images/SettingsOverlayChooser.png"/>\r
241 </figure>\r
242 You can change the overlay icon set to the one you like best.\r
243 Note that if you change overlay set, you may have to restart\r
244 your computer for the changes to take effect.\r
245 </para>\r
246 </sect3>\r
247 </sect2>\r