293a7d94772b9a27bd89e5bc031f654e10c2da37
| blob | 293a7d94772b9a27bd89e5bc031f654e10c2da37 |
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 tree,\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 tree 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>TGitCache.exe</filename>). That process\r
44 watches all drives for changes and fetches the status\r
45 again if files inside a working tree 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 tree is modified,\r
55 all folders up to the working tree 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 trees. 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 trees,\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. The Shell variant only shows\r
86 differences of the filesystem to the git index (does not include revision\r
87 specific information, e.g. if you remove a file from the index the file will\r
88 show up as unversioned, but with TGitCache the file will show up as deleted\r
89 until you commit this change).\r
90 </para>\r
91 </listitem>\r
92 </varlistentry>\r
93 <varlistentry>\r
94 <term>Shell</term>\r
95 <listitem>\r
96 <para>\r
97 Caching is done directly inside the shell extension\r
98 dll, but only for the currently visible folder.\r
99 Each time you navigate to another folder, the status\r
100 information is fetched again.\r
101 </para>\r
102 <para>\r
103 Advantage: needs only very little memory (around 1 MB of RAM)\r
104 and can show the status in <emphasis>real time</emphasis>.\r
105 </para>\r
106 <para>\r
107 Disadvantage: Since only one folder is cached, the overlays\r
108 don't show the status recursively. For big working trees,\r
109 it can take more time to show a folder in explorer than\r
110 with the default cache. The Shell variant only shows\r
111 differences of the filesystem to the git index (does not include revision\r
112 specific information, e.g. if you remove a file from the index the file will\r
113 show up as unversioned, but with TGitCache the file will show up as deleted\r
114 until you commit this change).\r
115 </para>\r
116 </listitem>\r
117 </varlistentry>\r
118 <varlistentry>\r
119 <term>None</term>\r
120 <listitem>\r
121 <para>\r
122 With this setting, the TortoiseGit does not fetch the status\r
123 at all in Explorer. Because of that, files don't get an overlay\r
124 and folders only get a 'normal' overlay if they're versioned.\r
125 No other overlays are shown, and no extra columns are available\r
126 either.\r
127 </para>\r
128 <para>\r
129 Advantage: uses absolutely no additional memory and does\r
130 not slow down the Explorer at all while browsing.\r
131 </para>\r
132 <para>\r
133 Disadvantage: Status information of files and folders is not\r
134 shown in Explorer. To see if your working trees are modified,\r
135 you have to use the <quote>Check for modifications</quote> dialog.\r
136 </para>\r
137 </listitem>\r
138 </varlistentry>\r
139 </variablelist>\r
140 </para>\r
141 <para>\r
142 The next group allows you to select which classes of storage should\r
143 show overlays. By default, only hard drives are selected.\r
144 You can even disable all icon overlays, but where's the fun in that?\r
145 </para>\r
146 <para>\r
147 Network drives can be very slow, so by default\r
148 icons are not shown for working trees located on network shares.\r
149 </para>\r
150 <para>\r
151 USB Flash drives appear to be a special case in that the drive type\r
152 is identified by the device itself. Some appear as fixed drives,\r
153 and some as removable drives.\r
154 </para>\r
155 <para>\r
156 The <guilabel>Exclude Paths</guilabel> are used to tell TortoiseGit\r
157 those paths for which it should <emphasis>not</emphasis> show icon\r
158 overlays and status columns.\r
159 This is useful if you have some very big working trees containing\r
160 only libraries which you won't change at all and therefore don't\r
161 need the overlays. For example:\r
162 </para>\r
163 <para>\r
164 <filename>f:\development\SVN\Git</filename> will disable\r
165 the overlays <emphasis>only</emphasis> on that specific folder. You\r
166 still can see the overlays on all files and folder inside that folder.\r
167 </para>\r
168 <para>\r
169 <filename>f:\development\SVN\Git*</filename> will disable the\r
170 overlays on <emphasis>all</emphasis> files and folders whose path\r
171 starts with <filename>f:\development\SVN\Git</filename>. That\r
172 means you won't see overlays for any files and folders below that\r
173 path.\r
174 </para>\r
175 <para>\r
176 The same applies to the <guilabel>Include Paths</guilabel>. Except that\r
177 for those paths the overlays are shown even if the overlays are disabled\r
178 for that specific drive type, or by an exclude path specified above.\r
179 </para>\r
180 <para>\r
181 Users sometimes ask how these three settings interact, and the definitive\r
182 answer is:\r
183 <screen>\r
184 if (path is in include list)\r
185 show overlays\r
186 if (path is allowed drive type) AND (path is not in exclude list)\r
187 show overlays\r
188 </screen>\r
189 The include list <emphasis>always</emphasis> makes the overlays show.\r
190 Otherwise, overlays are shown for all marked drive types\r
191 <emphasis>unless</emphasis> the path is excluded.\r
192 </para>\r
193 <para>\r
194 TGitCache.exe also uses these paths to restrict its scanning. If you\r
195 want it to look only in particular folders, disable all drive types\r
196 and include only the folders you specifically want to be scanned.\r
197 </para>\r
198 <tip>\r
199 <title>Exclude <literal>SUBST</literal> Drives</title>\r
200 <indexterm>\r
201 <primary>SUBST drives</primary>\r
202 </indexterm>\r
203 <para>\r
204 It is often convenient to use a <literal>SUBST</literal> drive\r
205 to access your working trees, e.g. using the command\r
206 <screen>\r
207 subst T: C:\TortoiseGit\trunk\doc\r
208 </screen>\r
209 However this can cause the overlays not to update, as\r
210 <literal>TGitCache</literal> will only receive one notification when\r
211 a file changes, and that is normally for the original path. This means\r
212 that your overlays on the <literal>subst</literal> path may never\r
213 be updated.\r
214 </para>\r
215 <para>\r
216 An easy way to work around this is to exclude the original path\r
217 from showing overlays, so that the overlays show up on the\r
218 <literal>subst</literal> path instead.\r
219 </para>\r
220 </tip>\r
221 <para>\r
222 Sometimes you will exclude areas that contain working trees,\r
223 which saves TGitCache from scanning and monitoring for changes,\r
224 but you still want a visual indication that such folders are versioned.\r
225 The <guilabel>Show excluded folders as 'normal'</guilabel> checkbox\r
226 allows you to do this. With this option, versioned folders in any\r
227 excluded area (drive type not checked, or specifically excluded)\r
228 will show up as normal and up-to-date, with a green check\r
229 mark. This reminds you that you are looking at a working tree, even\r
230 though the folder overlays may not be correct. Files do not get an\r
231 overlay at all. Note that the context menus still work, even though\r
232 the overlays are not shown.\r
233 </para>\r
234 <para>\r
235 As a special exception to this, drives <literal>A:</literal>\r
236 and <literal>B:</literal> are never considered for the\r
237 <guilabel>Show excluded folders as 'normal'</guilabel> option.\r
238 This is because Windows is forced to look on the drive, which can\r
239 result in a delay of several seconds when starting Explorer, even\r
240 if your PC does have a floppy drive.\r
241 </para>\r
242 <sect3 id="tsvn-dug-settings-icon-set">\r
243 <title>Icon Set Selection</title>\r
244 <?dbhh topicname="HIDD_OVERLAYICONS"?>\r
245 <para>\r
246 <figure id="tsvn-dug-settings-dia-icons">\r
247 <title>The Settings Dialog, Icon Set Page</title>\r
248 <graphic fileref="../images/SettingsOverlayChooser.png"/>\r
249 </figure>\r
250 You can change the overlay icon set to the one you like best. Especially you can disable overlays which you do not need like assume-valid and skip-worktree, however other Tortoise* tools use these two for different purposes.\r
251 Note that if you change overlay set, you may have to restart\r
252 your computer for the changes to take effect.\r
253 </para>\r
254 </sect3>\r
255 </sect2>\r