Manual

Table of contents

1. Features
2. Manual installation
3. Configuration
   1. General configuration
   2. Global
      1. Notifications
   3. Project
      1. Defaults for new project
      2. Project general configuration
         1. Parent branch mode
      3. Automatic fetch exclusions
4. Troubleshooting

Features

1. Git status display
2. Not committed changes tracker
3. Git blame display
4. Automatic fetch
5. Behind tracker
6. Commit dialog branch completion
7. Commit dialog gitmoji completion
8. Recent branches switcher
9. Branch cleanup
10. Push selected tags
11. Issue Navigation integration
12. Git Extender integration

Git status display

Git status shows the following information:

• number of ahead / behind commits for current branch
• current branch
• tags on HEAD

Information is displayed in these locations:

• Project View - ahead / behind, branch name, tags on HEAD
  • 
• status bar - ahead / behind
  • 

Numbers for ahead and behind are based on number of commits not present in each of the branches. This information is obtained from output of git rev-list <current-ref>...<parent-ref> --left-right command.

Information presentation depends on the selected parent branch mode:

1. if parent-ref is a remote tracking branch of a current branch
   • simple branch name is displayed
   • ahead shows number of not yet pushed commits
   • behind shows number of remote commits not present in local branch
2. if parent-ref is a remote branch not tracking current branch (possible with Auto or selected parent modes)
   • extended branch name is displayed
     • <current branch> -> <parent branch> when both branches have the same remote
     • <current branch> -> <parent remote>/<parent branch> when both branches have different remotes
   • ahead shows number of commits from a current branch not present in remote parent branch
   • behind shows number of commits on a remote parent not present in the current branch

Not committed changes tracker

Shows committed changes:

• number of changes
• status (clean / dirty)

Information is displayed in following locations:

• Project View - number for changes
  • 2 Δ - means there are two changes
  • ∅ - no changes / clean
• Status bar
  • icon indicator for quick glance
  • number of changes / clean

Icons mapping to states:

• clean /
• dirty /

Git blame display

Git blame shows the following information for the current line in editor:

• author
• date and time
• commit subject

Git blame can be displayed as:

• editor inline for current line
  • 
• status bar widget
  • 

More detailed information about the line commit is available with Show Blame Details action:

• commit hash
• full message
• additional links that:
  • open Git Log
  • show affected files
  • copy commit hash

Automatic fetch

Runs git fetch at fixed intervals.

Behind tracker

Shows notification when behind count of current branch changes and is non-zero.

Commit dialog branch completion

Provides the following types of completion when editing commit message:

• current branch name
• pattern

Pattern based completion uses regular expression capture groups. Output consists of concatenation of input captured by each group. For example, regular expression (\w+-\d+).* matched against input JIRA-123_some_task will provide completion item JIRA-123

Commit dialog gitmoji completion

Provides gitmoji completion when editing commit message. It is disabled by default. In addition to completing by name it also takes into account descriptions of the gitmoji. Completion inserts either Markdown or Unicode, depending on configuration.

Recent branches switcher

Keeps track of 5 most recently used local branches for a repository and providers Switch Recent Git Branches action to show popup that allows fast switching. Popup entries ordering is from least recently used.

Branch cleanup

Detects merged and non-merged but stale branches. Cleanup can be executed manually from Git / GitToolBox / Git Branches Cleanup or automatically. Branches can be excluded using glob patterns.

Push selected tags

Lists tags on current branch and allows selection which should be pushed. They can also be force-pushed.

Issue Navigation integration

Plugin integrates with IDE Version Control / Issue Navigation. The moment it is configured following feature becomes active:

• clickable issue links inside blame details
• action to open issue that current branch refers to <context menu> / Git / Current Branch Issue <issue key>
• action to open issue that current line refers to <context menu> / Git / Line Issue <issue key>

Git Extender integration

Can be selected as update action executed from behind tracker popup.

Manual installation

To install manually from distribution artifact downloaded from https://plugins.jetbrains.com you must select entire zip archive in Install Plugin from Disk... dialog.

If you select only main jar file you will get NoClassDefFoundErrors when running IDE.

Configuration

Global configuration applies to IDE, project configuration applies to a project only.

General configuration

For most of the features to work repository roots must be correctly configured in:

• File / Settings / Version Control
• IntelliJ IDEA / Preferences... / Version Control

Windows/Linux configuration locations

• File / Settings / Appearance & Behavior / Notifications
• File / Settings / Editor / Color Scheme / GitToolBox Colors
• File / Settings / Version Control / GitToolBox
• File / Settings / Version Control / GitToolBox / GitToolBox Project

Mac OS configuration locations (with project open)

• IntelliJ IDEA / Preferences... / Appearance & Behavior / Notifications
• IntelliJ IDEA / Preferences... / Editor / Color Scheme / GitToolBox Colors
• IntelliJ IDEA / Preferences... / Version Control / GitToolBox
• IntelliJ IDEA / Preferences... / Version Control / GitToolBox / GitToolBox Project

Global configuration

Notifications

Notifications shown by the plugin can be configured on Appearance & Behavior / Notifications IDE config page.

Project configuration

Defaults for new project

Default configuration for newly created projects can be setup with standard IDE functionality available under:

File / New Projects Settings / Preferences for New Projects...

If you want to change inherited project-level configuration for existing projects see configuration overrides

Project general configuration

Parent branch mode

There are following modes available:

1. Auto - if Task Management plugin is enabled then get tracked branch of tasks parent branch, use tracked branch of current branch otherwise
2. Tracked remote - tracked branch of current branch
3. Selected parent - tracked branch of selected local branch. Branch selection goes through steps:
   1. if branch name contains / then match against names of remote branches prefixed with remote
   2. else find local branch with given name and use it's remote branch as parent

Automatic fetch exclusions

Under GitToolBox Project settings open the Auto Fetch tab and add your repository with the plus sign. Afterwards mark the repository in the list and add the remote you want to exclude with the plus sign again.

Exclusions are applied according to following rules:

• If a repository without remotes is configured, the whole repository is excluded
• If a repository with remotes is configured, only those remotes are excluded

Exclusions apply only to automatic fetch, they do not influence fetch actions.

Troubleshooting

Commonly raised questions and issues

Inline blame does not work in git directory

This might be caused by missing configuration, see general configuration

Login popup is shown every few minutes

Related to automatic fetch. First see if running Git / Fetch also shows the pop-up. If is does either save login information or just disable automatic fetch for the project in GitToolbox Project settings.

Enable diagnostic mode

1. Open Help > Find Action... and search for Registry.
2. Find zielu.gittoolbox.diagnostic.mode and enable it

There is new tab called Diagnostic available on GitToolBox Project config page displaying information which might be useful when investigating issues.

Logging

Plugin can log additional diagnostic information to help with issues investigation. All categories can be used in any combination.

Debug logging

Add following line to Help / Debug Log Settings...

#zielu.gittoolbox

Accessing logs

There is an action to open directory containing the logs Help / Show Log in...