Documentation Git Integration
Sublime Text's Git integration includes the following components:
Please note: the following documentation discusses the implementation of the Git integration as seen with the Default and Adaptive themes that are included with Sublime Text. Via the theme engine, it is possible for third-party themes to change the visual presentation of information, in which case the following documentation may not be accurate.
Files and folders displayed in the side bar will include a status badge along the right-hand edge, when modified. This includes files and folder in the Folders section of the side bar, along with files in the Open Files section. Ignored files and folders are de-emphasized in the side bar by reducing the opacity of the name.
When the mouse pauses over a status badge, a tool tip will be displayed indicating the status of the file, or in the case of a folder, the status of the contained files and folders.
Status Badge Key
The following table indicates the meaning of each badge. Please note that the color of the badges will be slightly different as they adapt to the closest hue in the active color scheme.
- Staged Addition
- Staged Modification
- Staged Deletion
When a folder contains files with multiple statuses, the badge most toward the end of the above list will override all others.
When the focussed file us containing within the working directory of a Git repository, the status bar will contain the name of the current branch, along with the number of files that are untracked, modified, staged or unmerged. The status bar element will look like:
Sublime Text's incremental diff functionality ties in with the Git integration. By default, the incremental diff functionality tracks changes to the file since it was last saved, but it is also possible to diff against HEAD.
Here is an example of what the diff markers look like in action, using the Mariana color scheme:
|28||A line that was added|
|30||A modified line|
|31||followed by another modified line|
|33||The line before this was deleted|
Changing the setting git_diff_target to
"head" will modify the diff markers to display a diff versus the version of the file at the Git repository HEAD, as opposed to the version of the file in the working directory.
See the incremental diff documentation for more information and examples, including instructions for viewing inline diffs, navigating between hunks and reverting changes.
Sublime Merge Integration
The Git features available in Sublime Text were derived from work that went into our other product, Sublime Merge. Sublime Merge is a full-featured, blazing-fast Git client built upon the technologies from Sublime Text.
Since editing source code and prose requires different tools and workflows than managing a Git repository, we opted to integrate the most appropriate Git functionality into Sublime Text, but leave more advanced features in Sublime Merge. The following integration points make it easy to jump into the appropriate Git context:
Editor Context Menu
Side Bar Folder Context Menu
Side Bar File Context Menu
The Git integration may be controlled via the show_git_status setting. The default value of
true enables Git integration, while
false disables it.
The behavior of incremental diff for files in a Git repository can be controlled via the git_diff_target setting. Valid values include:
"index"– diff against the Git index, the default
"head"– diff against the file at HEAD