[JENKINS-43052] Warn if "Additional Behaviors > Check out to a sub-directory" is used in a Pipeline project #3068
Description
Additional Behaviors > Check out to a sub-directory clones Jenkinsfile in the specified directory. Meanwhile, Jenkins itself continues to look for Jenkinsfile at the top of the workspace. This is very confusing.
As far as I can see, Additional Behaviors > Check out to a sub-directory is never appropriate with Pipeline. This should be handled in Jenkinsfile using dir():
dir('subDir') {
checkout scm
}
In JENKINS-40267, jglick suggested that git-plugin should conditionally display the Additional Behaviors > Check out to a sub-directory option only if the AncestorInPath is an AbstractProject.
Removing the option might break compatibility but we could print an explanatory warning into the build log. The warning would say that Check out to a sub-directory is not intended for use with Pipeline jobs. The message should describe the preferred declarative technique of using the the dir step to provide a subdirectory which contains the checkout or using the checkoutToSubdirectory option.
Originally reported by jmcgeheeiv, imported from: Warn if "Additional Behaviors > Check out to a sub-directory" is used in a Pipeline project
- status: In Review
- priority: Minor
- component(s): git-plugin
- label(s): newbie-friendly, pipeline
- resolution: Unresolved
- votes: 2
- watchers: 6
- imported: 2025-12-02
Raw content of original issue
Additional Behaviors > Check out to a sub-directory clones Jenkinsfile in the specified directory. Meanwhile, Jenkins itself continues to look for Jenkinsfile at the top of the workspace. This is very confusing.
As far as I can see, Additional Behaviors > Check out to a sub-directory is never appropriate with Pipeline. This should be handled in Jenkinsfile using dir():
dir('subDir') { checkout scm }In
JENKINS-40267, jglick suggested that git-plugin should conditionally display the Additional Behaviors > Check out to a sub-directory option only if the AncestorInPath is an AbstractProject.Removing the option might break compatibility but we could print an explanatory warning into the build log. The warning would say that Check out to a sub-directory is not intended for use with Pipeline jobs. The message should describe the preferred declarative technique of using the the dir step to provide a subdirectory which contains the checkout or using the checkoutToSubdirectory option.
environment
Jenkins ver. 2.19.2 <br/>
Pipeline 2.4 <br/>
Pipeline: Multibranch 2.9 <br/>
Ubuntu 16 LTS