Merge branch 'stable-3.x'

Author: MarkEWaite

README.md

@@ -1,77 +1,244 @@
-# Git SCM plugin for Jenkins
+# Git plugin
 
-![Plugin Version](https://img.shields.io/jenkins/plugin/v/git.svg?label=version) [![Build Status](https://ci.jenkins.io/buildStatus/icon?job=Plugins/git-plugin/master)](https://ci.jenkins.io/job/Plugins/job/gitplugin/job/master/)
+[![Build Status](https://ci.jenkins.io/job/Plugins/job/git-plugin/job/master/badge/icon)](https://ci.jenkins.io/job/Plugins/job/git-plugin/job/master/)
+[![Contributors](https://img.shields.io/github/contributors/jenkinsci/git-plugin.svg)](https://github.com/jenkinsci/git-plugin/graphs/contributors)
+[![GitHub release](https://img.shields.io/github/release/jenkinsci/git-plugin.svg?label=release)](https://github.com/jenkinsci/git-plugin/releases/latest)
 
-Git software configuration management for Jenkins.
+<img src="https://git-scm.com/images/logos/downloads/Git-Logo-2Color.png" width="303">
 
-* see [Jenkins Wiki](https://plugins.jenkins.io/git) for feature descriptions
-* use [Jenkins JIRA](https://issues.jenkins-ci.org) to report issues or request features
+## Introduction
 
-## Requirements
+The git plugin provides fundamental git operations for Jenkins projects.
+It can poll, fetch, checkout, branch, list, merge, and tag repositories.
 
-* Jenkins `2.138.4` or newer
+## Contents
 
-## Development
+* [Changelog](#changelog)
+* [Configuration](#configuration)
+* [Extensions](#extensions)
+* [Environment Variables](#environment-variables)
+* [Properties](#properties)
+// * [Pipelines](#pipelines)
+// * [Performance Tuning](#performance-tuning)
+// * [Reference repositories](#reference-repositories)
+* [Combining repositories](#combining-repositories)
+* [Bug Reports](#bug-reports)
+* [Contributing to the Plugin](#contributing-to-the-plugin)
 
-### Branches
+## Changelog
 
-The `master` branch is the primary development branch.
+Release notes are recorded in [GitHub](https://github.com/jenkinsci/git-plugin/releases) beginning with git plugin 3.10.1.
+Prior release notes are recorded on the [Jenkins wiki](https://wiki.jenkins.io/display/JENKINS/Git+Plugin#GitPlugin-ChangeLog-MovedtoGitHub).
 
-Branches using name pattern `stable-{VERSION}` are development branches
-for changes from a base release `VERSION`. For example `stable-3.x` is the
-branch used to release fixes for plugin version `3.x`.
+## Configuration
 
-### Building the Plugin
+### Using Credentials
 
-To build the plugin you will need
-* [Maven](https://maven.apache.org/) version `3.5.4` or newer
-* [Java Development Kit (JDK)](https://jdk.java.net/) version `8` or version `11`
+The git plugin supports username / password credentials and private key credentials provided by the [Jenkins credentials plugin](https://plugins.jenkins.io/credentials).
+Select credentials from the job definition drop down menu or enter their identifiers in Pipeline job definitions.
 
-Run the following command to build the plugin (Java 8)
+### Push Notifications
 
-```shell
-mvn package
-```
+### Enabling JGit
 
-Run the following command to build the plugin (Java 11)
+See the [git client plugin documentation](https://plugins.jenkins.io/git-client) for instructions to enable JGit.
+JGit becomes available throughout Jenkins once it has been enabled.
 
-```shell
-mvn -Djenkins.version=2.164.1 package
-```
+## Extensions
 
-### Contributing to the Plugin
+### Advanced checkout behaviors
 
-Plugin source code is hosted on [GitHub](https://github.com/jenkinsci/git-plugin).
-New feature proposals and bug fix proposals should be submitted as
-[pull requests](https://help.github.com/articles/creating-a-pull-request).
-Fork the repository. Make the desired changes in your forked copy. Submit
-a pull request to the `master` branch. Your pull request will be evaluated
-by the [Jenkins job](https://ci.jenkins.io/job/Plugins/job/git-plugin/).
+Timeout (in minutes) for checkout operation::
+  Specify a timeout (in minutes) for checkout.
 
-Before submitting your pull request, please add tests which verify your
-change. There have been many developers involved in the git plugin and
-there are many users who depend on the git plugin. Tests help us assure
-that we're delivering a reliable plugin and that we've communicated
-our intent to other developers in a way that they can detect when they
-run tests.
+### Advanced clone behaviours
 
-Code coverage reporting is available as a maven target and is actively
-monitored. Please improve code coverage with the tests you submit.
-Code coverage reporting is written to `target/site/jacoco/` by the maven command
+Fetch tags::
+  Deselect this to perform a clone without tags, saving time and disk space when you just want to access what is specified by the refspec.
 
-```shell
-mvn -P enable-jacoco clean install jacoco:report
-```
+Honor refspec on initial clone::
+  Perform initial clone using the refspec defined for the repository.
+  This can save time, data transfer and disk space when you only need to access the references specified by the refspec.
+
+Shallow clone::
+  Perform shallow clone.
+  Git will not download the complete history of the project, saving time and disk space when you just want to access the latest version of a repository.
+
+Shallow clone depth::
+  Set shallow clone depth to the specified numebr of commits.
+  Git will only download that many commits from the remote repository, saving time and disk space.
+
+[[clone-reference-repository-path,reference repository path]]
+Path of the reference repo to use during clone::
+  Specify a folder containing a repository that will be used by git as a reference during clone operations.
+  This option will be ignored if the folder is not available on the agent.
+
+Timeout (in minutes) for clone and fetch operations::
+  Specify a timeout (in minutes) for clone and fetch operations.
+
+### Advanced sub-modules behaviours
+
+Disable submodules processing::
+  Ignore submodules in the repository.
+
+Recursively update submodules::
+  Retrieve all submodules recursively.
+  Without this option, submodules which contain other submodules will ignore the contained submodules.
+
+Update tracking submodules to tip of branch::
+  Retrieve the tip of the configured branch in .gitmodules.
+
+Use credentials from default remote of parent repository::
+  Use credentials from the default remote of the parent project.
+  Submodule updates do not use credentials by default.
+  Enabling this extension will provide the parent repository credentials to each of the submodule repositories.
+  Submodule credentials require that the submodule repository must accept the same credentials as the parent project.
+  If the parent project is cloned with https, then the authenticated submodule references must use https as well.
+  If the parent project is cloned with ssh, then the authenticated submodule references must use ssh as well.
+
+Shallow clone::
+  Perform shallow clone of submodules.
+  Git will not download the complete history of the project, saving time and disk space.
+
+Shallow clone depth::
+  Set shallow clone depth for submodules.
+  Git will only download recent history of the project, saving time and disk space.
+
+Path of the reference repo to use during submodule update::
+  Folder containing a repository that will be used by git as a reference during submodule clone operations.
+  This option will be ignored if the folder is not available on the agent running the build.
+  A reference repository may contain multiple subprojects.
+  See the [combining repositories](#combining-repositories) section for more details.
+
+Timeout (in minutes) for submodules operations::
+  Specify a timeout (in minutes) for submodules operations.
+  This option overrides the default timeout.
+
+Number of threads to use when updating submodules::
+  Number of parallel processes to be used when updating submodules.
+  Default is to use a single thread for submodule updates
+
+### Calculate changelog against a specific branch
+
+Name of repository::
+  Name of the repository, such as origin, that contains the branch.
+
+Name of branch::
+  Name of the branch used for the changelog calculation within the named repository.
+
+### Checkout to a sub-directory
+
+Specify a local directory (relative to the workspace root) where the git repository will be checked out.
+If left empty, the workspace root itself will be used.
+
+### Checkout to specific local branch
+
+Branch name::
+  If given, checkout the revision to build as HEAD on the named branch.
+  If value is an empty string or "**", then the branch name is computed from the remote branch without the origin.
+  In that case, a remote branch origin/master will be checked out to a local branch named master, and a remote branch origin/develop/new-feature will be checked out to a local branch named develop/newfeature.
+
+### Clean after checkout
+
+Clean the workspace **after** every checkout by deleting all untracked files and directories, including those which are specified in .gitignore.
+Resets all tracked files to their versioned state.
+Ensures that the workspace is in the same state as if cloned and checkout were performed in a new workspace.
+Reduces the risk that current build will be affected by files generated by prior builds.
+Does not remove files outside the workspace (like temporary files or cache files).
+Does not remove files in the `.git` repository of the workspace.
+
+### Clean before checkout
 
-Before submitting your change, review the SpotBugs output to
-assure that you haven't introduced new warnings.
+Clean the workspace **before** every checkout by deleting all untracked files and directories, including those which are specified in .gitignore.
+Resets all tracked files to their versioned state.
+Ensures that the workspace is in the same state as if cloned and checkout were performed in a new workspace.
+Reduces the risk that current build will be affected by files generated by prior builds.
+Does not remove files outside the workspace (like temporary files or cache files).
+Does not remove files in the `.git` repository of the workspace.
 
-```shell
-mvn spotbugs:check
+### Create a tag for every build
+
+Create a tag in the workspace for every build to unambiguously mark the commit that was built.
+You can combine this with Git publisher to push the tags to the remote repository.
+
+### Custom SCM name - __Deprecated__
+
+Unique name for this SCM.
+Was needed when using Git within the Multi SCM plugin.
+Pipeline is the robust and feature-rich way to checkout from multiple repositories in a single job.
+
+### Custom user name/e-mail address
+
+user.name::
+  Defines the user name value which git will assign to new commits made in the workspace.
+  If given, `git config user.name [this]` is called before builds.
+  This overrides values from the global settings.
+
+user.email::
+  Defines the user email value which git will assign to new commits made in the workspace.
+  If given, `git config user.email [this]` is called before builds.
+  This overrides whatever is in the global settings.
+
+// ### Don't trigger a build on commit notifications
+// ### Force polling using workspace
+// ### Git LFS pull after checkout
+// ### Merge before build
+// ### Polling ignores commits from certain users
+// ### Polling ignores commits in certain paths
+// ### Polling ignores commits with certain messages
+
+### Prune stale remote tracking branches
+
+Runs `git remote prune` for each remote to prune obsolete local branches.
+
+// ### Sparse checkout paths
+// ### Strategy for choosing what to build
+
+### Use commit author in changelog
+
+The default behavior is to use the Git commit's "Committer" value in build changesets.
+If this option is selected, the git commit's "Author" value is used instead.
+
+// ### Wipe out repository and force clone
+
+## Environment Variables
+
+## Properties
+
+Some git plugin settings can only be controlled from command line properties set at Jenkins startup.
+
+Default timeout::
+  The default initial git timeout value can be overridden through the property `org.jenkinsci.plugins.gitclient.Git.timeOut` (see [JENKINS-11286](https://issues.jenkins-ci.org/browse/JENKINS-11286)).
+  The property should be set on both master and agent to have effect (see [JENKINS-22547](https://issues.jenkins-ci.org/browse/JENKINS-22547)).
+
+// ## Pipelines
+
+// ## Performance Tuning
+
+// ### Reference repositories
+
+### Combining repositories
+
+A single reference repository may contain commits from multiple repositories.
+For example, if a repository named `parent` includes references to submodules `child-1` and `child-2`, a reference repository could be created to cache commits from all three repositories using the commands:
+```
+$ mkdir multirepository-cache.git
+$ cd  multirepository-cache.git
+$ git init --bare
+$ git remote add parent https://github.com/jenkinsci/git-plugin
+$ git remote add child-1 https://github.com/jenkinsci/git-client-plugin
+$ git remote add child-2 https://github.com/jenkinsci/platformlabeler-plugin
+$ git fetch --all
 ```
 
-## To Do
+Those commands will create a single bare repository which includes the current commits from all three repositories.
+If that reference repository is used in the advanced clone options <<clone-reference-repository-path>>, it will reduce data transfer and disc use for the parent repository.
+If that reference repository is used in the submodule options <<submodule-reference-repository-path>>, it will reduce data transfer and disc use for the submodule repositories.
+
+## Bug Reports
+
+Report issues and enhancements in the [Jenkins issue tracker](https://issues.jenkins-ci.org).
+
+## Contributing to the Plugin
 
-* Fix [bugs](https://issues.jenkins-ci.org/secure/IssueNavigator.jspa?mode=hide&reset=true&jqlQuery=project+%3D+JENKINS+AND+status+in+%28Open%2C+"In+Progress"%2C+Reopened%29+AND+component+%3D+git-plugin)
-* Improve code coverage
-* Improve javadoc
+Refer to [contributing to the plugin](CONTRIBUTING.md) for contribution guidelines.

pom.xml

@@ -20,7 +20,7 @@
   <packaging>hpi</packaging>
   <name>Jenkins Git plugin</name>
   <description>Integrates Jenkins with GIT SCM</description>
-  <url>https://wiki.jenkins.io/display/JENKINS/Git+Plugin</url>
+  <url>https://github.com/jenkinsci/git-plugin</url>
   <inceptionYear>2007</inceptionYear>
 
   <properties>
@@ -32,9 +32,10 @@
     <useBeta>true</useBeta>
     <concurrency>1C</concurrency>
     <scm-api-plugin.version>2.6.3</scm-api-plugin.version>
-    <jcasc.version>1.29</jcasc.version>
+    <jcasc.version>1.30</jcasc.version>
     <maven.checkstyle.plugin.version>3.1.0</maven.checkstyle.plugin.version>
     <maven.checkstyle.version>8.24</maven.checkstyle.version>
+    <linkXRef>false</linkXRef>
   </properties>
 
   <build>

src/test/java/jenkins/plugins/git/GitJCasCCompatibilityTest.java

@@ -35,6 +35,6 @@ protected void assertConfiguredAsExpected(RestartableJenkinsRule restartableJenk
 
     @Override
     protected String stringInLogExpected() {
-        return "Setting class hudson.plugins.git.SubmoduleConfig. branches = [mybranch-3, mybranch-4]";
+        return "Setting class hudson.plugins.git.SubmoduleConfig.branches = [mybranch-3, mybranch-4]";
     }
 }