Manual

Table of contents

1. License and usage
   1. License check
   2. Purchase and duration of license
   3. License activation
2. Features
3. Paid features
4. Manual installation
5. Configuration
   1. General configuration
   2. Global
      1. Notifications
   3. Project
      1. Defaults for a new project
      2. Project general configuration
         1. Parent branch mode
      3. Automatic fetch exclusions
   4. Repository configuration
6. Cache invalidation
7. Troubleshooting

License and usage

Plugin is developed and delivered in freemium model.

License text is available in plugin configuration > About > License tab

All features available before 500.x.y version will stay free and receive fixes and occasional updated. Features marked as paid as available upon purchasing license using Jetbrains Marketplace.

License check

License is checked using APIs provided by Jetbrains Marketplace. Result of last check is available in plugin configuration > About > Plugin Information tab.

Purchase and duration of license

Duration of license depends on type of your purchase made via Jetbrains Marketplace. Details on how each type of license available works are described in Marketplace Docs

License activation

Due to dynamic nature of some features (for example blame) it may be necessary to restart IDE after license purchase.

Features

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

Paid features

1. Git blame display (Paid)
2. Repository links (Paid)

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

Git blame display Paid

This is a paid feature. You need to set up Issue Navigation.

Issue references available in inline blame become clickable links.

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.

Commit message validation

Before commit checks can verify whether a commit message:

• contains reference to issue referenced by branch name
• matches a regular expression

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

List tags on current branch and select which ones should be pushed. They can be also 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
  • 
• highlighted issue number in line blame
  • 
  • paid feature makes the links clickable
• action to open issue that current line / branch refers to <context menu> / Git / Open Issue Link
  • 
  • clicking the action opens navigation popup
  • 

Git Extender integration

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

Repository links

This is a paid feature.

Following repositories are supported:

• Bitbucket (Cloud & Server)
• GitHub
• GitLab

You can open or copy browser link to file (and to exact line in file when used from editor).

It is also possible to copy link from browser and a notification in IDE will appear which allows to open given file in IDE. For example:

1. Copy a link from browser to clipboard, for example:
   • https://bitbucket.org/user/repository/src/a2bda0f550dd43111145b9f4a03e331f049dec28/test.txt#lines-4
2. After switching back to IDE you will get a notification with link to open editor from that link
   • 

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

MacOS configuration locations (with project open)

• IntelliJ IDEA / Settings... / Appearance & Behavior / Notifications
• IntelliJ IDEA / Settings... / Editor / Color Scheme / GitToolBox Colors
• IntelliJ IDEA / Settings... / Version Control / GitToolBox
• IntelliJ IDEA / Settings... / 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 a new project

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

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.

Repository configuration

This is used by paid features.

There are two levels on configuration. On application level you can configure how repository type is detected based on fetch uri.

On project level you can see which type was detected based on settings on app level.

Cache invalidation

Since 500.0.1 it is possible to invalidate plugin caches with File / Invalidate Caches.... There is no need to select any specific item under Optional section.

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...