Appendix E. Implementation Details

Every file has a Git status value as reported by the Git library. In the command line client, these are represented by single letter codes, but in TortoiseGit they are shown graphically using the icon overlays. Because the number of overlays is very limited, each overlay may represent one of several status values.

The Conflicted overlay is used to represent the conflicted state, where a merge resulted in conflicts between the changes of the current and changes from another branch.

The Modified overlay represents the modified state, where you have made local modifications to your working tree.

The Deleted overlay represents the deleted state, where an item is scheduled for deletion, or the missing state, where an item is not present but still in the Git index. Naturally an item which is missing cannot have an overlay itself, but the parent folder can be marked if one of its child items is missing.

The Added overlay is simply used to represent the added status when an item has been added to version control.

The In Git overlay is used to represent an item which is in the normal state.

The assume-valid (Needs Lock in TortoiseSVN) overlay is used to indicate if a file has the assume-valid flag set.

The skip-worktree (Locked in TortoiseSVN) overlay is used when to indicate if a file has the skip-worktree flag set.

The Ignored overlay is used to represent an item which is in the ignored state, either due to a global ignore pattern, or due to a .gitignore file in one of the parent folders. This overlay is optional.

The Unversioned overlay is used to represent an item which is in the unversioned state. This is an item in a versioned folder, but which is not under version control itself. This overlay is optional.

If an item has Git status none (the item is not within a working tree) then no overlay is shown. If you have chosen to disable the Ignored and Unversioned overlays then no overlay will be shown for those files either.

An item can only have one Git status value. For example a file could be locally modified and it could be marked for deletion at the same time. Git returns a single status value - in this case deleted. Those priorities are defined within Git and TortoiseGit itself.

When TortoiseGit displays the status recursively (the default setting), each folder displays an overlay reflecting its own status and the status of all its children. In order to display a single summary overlay, we use the priority order shown above to determine which overlay to use, with the Conflicted overlay taking highest priority.

In fact, you may find that not all of these icons are used on your system. This is because the number of overlays allowed by Windows is limited to 15. Windows uses 4 of those, and the remaining 11 can be used by other applications. If there are not enough overlay slots available, TortoiseGit tries to be a Good Citizen (TM) and limits its use of overlays to give other apps a chance.

If you have problems with overlays, please see the online FAQ.

Since there are Tortoise clients available for other version control systems, the TortoiseSVN developers created a shared component which is responsible for showing the overlay icons. The technical details are not important here, all you need to know is that this shared component allows all Tortoise clients to use the same overlays and therefore the limit of 11 available slots isn't used up by installing more than one Tortoise client. Of course there's one small drawback: all Tortoise clients use the same overlay icons, so you can't figure out by the overlay icons what version control system a working copy is using.