From 80bd333984e081d5c9b9a22fd9f03ab1c7f7eaf1 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Mon, 3 Aug 2020 19:27:10 -0600 Subject: [PATCH] Document plugin properties The properties are usually "escape hatches" that allow users to restore a risky behavior or to enable something that is intentionally disabled. --- README.adoc | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.adoc b/README.adoc index 6edceba244..d061b37cb1 100644 --- a/README.adoc +++ b/README.adoc @@ -86,3 +86,47 @@ Report issues and enhancements with the https://issues.jenkins-ci.org[Jenkins is == Contributing to the Plugin Refer to link:CONTRIBUTING.adoc#contributing-to-the-git-client-plugin[contributing to the plugin] for contribution guidelines. + +== Plugin Properties + +Some plugin settings are controlled by Java system properties. +The properties are often used to override a standard behavior or to revert to previous behavior. +Refer to link:https://www.jenkins.io/doc/book/managing/system-properties/[Jenkins Features Controlled with System Properties] for more details on system properties and how to set them. + +checkRemoteURL:: +When `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.checkRemoteURL` is set to `false` it disables the safety checking of repository URLs. ++ +Default is `true` so that repository URL's are rejected if they start with `-` or contain space characters. + +forceFetch:: +When `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.forceFetch` is set to `false` it allows command line git versions 2.20 and later to not update tags which have already been fetched into the workspace. ++ +Command line git 2.20 and later have changed behavior when fetching remote tags that already exist in the repository. +Command line git before 2.20 silently updates an existing tag if the remote tag points to a different SHA1 than the local tag. +Command line git 2.20 and later do not update an existing tag if the remote tag points to a different SHA1 than the local tag unless the `--force` option is passed to `git fetch`. ++ +Default is `true` so that newer command line git versions behave the same as older versions. + +promptForAuthentication:: +When `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.promptForAuthentication` is set to `true` it allows command line git versions 2.3 and later to prompt the user for authentication. +Command line git prompting for authentication should be rare, since Jenkins credentials should be managed through the credentials plugin. ++ +Credential prompting could happen on multiple platforms, but is more common on Windows computers because many Windows agents run from the desktop environment. +Agents running on the desktop are much less common in Unix environments. ++ +Default is `false` so that command line git does not prompt for interactive authentication. + +useCLI:: +When `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.useCLI` is set to `false`, it will use JGit as the default implementation instead of command line git. ++ +Default is `true` so that command line git is chosen as the default implementation. + +useSETSID:: +When `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.useSETSID` is set to `true` and the `setsid` command is available, the git client process on non-Windows computers will be started with the `setsid` command so that they are detached from any controlling terminal. +Most agents are run without a controlling terminal and the `useSETSID` setting is not needed. +Enable `useSETSID` only in those rare cases where the agent is running with a controlling terminal. +If it is not used in those cases, the agent may block on some authenticated git operations. ++ +This setting can be helpful with link:https://plugins.jenkins.io/swarm/[Jenkins swarm agents] and inbound agents started from a terminal emulator. ++ +Default is `false` so that `setsid` is not used.