[JENKINS-75162] inadequate documentation for gitSCM module

[jenkins-infra-bot]

I'm trying to use
checkout gitSCM (some arguments here)

I see that one example, given at
https://www.jenkins.io/doc/pipeline/steps/params/scmgit/
is

checkout scmGit(userRemoteConfigs: [ [ url: 'https://github.com/jenkinsci/git-plugin' ] ])

Higher up in the page, it mentions,

" Refer to the git plugin documentation for detailed descriptions of options available to the checkout step"

But the referenced page is unusable for this sort of purpose.

I just want to find out what other things can be used in "userRemoteConfigs".

In the referenced page, I see various random examples of that used.
But nowhere do I see a concise reference of the approximate format,

"For userRemoteConfigs, here are the possible options and syntax.

  url: url to the remote repo
  xyz: ....
  abc: ....
"

---

Originally reported by pbrownrobo, imported from: inadequate documentation for gitSCM module

• status: Open
• priority: Minor
• component(s): git-plugin
• resolution: Unresolved
• votes: 0
• watchers: 2
• imported: 2025-12-02

Raw content of original issue

I'm trying to use
checkout gitSCM (some arguments here)

I see that one example, given at
https://www.jenkins.io/doc/pipeline/steps/params/scmgit/
is

checkout scmGit(userRemoteConfigs: [ [ url: 'https://github.com/jenkinsci/git-plugin' ] ])

Higher up in the page, it mentions,

" Refer to the git plugin documentation for detailed descriptions of options available to the checkout step"

But the referenced page is unusable for this sort of purpose.

I just want to find out what other things can be used in "userRemoteConfigs".

In the referenced page, I see various random examples of that used.
But nowhere do I see a concise reference of the approximate format,

"For userRemoteConfigs, here are the possible options and syntax.

  url: url to the remote repo
  xyz: ....
  abc: ....
"

[jenkins-infra-bot]

• Remote link associated with this issue:

  • PR-1711 - Fix plugins.jenkins.io links to jump to correct location within the page

[jenkins-infra-bot]

markewaite:

• Original comment link
• Raw content of original comment:

  Thanks for the feedback.  I agree that there is much to improve in the documentation of the git plugin.
  
  a concise reference of the approximate format
  
  The concise reference of the approximate format is included on the Pipeline steps page in the "Argument Descriptions".  In the section labeled "userRemoteConfigs" there is a "Array / List of Nested Object" that includes the following items:
  
  
  	
  url : String
  	
  name : String
  	
  refspec : String
  	
  credentialsId : String
  
  
  
  Those are the arguments of userRemoteConfigs and each can be expanded to provide more detail.
  
  The link for the "detailed descriptions of options available to the checkout step" is using an incorrect anchor.  It is using https://plugins.jenkins.io/git/#extensions when it should be using https://plugins.jenkins.io/git/#plugin-content-extensions .  I'll  fix that mistake in a future release.
  

Thanks for the feedback. I agree that there is much to improve in the documentation of the git plugin.

a concise reference of the approximate format

The concise reference of the approximate format is included on the Pipeline steps page in the "Argument Descriptions". In the section labeled "userRemoteConfigs" there is a "Array / List of Nested Object" that includes the following items:

• url : String
• name : String
• refspec : String
• credentialsId : String

Those are the arguments of userRemoteConfigs and each can be expanded to provide more detail.

The link for the "detailed descriptions of options available to the checkout step" is using an incorrect anchor. It is using https://plugins.jenkins.io/git/#extensions when it should be using https://plugins.jenkins.io/git/#plugin-content-extensions . I'll fix that mistake in a future release.

[jenkins-infra-bot]

markewaite:

• Original comment link
• Raw content of original comment:

  The link to the detailed descriptions of options available in the checkout step is fixed in PR-1711.  That doesn't address the request for a concise list of possible options and Pipeline syntax, because that page is providing an overview that is applicable for use in any Jenkins job, not just Pipeline jobs.
  

The link to the detailed descriptions of options available in the checkout step is fixed in PR-1711. That doesn't address the request for a concise list of possible options and Pipeline syntax, because that page is providing an overview that is applicable for use in any Jenkins job, not just Pipeline jobs.