[JENKINS-52490] add more documentation, and test for the new env var

* rename the env var to be aligned with the git description
* test isn't working yet as expected, still need more investigation into why

Signed-off-by: Jeff Knurek <[email protected]>

Author: Jeff Knurek

README.adoc

@@ -468,6 +468,7 @@ GIT_LOCAL_BRANCH:: Name of branch being built without remote name, as in `master
 GIT_COMMIT:: SHA-1 of the commit used in this build
 GIT_PREVIOUS_COMMIT:: SHA-1 of the commit used in the preceding build of this project
 GIT_PREVIOUS_SUCCESSFUL_COMMIT:: SHA-1 of the commit used in the most recent successful build of this project
+GIT_COMMIT_TITLE:: The text up to the first blank line in the commit message used in this build
 
 === System Configuration Variables
 

src/main/java/hudson/plugins/git/GitSCM.java

@@ -152,7 +152,7 @@ public class GitSCM extends GitSCMBackwardCompatibility {
     public static final String GIT_LOCAL_BRANCH = "GIT_LOCAL_BRANCH";
     public static final String GIT_CHECKOUT_DIR = "GIT_CHECKOUT_DIR";
     public static final String GIT_COMMIT = "GIT_COMMIT";
-    public static final String GIT_COMMIT_MESSAGE = "GIT_COMMIT_MESSAGE";
+    public static final String GIT_COMMIT_TITLE = "GIT_COMMIT_TITLE";
     public static final String GIT_PREVIOUS_COMMIT = "GIT_PREVIOUS_COMMIT";
     public static final String GIT_PREVIOUS_SUCCESSFUL_COMMIT = "GIT_PREVIOUS_SUCCESSFUL_COMMIT";
 
@@ -1203,7 +1203,7 @@ public void checkout(Run<?, ?> build, Launcher launcher, FilePath workspace, Tas
         try {
             String shortMessage = getCommitMessage(listener, git, revToBuild);
             listener.getLogger().println("Commit message: \"" + shortMessage + "\"");
-            environment.put(GIT_COMMIT_MESSAGE, shortMessage);
+            environment.put(GIT_COMMIT_TITLE, shortMessage);
         } catch (GitException ge) {
             listener.getLogger().println("Exception logging commit message for " + revToBuild + ": " + ge.getMessage());
         }
@@ -1250,7 +1250,6 @@ private String getCommitMessage(TaskListener listener, GitClient git, final Buil
         return "";
     }
 
-
     /**
      * Build up change log from all the branches that we've merged into {@code revToBuild}.
      *

src/main/resources/hudson/plugins/git/GitSCM/buildEnv.groovy

@@ -3,7 +3,7 @@ package hudson.plugins.git.GitSCM
 def l = namespace(lib.JenkinsTagLib)
 
 // TODO handle GitSCMExtension.populateEnvironmentVariables somehow, say by optionally including GitSCMExtension/buildEnv.groovy; though GIT_{COMMITTER,AUTHOR}_{NAME,EMAIL} are only overridden by UserIdentity
-['GIT_COMMIT', 'GIT_PREVIOUS_COMMIT', 'GIT_PREVIOUS_SUCCESSFUL_COMMIT', 'GIT_BRANCH', 'GIT_LOCAL_BRANCH', 'GIT_CHECKOUT_DIR', 'GIT_URL', 'GIT_COMMITTER_NAME', 'GIT_AUTHOR_NAME', 'GIT_COMMITTER_EMAIL', 'GIT_AUTHOR_EMAIL'].each {name ->
+['GIT_COMMIT', 'GIT_PREVIOUS_COMMIT', 'GIT_PREVIOUS_SUCCESSFUL_COMMIT', 'GIT_BRANCH', 'GIT_LOCAL_BRANCH', 'GIT_CHECKOUT_DIR', 'GIT_URL', 'GIT_COMMITTER_NAME', 'GIT_AUTHOR_NAME', 'GIT_COMMITTER_EMAIL', 'GIT_AUTHOR_EMAIL', 'GIT_COMMIT_TITLE'].each {name ->
     l.buildEnvVar(name: name) {
         raw(_("${name}.blurb"))
     }

src/main/resources/hudson/plugins/git/GitSCM/buildEnv.properties

@@ -1,6 +1,7 @@
 GIT_COMMIT.blurb=The commit hash being checked out.
 GIT_PREVIOUS_COMMIT.blurb=The hash of the commit last built on this branch, if any.
 GIT_PREVIOUS_SUCCESSFUL_COMMIT.blurb=The hash of the commit last successfully built on this branch, if any.
+GIT_COMMIT_TITLE.blurb=The text up to the first blank line in a commit message is treated as the commit title.
 GIT_BRANCH.blurb=The remote branch name, if any.
 GIT_LOCAL_BRANCH.blurb=The local branch name being checked out, if applicable.
 GIT_CHECKOUT_DIR.blurb=The directory that the repository will be checked out to. This contains the value set in Checkout to a sub-directory, if used.

src/test/java/hudson/plugins/git/GitSCMTest.java

@@ -2699,6 +2699,24 @@ public void testCommitMessageIsPrintedToLogs() throws Exception {
         assertThat(values, hasItem("Commit message: \"test commit\""));
     }
 
+    @Test
+    public void testCommitMessageIsEnvVar() throws Exception {
+        String title = "test commit";
+        sampleRepo.init();
+        sampleRepo.write("file", "v1");
+        sampleRepo.git("commit", "--all", "--message", title);
+        FreeStyleProject p = setupSimpleProject("master");
+        Run<?,?> run = rule.buildAndAssertSuccess(p);
+        TaskListener mockListener = Mockito.mock(TaskListener.class);
+        Mockito.when(mockListener.getLogger()).thenReturn(Mockito.spy(StreamTaskListener.fromStdout().getLogger()));
+
+        p.getScm().checkout(run, new Launcher.LocalLauncher(listener),
+                new FilePath(run.getRootDir()).child("tmp-" + "master"),
+                mockListener, null, SCMRevisionState.NONE);
+
+        assertEquals("Commit message should be an env var", getEnvVars(p), title);
+    }
+
     /**
      * Method performs HTTP get on "notifyCommit" URL, passing it commit by SHA1
      * and tests for build data consistency.