Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "JGit/New and Noteworthy/6.2"

(→‎Support for External Diff and Merge Tools)
(Shorten difftool/mergetool section, and use only standard MediaWiki formatting (no GesHi syntax coloring extension))
Line 9: Line 9:
 
=== Negative Refspecs ===
 
=== 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 <tt>^refs/...</tt> and it many conatin the <tt>*</tt> wildcard. For the details, see the [https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt-ltrefspecgt git fetch documentation], or the [https://github.blog/2020-10-19-git-2-29-released/#user-content-negative-refspecs git 2.29 announcement].
+
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 <tt>^refs/...</tt> and it many contain the <tt>*</tt> wildcard. For the details, see the [https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt-ltrefspecgt git fetch documentation], or the [https://github.blog/2020-10-19-git-2-29-released/#user-content-negative-refspecs git 2.29 announcement].
  
 
=== Support for External Diff and Merge Tools ===
 
=== 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 6.2 supports the use of external diff and merge tools. To invoke a merge or diff tool use, for instance:
  
−
<source lang="bash">
+
jgit difftool --tool=kdiff3
−
jgit mergetool --tool=kdiff3
+
jgit mergetool --tool=kdiff3
−
jgit difftool --tool=kdiff3
+
−
</source>
+
  
−
==== Available merge and diff tools ====
+
The list of diff or merge tools configured on the system may be obtained via
  
−
To list the merge tools resp. diff tools available to JGit on your system, run:
+
jgit difftool --tool-help
 +
jgit mergetool --tool-help
  
−
<source lang="bash">
+
Diff or merge tools are defined in the git configuration files, typically in the repository or user git config. The mechanism is the same for both. An example of a merge tool definition might be
−
jgit mergetool --tool-help
+
−
jgit difftool --tool-help
+
−
</source>
+
  
−
==== Parameters for '''mergetool''' ====
+
[merge]
−
 
+
−
List of parameters supported by '''mergetool''':
+
−
 
+
−
<source lang="bash">
+
−
-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.
+
−
</source>
+
−
 
+
−
==== Parameters for '''difftool'''====
+
−
 
+
−
List of parameters supported by '''difftool''':
+
−
 
+
−
<source lang="bash">
+
−
-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.
+
−
</source>
+
−
 
+
−
==== Configuration via .git/config ====
+
−
 
+
−
===== .git/config for mergetool =====
+
−
 
+
−
Example configuration of an external merge tool:
+
−
 
+
−
<source lang="bash">
+
−
[merge]
+
 
         tool = customTool
 
         tool = customTool
−
[mergetool "customTool"]
+
[mergetool "customTool"]
 
         cmd = echo
 
         cmd = echo
 
         path = /usr/bin/echo
 
         path = /usr/bin/echo
 
         prompt = false
 
         prompt = false
−
        guitool = false
 
−
        trustExitCode = false
 
−
</source>
 
−
 
−
The '''merge''' section in the example above configures the default merge tool. The '''mergetool''' section configures specifics for that tool.
 
−
 
−
List of configuration options:
 
−
 
−
<source lang="bash">
 
−
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.
 
−
</source>
 
−
 
−
 
−
===== .git/config for difftool =====
 
−
 
−
 
−
Example configuration of an external diff tool:
 
−
 
−
<source lang="bash">
 
−
[diff]
 
−
        tool = customTool
 
−
[difftool "customTool"]
 
−
        cmd = echo
 
−
        path = /usr/bin/echo
 
−
        prompt = false
 
−
        guitool = false
 
 
         trustExitCode = false
 
         trustExitCode = false
−
</source>
 
−
 
−
The '''diff''' section in the example above configures the default diff tool. The '''difftool''' section configures specifics for that tool.
 
−
 
−
List of configuration options:
 
−
 
−
<source lang="bash">
 
−
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.
 
−
</source>
 
−
 
−
==== See also ====
 
  
−
For more info on those parameters and configuration, see:
+
For a diff tool definition, use <tt>diff.tool = &lt;name></tt> and define it via <tt>diff.&lt;name>.*</tt> instead of <tt>merge.tool</tt> and <tt>merge.&lt;name>.*</tt>.
  
−
* https://git-scm.com/docs/git-mergetool
+
For the details of configurations and possible parameters to the <tt>difftool</tt> or <tt>mergetool</tt> commands, see the official git documentation on <tt>[https://git-scm.com/docs/git-difftool git difftool]</tt> and <tt>[https://git-scm.com/docs/git-mergetool git mergetool]</tt>.
−
* https://git-scm.com/docs/git-difftool
+
  
 
== Other Changes ==
 
== Other Changes ==

Revision as of 05:26, 3 June 2022

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 contain 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 or diff tool use, for instance: 

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

The list of diff or merge tools configured on the system may be obtained via 

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

Diff or merge tools are defined in the git configuration files, typically in the repository or user git config. The mechanism is the same for both. An example of a merge tool definition might be 

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

For a diff tool definition, use diff.tool = <name> and define it via diff.<name>.* instead of merge.tool and merge.<name>.*.

For the details of configurations and possible parameters to the difftool or mergetool commands, see the official git documentation on git difftool and git mergetool.

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>

Retrieved from "https://wiki.eclipse.org/index.php?title=JGit/New_and_Noteworthy/6.2&oldid=445516"

Back to the top