doc/source/en/TortoiseSVN/tsvn_app_internals.xml

   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 TortoiseSVN'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 Subversion status value as reported\r
  21                         by the Subversion library. In the command line client, these\r
  22                         are represented by single letter codes, but in TortoiseSVN 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/InSubVersionIcon.png"/>\r
  63                         The <emphasis>In Subversion</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 TortoiseSVN 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                 <para>\r
  71                         <graphic fileref="images/ReadOnlyIcon.png"/> \r
  72                         The <emphasis>Needs Lock</emphasis> overlay is used to\r
  73                         indicate when a file has the <literal>svn:needs-lock</literal>\r
  74                         property set. For working copies which were created using\r
  75                         Subversion 1.4.0 and later, the <literal>svn:needs-lock</literal>\r
  76                         status is cached locally by Subversion and this is used to\r
  77                         determine when to show this overlay. For working copies which\r
  78                         are in pre-1.4.x format, TortoiseSVN shows this overlay when the\r
  79                         file has read-only status. Note that Subversion automatically\r
  80                         upgrades working copies when you update them, although the\r
  81                         caching of the <literal>svn:needs-lock</literal> property\r
  82                         may not happen until the file itself is updated.\r
  83                 </para>\r
  84                 <para>\r
  85                         <graphic fileref="images/LockedIcon.png"/> \r
  86                         The <emphasis>Locked</emphasis> overlay is used when the local\r
  87                         working copy holds a lock for that file.\r
  88                 </para>\r
  89                 <para>\r
  90                         <graphic fileref="images/IgnoredIcon.png"/>\r
  91                         The <emphasis>Ignored</emphasis> overlay is used to\r
  92                         represent an item which is in the <literal>ignored</literal>\r
  93                         state, either due to a global ignore pattern, or the\r
  94                         <literal>svn:ignore</literal> property of the parent folder.\r
  95                         This overlay is optional.\r
  96                 </para>\r
  97                 <para>\r
  98                         <graphic fileref="images/UnversionedIcon.png"/>\r
  99                         The <emphasis>Unversioned</emphasis> overlay is used to\r
 100                         represent an item which is in the <literal>unversioned</literal>\r
 101                         state. This is an item in a versioned folder, but which is not\r
 102                         under version control itself.\r
 103                         This overlay is optional.\r
 104                 </para>\r
 105                 <para>\r
 106                         If an item has subversion status <literal>none</literal> (the item\r
 107                         is not within a working copy) then no overlay is shown.\r
 108                         If you have chosen to disable the <emphasis>Ignored</emphasis>\r
 109                         and <emphasis>Unversioned</emphasis> overlays then no overlay\r
 110                         will be shown for those files either.\r
 111                 </para>\r
 112                 <para>\r
 113                         An item can only have one Subversion status value. For example\r
 114                         a file could be locally modified and it could be marked for\r
 115                         deletion at the same time. Subversion returns a single status\r
 116                         value - in this case <literal>deleted</literal>.\r
 117                         Those priorities are defined within Subversion itself.\r
 118                 </para>\r
 119                 <para>\r
 120                         When TortoiseSVN displays the status recursively (the default\r
 121                         setting), each folder displays an overlay reflecting its own\r
 122                         status and the status of all its children. In order to display\r
 123                         a single <emphasis>summary</emphasis> overlay, we use the\r
 124                         priority order shown above to determine which overlay to use,\r
 125                         with the <emphasis>Conflicted</emphasis> overlay taking highest\r
 126                         priority.\r
 127                 </para>\r
 128                 <para>\r
 129                         In fact, you may find that not all of these icons are used on your\r
 130                         system. This is because the number of overlays allowed by Windows\r
 131                         is limited to 15. Windows uses 4 of those, and the remaining 11\r
 132                         can be used by other applications. If there are not enough overlay\r
 133                         slots available, TortoiseSVN tries to be a\r
 134                         <quote>Good Citizen (TM)</quote> and limits its use of overlays to\r
 135                         give other apps a chance.\r
 136                 </para>\r
 137                 <itemizedlist>\r
 138                         <listitem>\r
 139                                 <para>\r
 140                                         <emphasis>Normal</emphasis>,\r
 141                                         <emphasis>Modified</emphasis> and\r
 142                                         <emphasis>Conflicted</emphasis>\r
 143                                         are always loaded and visible.\r
 144                                 </para>\r
 145                         </listitem>\r
 146                         <listitem>\r
 147                                 <para>\r
 148                                         <emphasis>Deleted</emphasis>\r
 149                                         is loaded if possible, but falls back to\r
 150                                         <emphasis>Modified</emphasis> if there are not enough slots.\r
 151                                 </para>\r
 152                         </listitem>\r
 153                         <listitem>\r
 154                                 <para>\r
 155                                         <emphasis>Read-Only</emphasis>\r
 156                                         is loaded if possible, but falls back to\r
 157                                         <emphasis>Normal</emphasis> if there are not enough slots.\r
 158                                 </para>\r
 159                         </listitem>\r
 160                         <listitem>\r
 161                                 <para>\r
 162                                         <emphasis>Locked</emphasis>\r
 163                                         is only loaded if there are fewer than 13 overlays already\r
 164                                         loaded. It falls back to <emphasis>Normal</emphasis>\r
 165                                         if there are not enough slots.\r
 166                                 </para>\r
 167                         </listitem>\r
 168                         <listitem>\r
 169                                 <para>\r
 170                                         <emphasis>Added</emphasis>\r
 171                                         is only loaded if there are fewer than 14 overlays already\r
 172                                         loaded. It falls back to <emphasis>Modified</emphasis>\r
 173                                         if there are not enough slots.\r
 174                                 </para>\r
 175                         </listitem>\r
 176                 </itemizedlist>\r
 177         </sect1>\r
 178 </appendix>\r