Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be 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/5.11"

(Mention signed tags)
(JGit: HTTP Basic auth)
Line 18: Line 18:
 
JGit's server side (class <tt>UploadPack</tt>) has supported protocol V2 for handling fetches for a while already, but it was not the default. With JGit 5.11, protocol V2 has been made the default also for the server side.
 
JGit's server side (class <tt>UploadPack</tt>) has supported protocol V2 for handling fetches for a while already, but it was not the default. With JGit 5.11, protocol V2 has been made the default also for the server side.
  
== Commands ==
+
== HTTP(S) transport protocol ==
 +
 
 +
JGit 5.11.0 supports ''preemptive'' Basic authentication on HTTP or HTTPS connections. Preemptive authentication may save an extra request if it is known that the host will accept the HTTP Basic authentication scheme, and if the user name and password are known up front. There are two ways to use this:
 +
 
 +
# via the git remote URL (or clone URL). If the URL includes user and password information like <tt>https://''user:password''@example.org/git/some_repository.git</tt>, JGit removes the user name and password from the URL and sends it in a HTTP Basic Authentication header. ('''Note:''' special characters in the "user:password" part ''must'' be %-encoded.)
 +
# programmatically via the new method <code>TransportHttp.setPreemptiveBasicAuthentication(String username, String password)</code>, which can be used, e.g., in a <code>TransportConfigCallback</code> to configure the transport used by higher-level API commands. Setting a username and password via this method overrides a username and password that might be present in the URL.
 +
 
 +
 
 +
Programmatically, one might do
 +
<pre style="margin-left:2em;">
 +
String username = ...;
 +
String password = ...;
 +
Git newlyCloned = Git.cloneRepository()
 +
  .setDirectory(someDirectory)
 +
  .setURI(remoteURI)
 +
  .setTransportConfigCallback(transport -> {
 +
    if (transport instanceof TransportHttp) {
 +
      ((TransportHttp) transport).setPreemptiveBasicAuthentication(username, password);
 +
    }
 +
  })
 +
  .call();
 +
// Do something with 'newlyCloned'
 +
// Don't forget to close it eventually when you're done! (Could also use try-with-resource.)
 +
newlyCloned.close();
 +
</pre>
 +
 
 +
If the original URI results in a redirect to another host, the preemptive Basic authentication is ''not'' propagated.
 +
 
 +
== Commands ==
  
 
* JGit 5.11 supports creating '''signed tags'''. There is a new interface <code>org.eclipse.jgit.lib.GpgObjectSigner</code> that can be implemented to sign not only commits but also tags; a default implementation using BouncyCastle is available in bundle <code>org.eclipse.jgit.gpg.bc</code>. API class <code>org.eclipse.jgit.api.TagCommand</code> has been extended to be able to sign tags using such a <tt>GpgObjectSigner</tt>, and the command-line program <code>org.eclipse.jgit.pgm.Tag</code> also supports it. Git configs <tt>[https://git-scm.com/docs/git-config#Documentation/git-config.txt-taggpgSign tag.gpgSign]</tt> and <tt>[https://git-scm.com/docs/git-config#Documentation/git-config.txt-tagforceSignAnnotated tag.forceSignAnnotated]</tt> are implemented.
 
* JGit 5.11 supports creating '''signed tags'''. There is a new interface <code>org.eclipse.jgit.lib.GpgObjectSigner</code> that can be implemented to sign not only commits but also tags; a default implementation using BouncyCastle is available in bundle <code>org.eclipse.jgit.gpg.bc</code>. API class <code>org.eclipse.jgit.api.TagCommand</code> has been extended to be able to sign tags using such a <tt>GpgObjectSigner</tt>, and the command-line program <code>org.eclipse.jgit.pgm.Tag</code> also supports it. Git configs <tt>[https://git-scm.com/docs/git-config#Documentation/git-config.txt-taggpgSign tag.gpgSign]</tt> and <tt>[https://git-scm.com/docs/git-config#Documentation/git-config.txt-tagforceSignAnnotated tag.forceSignAnnotated]</tt> are implemented.

Revision as of 17:02, 18 January 2021

JGit

Git Protocol

The git protocol is the application-layer protocol git uses for communication between a git client and an upstream (git server). It is implemented atop the transport protocol (like HTTPS or SSH). Git has two different protocols for communicating with an upstream. Protocol V2 is supposed to be more efficient than the older protocol V0/V1.

JGit 5.11 supports git protocol V2 for fetching. When JGit does a fetch, it always requests protocol V2 (unless overridden by a git config, see below). If the server response indicates that the server can do only protocol V0/V1, JGit falls back to using that older protocol. If the server replies with a valid protocol V2 answer, protocol V2 is used.

On the client side, git config protocol.version controls which protocol is used by JGit for fetching. Possible values are:

  • 2 or not set: JGit requests protocol V2 and falls back to protocol V0 if the server does not support protocol V2.
  • 0 or 1: JGit uses protocol V0.


(Protocol V0 and V1 are identical except for an additional line "version 1" in V1 in the initial server response.)

Pushing via JGit always uses protocol V0.

JGit's server side (class UploadPack) has supported protocol V2 for handling fetches for a while already, but it was not the default. With JGit 5.11, protocol V2 has been made the default also for the server side.

HTTP(S) transport protocol

JGit 5.11.0 supports preemptive Basic authentication on HTTP or HTTPS connections. Preemptive authentication may save an extra request if it is known that the host will accept the HTTP Basic authentication scheme, and if the user name and password are known up front. There are two ways to use this:

  1. via the git remote URL (or clone URL). If the URL includes user and password information like https://user:password@example.org/git/some_repository.git, JGit removes the user name and password from the URL and sends it in a HTTP Basic Authentication header. (Note: special characters in the "user:password" part must be %-encoded.)
  2. programmatically via the new method TransportHttp.setPreemptiveBasicAuthentication(String username, String password), which can be used, e.g., in a TransportConfigCallback to configure the transport used by higher-level API commands. Setting a username and password via this method overrides a username and password that might be present in the URL.


Programmatically, one might do

String username = ...;
String password = ...;
Git newlyCloned = Git.cloneRepository()
  .setDirectory(someDirectory)
  .setURI(remoteURI)
  .setTransportConfigCallback(transport -> {
     if (transport instanceof TransportHttp) {
       ((TransportHttp) transport).setPreemptiveBasicAuthentication(username, password);
     }
   })
  .call();
// Do something with 'newlyCloned'
// Don't forget to close it eventually when you're done! (Could also use try-with-resource.)
newlyCloned.close();

If the original URI results in a redirect to another host, the preemptive Basic authentication is not propagated.

Commands

  • JGit 5.11 supports creating signed tags. There is a new interface org.eclipse.jgit.lib.GpgObjectSigner that can be implemented to sign not only commits but also tags; a default implementation using BouncyCastle is available in bundle org.eclipse.jgit.gpg.bc. API class org.eclipse.jgit.api.TagCommand has been extended to be able to sign tags using such a GpgObjectSigner, and the command-line program org.eclipse.jgit.pgm.Tag also supports it. Git configs tag.gpgSign and tag.forceSignAnnotated are implemented.

Other Changes

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

Contributors

The following X developers worked on this release:

<TBD: list of contributors, number>

Back to the top