JGit/New and Noteworthy/6.2

JGit

New Features

Git config core.commentChar

The git config core.commentChar is supported as of JGit 6.2. It enables users to change the default character indicating comment lines in commit messages, which by default is #. The auto setting is also supported.

Negative Refspecs

JGit 6.2 supports negative refspecs when fetching, introduced in C git 2.29. Negative refspecs enable a git client to specify that some refs should not be fetched. A negative refspec has the form ^refs/... and it many conatin the * wildcard. For the details, see the git fetch documentation, or the git 2.29 announcement.

Support for External Diff and Merge Tools

JGit 6.2 supports the use of external diff and merge tools. To invoke a merge tool or a diff tool, e.g. run:

jgit mergetool --tool=kdiff3
jgit difftool --tool=kdiff3

Available merge and diff tools

To list the merge tools resp. diff tools available to JGit on your system, run:

jgit mergetool --tool-help
jgit difftool --tool-help

Parameters for mergetool

List of parameters supported by mergetool:

-t <tool>
--tool=<tool>
    Use the mergetool specified by <tool>.
 
-y
--no-prompt
    Do not prompt before launching the merge tool.
 
--prompt
    Prompt before each invocation of the merge tool. Default.
 
--tool-help
    Print a list of merge tools that may be used with --tool.
 
-g
--gui
    Use the default configured diff tool from merge.guitool instead of merge.tool.
 
--no-gui
    Override the default configured diff tool from merge.guitool.
 
--trust-exit-code
    Exit as soon as the merge tool returns a non-zero exit code for a file.
 
--no-trust-exit-code
    Continue merging with the merge tool, regardless of exit code per file. Default.
 
-- <files, file pattern>
    Invoke the merge tool only for the listed files, or files matching the specified pattern.

Parameters for difftool

List of parameters supported by difftool:

-t <tool>
--tool=<tool>
    Use the diff tool specified by <tool>.
 
-y
--no-prompt
    Do not prompt before launching the diff tool.
 
--prompt
    Prompt before each invocation of the diff tool. Default.
 
--tool-help
    Print a list of diff tools that may be used with --tool.
 
--cached
--staged
    Invoke the diff tool with files that contain staged changes.
 
-g
--gui
    Use the default configured diff tool from diff.guitool instead of diff.tool.
 
--no-gui
    Override the default configured diff tool from diff.guitool.
 
--trust-exit-code
    Exit as soon as the diff tool returns a non-zero exit code for a file.
 
--no-trust-exit-code
    Continue listing diffs with the diff tool, regardless of exit code per file. Default.
 
-- <files, file pattern>
    Invoke the diff tool only for the listed files, or files matching the specified pattern.

Configuration via .git/config

.git/config for mergetool

Example configuration of an external merge tool:

[merge]
        tool = customTool
[mergetool "customTool"]
        cmd = echo
        path = /usr/bin/echo
        prompt = false
        guitool = false
        trustExitCode = false

The merge section in the example above configures the default merge tool. The mergetool section configures specifics for that tool.

List of configuration options:

merge.tool
    Default merge tool.
merge.guitool
    Default GUI merge tool.
mergetool.prompt
    Whether to prompt before each invocation of the merge tool.
mergetool.keepBackup
    Whether to preserve original files with '.orig' extension.
mergetool.keepTemporaries
    Whether to keep the temporary files created for the merge tool invocation.
mergetool.writeToTemp
    Whether to create temporary files in a temporary directory. If set to 'false', the temporary files are written in the worktree.
mergetool.<tool>.path
    Specify the full merge tool command (including path). E.g. in case the merge tool is not on the PATH variable.
mergetool.<tool>.cmd
    Specify the command to invoke for the merge tool.
mergetool.<tool>.trustExitCode
    Whether to exit on non-zero exit code returned by the merge tool for a file.

.git/config for difftool

Example configuration of an external diff tool:

[diff]
        tool = customTool
[difftool "customTool"]
        cmd = echo
        path = /usr/bin/echo
        prompt = false
        guitool = false
        trustExitCode = false

The diff section in the example above configures the default diff tool. The difftool section configures specifics for that tool.

List of configuration options:

diff.tool
    Default diff tool.
diff.guitool
    Default GUI diff tool.
difftool.prompt
    Whether to prompt before each invocation of the diff tool.
difftool.<tool>.path
    Specify the full diff tool command (including path). E.g. in case the diff tool is not on the PATH variable.
difftool.<tool>.cmd
    Specify the command to invoke for the diff tool.
difftool.<tool>.trustExitCode
    Whether to exit on non-zero exit code returned by the diff tool for a file.

See also

For more info on those parameters and configuration, see:

• https://git-scm.com/docs/git-mergetool
• https://git-scm.com/docs/git-difftool

Other Changes

The complete list of new features and bug fixes is available in the release notes.

Contributors

The following XX developers worked on this release:

<TBD: list of contributors, number>