| blob | 04e83081484164be8a118475eeda7551f5e6a587 |
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE appendix SYSTEM "../../dtd/dblite.dtd">\r
3 <appendix id="tsvn-app-internals" xmlns:xi="http://www.w3.org/2001/XInclude">\r
4 <title>Implementation Details</title>\r
5 <simplesect>\r
6 <para>\r
7 This appendix contains a more detailed discussion of the\r
8 implementation of some of TortoiseGit's features.\r
9 </para>\r
10 </simplesect>\r
11 <sect1 id="tsvn-app-internals-overlays">\r
12 <title>Icon Overlays</title>\r
13 <indexterm>\r
14 <primary>overlay priority</primary>\r
15 </indexterm>\r
16 <indexterm>\r
17 <primary>overlays</primary>\r
18 </indexterm>\r
19 <para>\r
20 Every file and folder has a Git status value as reported\r
21 by the Git library. In the command line client, these\r
22 are represented by single letter codes, but in TortoiseGit they\r
23 are shown graphically using the icon overlays. Because the number\r
24 of overlays is very limited, each overlay may represent one of\r
25 several status values.\r
26 </para>\r
27 <para>\r
28 <graphic fileref="images/ConflictIcon.png"/>\r
29 The <emphasis>Conflicted</emphasis> overlay is used to\r
30 represent the <literal>conflicted</literal> state, where\r
31 an update or switch results in conflicts between local\r
32 changes and changes downloaded from the repository. It is\r
33 also used to indicate the <literal>obstructed</literal> state,\r
34 which can occur when an operation is unable to complete.\r
35 </para>\r
36 <para>\r
37 <graphic fileref="images/ModifiedIcon.png"/>\r
38 The <emphasis>Modified</emphasis> overlay represents the\r
39 <literal>modified</literal> state, where you have made\r
40 local modifications, the <literal>merged</literal> state,\r
41 where changes from the repository have been merged with\r
42 local changes, and the <literal>replaced</literal> state,\r
43 where a file has been deleted and replaced by another\r
44 different file with the same name.\r
45 </para>\r
46 <para>\r
47 <graphic fileref="images/DeletedIcon.png"/> \r
48 The <emphasis>Deleted</emphasis> overlay represents the\r
49 <literal>deleted</literal> state, where an item is scheduled for\r
50 deletion, or the <literal>missing</literal> state, where an\r
51 item is not present. Naturally an item which is missing cannot have\r
52 an overlay itself, but the parent folder can be marked if one of its\r
53 child items is missing.\r
54 </para>\r
55 <para>\r
56 <graphic fileref="images/AddedIcon.png"/> \r
57 The <emphasis>Added</emphasis> overlay is simply used to\r
58 represent the <literal>added</literal> status when an item\r
59 has been added to version control.\r
60 </para>\r
61 <para>\r
62 <graphic fileref="images/InGitIcon.png"/>\r
63 The <emphasis>In Git</emphasis> overlay is used to\r
64 represent an item which is in the <literal>normal</literal>\r
65 state, or a versioned item whose state is not yet known.\r
66 Because TortoiseGit uses a background caching process to\r
67 gather status, it may take a few seconds before the overlay\r
68 updates.\r
69 </para>\r
70 \r
71 <para>\r
72 <graphic fileref="images/ReadOnlyIcon.png"/> \r
73 The <emphasis>stage</emphasis> overlay is used to file which staged.\r
74 But it still has not commited. \r
75 </para>\r
76 <!--\r
77 <para>\r
78 <graphic fileref="images/LockedIcon.png"/> \r
79 The <emphasis>Locked</emphasis> overlay is used when the local\r
80 working tree holds a lock for that file.\r
81 </para>\r
82 -->\r
83 <para>\r
84 <graphic fileref="images/IgnoredIcon.png"/>\r
85 The <emphasis>Ignored</emphasis> overlay is used to\r
86 represent an item which is in the <literal>ignored</literal>\r
87 state, either due to a global ignore pattern, or the\r
88 <literal>svn:ignore</literal> property of the parent folder.\r
89 This overlay is optional.\r
90 </para>\r
91 <para>\r
92 <graphic fileref="images/UnversionedIcon.png"/>\r
93 The <emphasis>Unversioned</emphasis> overlay is used to\r
94 represent an item which is in the <literal>unversioned</literal>\r
95 state. This is an item in a versioned folder, but which is not\r
96 under version control itself.\r
97 This overlay is optional.\r
98 </para>\r
99 <para>\r
100 If an item has Git status <literal>none</literal> (the item\r
101 is not within a working tree) then no overlay is shown.\r
102 If you have chosen to disable the <emphasis>Ignored</emphasis>\r
103 and <emphasis>Unversioned</emphasis> overlays then no overlay\r
104 will be shown for those files either.\r
105 </para>\r
106 <para>\r
107 An item can only have one Git status value. For example\r
108 a file could be locally modified and it could be marked for\r
109 deletion at the same time. Git returns a single status\r
110 value - in this case <literal>deleted</literal>.\r
111 Those priorities are defined within Git itself.\r
112 </para>\r
113 <para>\r
114 When TortoiseGit displays the status recursively (the default\r
115 setting), each folder displays an overlay reflecting its own\r
116 status and the status of all its children. In order to display\r
117 a single <emphasis>summary</emphasis> overlay, we use the\r
118 priority order shown above to determine which overlay to use,\r
119 with the <emphasis>Conflicted</emphasis> overlay taking highest\r
120 priority.\r
121 </para>\r
122 <para>\r
123 In fact, you may find that not all of these icons are used on your\r
124 system. This is because the number of overlays allowed by Windows\r
125 is limited to 15. Windows uses 4 of those, and the remaining 11\r
126 can be used by other applications. If there are not enough overlay\r
127 slots available, TortoiseGit tries to be a\r
128 <quote>Good Citizen (TM)</quote> and limits its use of overlays to\r
129 give other apps a chance.\r
130 </para>\r
131 <itemizedlist>\r
132 <listitem>\r
133 <para>\r
134 <emphasis>Normal</emphasis>,\r
135 <emphasis>Modified</emphasis> and\r
136 <emphasis>Conflicted</emphasis>\r
137 are always loaded and visible.\r
138 </para>\r
139 </listitem>\r
140 <listitem>\r
141 <para>\r
142 <emphasis>Deleted</emphasis>\r
143 is loaded if possible, but falls back to\r
144 <emphasis>Modified</emphasis> if there are not enough slots.\r
145 </para>\r
146 </listitem>\r
147 <listitem>\r
148 <para>\r
149 <emphasis>Stage</emphasis>\r
150 is loaded if possible, but falls back to\r
151 <emphasis>Modified</emphasis> if there are not enough slots.\r
152 </para>\r
153 </listitem>\r
154 <!--\r
155 <listitem>\r
156 <para>\r
157 <emphasis>Locked</emphasis>\r
158 is only loaded if there are fewer than 13 overlays already\r
159 loaded. It falls back to <emphasis>Normal</emphasis>\r
160 if there are not enough slots.\r
161 </para>\r
162 </listitem>\r
163 -->\r
164 <listitem>\r
165 <para>\r
166 <emphasis>Added</emphasis>\r
167 is only loaded if there are fewer than 14 overlays already\r
168 loaded. It falls back to <emphasis>Modified</emphasis>\r
169 if there are not enough slots.\r
170 </para>\r
171 </listitem>\r
172 </itemizedlist>\r
173 </sect1>\r
174 </appendix>\r