[JENKINS-75812] Misleading label on git client plugin configuration page

[jenkins-infra-bot]

### Reproduction Steps
1. Configure Global Tool():
   - Name: `MinGit-Auto`
   - Set "Path to Git executable": `mingw64\bin\git.exe`
   - Check "Install automatically(.zip/.tar.gz)"
   - Select "MinGit" installer Url
   - Set "Subdirectory": `MinGit`
2. Create pipeline job:

groovy
   pipeline {
     agent any
     tools { git 'MinGit-Auto' }
     stages {
       stage('Clone') {
         steps {
           git url: 'http://example.com/repo.git'
         }
       }
     }
   }

 

3. Run job :

logs:

 

*Started by user Admin
Running as SYSTEM
Building remotely on [Agent_IP] (windows) in workspace $WORKSPACE_PATH
[WS-CLEANUP] Deleting project workspace...
[WS-CLEANUP] Done
Unpacking https://example.com/git/MinGit-2.50.0-64-bit.zip to $JENKINS_HOME/tools/mingw64/bin/git.exe on [Agent_IP]
The recommended git tool is: NONE
using credential Jenkins
Cloning the remote Git repository
Cloning repository http://example.com/repository.git
 > $JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit init $WORKSPACE_PATH # timeout=10
ERROR: Error cloning remote repo 'origin'
hudson.plugins.git.GitException: Could not init $WORKSPACE_PATH
    ...
Caused by: hudson.plugins.git.GitException: Error performing git command: $JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit init $WORKSPACE_PATH
    ...
Caused by: java.io.IOException: Cannot run program "$JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit" (in directory "$WORKSPACE_PATH"): CreateProcess error=2, 系统找不到指定的文件。
    ...
Caused by: java.io.IOException: CreateProcess error=2, 系统找不到指定的文件。
    ...
ERROR: Error cloning remote repo 'origin'
Finished: FAILURE*

### Expected Behavior
1. MinGit installs to: 
   `$JENKINS_HOME/tools/mingw64/bin/git.exe`
2. Repository clones to: 
   `$WORKSPACE/`

### Actual Behavior
Path reversal occurs:
1. Git executable path becomes invalid:  
   `$JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit`
2. Repository initialization targets workspace path
3. Result: `java.io.IOException: CreateProcess error=2` (文件找不到)

---

Originally reported by paeryu, imported from: Misleading label on git client plugin configuration page

• status: Open
• priority: Minor
• component(s): git-client-plugin
• resolution: Unresolved
• votes: 0
• watchers: 3
• imported: 20251211-071809

Raw content of original issue

### Reproduction Steps
1. Configure Global Tool():
   - Name: `MinGit-Auto`
   - Set "Path to Git executable": `mingw64\bin\git.exe`
   - Check "Install automatically(.zip/.tar.gz)"
   - Select "MinGit" installer Url
   - Set "Subdirectory": `MinGit`
2. Create pipeline job:

groovy
   pipeline {
     agent any
     tools { git 'MinGit-Auto' }
     stages {
       stage('Clone') {
         steps {
           git url: 'http://example.com/repo.git'
         }
       }
     }
   }

 
3. Run job :
logs:
 

*Started by user Admin
Running as SYSTEM
Building remotely on [Agent_IP] (windows) in workspace $WORKSPACE_PATH
[WS-CLEANUP] Deleting project workspace...
[WS-CLEANUP] Done
Unpacking https://example.com/git/MinGit-2.50.0-64-bit.zip to $JENKINS_HOME/tools/mingw64/bin/git.exe on [Agent_IP]
The recommended git tool is: NONE
using credential Jenkins
Cloning the remote Git repository
Cloning repository http://example.com/repository.git
 > $JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit init $WORKSPACE_PATH # timeout=10
ERROR: Error cloning remote repo 'origin'
hudson.plugins.git.GitException: Could not init $WORKSPACE_PATH
    ...
Caused by: hudson.plugins.git.GitException: Error performing git command: $JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit init $WORKSPACE_PATH
    ...
Caused by: java.io.IOException: Cannot run program "$JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit" (in directory "$WORKSPACE_PATH"): CreateProcess error=2, 系统找不到指定的文件。
    ...
Caused by: java.io.IOException: CreateProcess error=2, 系统找不到指定的文件。
    ...
ERROR: Error cloning remote repo 'origin'
Finished: FAILURE*

### Expected Behavior
1. MinGit installs to: 
   `$JENKINS_HOME/tools/mingw64/bin/git.exe`
2. Repository clones to: 
   `$WORKSPACE/<job_name>`
### Actual Behavior
Path reversal occurs:
1. Git executable path becomes invalid:  
   `$JENKINS_HOME/tools/mingw64/bin/git.exe\MinGit`
2. Repository initialization targets workspace path
3. Result: `java.io.IOException: CreateProcess error=2` (文件找不到)

environment

Jenkins: 2.504.2<br/>
OS: Windows Server 2022 - 10.0<br/>
Java: 21.0.7 - BellSoft (OpenJDK 64-Bit Server VM)<br/>
---<br/>
git:5.7.0<br/>
git-client:6.1.3

3 attachments

• Snipaste_2025-06-25_18-50-59.png

  

• image-2025-06-27-13-39-42-608.png

  

• mingit-config-screen.png

  

[jenkins-infra-bot]

markewaite:

• Original comment link
• Raw content of original comment:

  Please provide enough details so that others can duplicate the problem from a fresh Jenkins installation.  "How to report an issue" provides a checklist of the types of information needed so that others can duplicate the issue.
  

Please provide enough details so that others can duplicate the problem from a fresh Jenkins installation. "How to report an issue" provides a checklist of the types of information needed so that others can duplicate the issue.

[jenkins-infra-bot]

markewaite:

• Original comment link
• Raw content of original comment:

  Based on your updated description, it seems like you are not following the MinGit installation configuration instructions from the plugin documentation.  Does it fail in the same way if you configure as described in the documentation?
  

Based on your updated description, it seems like you are not following the MinGit installation configuration instructions from the plugin documentation. Does it fail in the same way if you configure as described in the documentation?

[jenkins-infra-bot]

paeryu:

• Original comment link
• Raw content of original comment:

  Thank you for pointing me to the documentation. I did follow the exact installation steps as described, and here's what I observed:
  
  1、As per documentation:
  
  Path to Git executable: "tools\git\mingw64\bin\git.exe"
  Subdirectory: "mingw64\bin\git.exe"
  
   
  
  2、Logs will be:
  
   
  
  *[WS-CLEANUP] Done
  Unpacking https://example.com/git/MinGit-2.50.0-64-bit.zip to $JENKINS_HOME/tools/mingw64/bin/git.exe on [Agent_IP]
  The recommended git tool is: NONE
  using credential Jenkins
  Cloning the remote Git repository
  Cloning repository http://example.com/repository.git
   > $JENKINS_HOME/tools/mingw64/bin/git.exe/mingw64/bin/git.exe init $WORKSPACE_PATH # timeout=10*
  
   
   
  3.Issue analysis:{}
  
  	
  Path to Git executable
  
  Intended purpose: This should specify the final executable filename (e.g., git.exe)
  
  	
  Subdirectory 
  
  Intended purpose: This should specify the subdirectory path where Git resides 
  
  	
  Visual representation
  
   
  
  # Expected structure
  tools/
  └── git/
      └── mingw64/
          └── bin/
              └── git.exe  # Correct executable# Actual structure
  tools/
  └── git/
      ├── mingw64/          
      │   └── bin/
      │        └── git.exe/   # WRONG: Created as directory
      │             └── mingw64/
      │                    └── bin/
      │                           └── git.exe
  
   
   
   
  

Thank you for pointing me to the documentation. I did follow the exact installation steps as described, and here's what I observed:

1、As per documentation:

Path to Git executable: "tools\git\mingw64\bin\git.exe"
Subdirectory: "mingw64\bin\git.exe"

 

2、Logs will be:

 

*[WS-CLEANUP] Done
Unpacking https://example.com/git/MinGit-2.50.0-64-bit.zip to $JENKINS_HOME/tools/mingw64/bin/git.exe on [Agent_IP]
The recommended git tool is: NONE
using credential Jenkins
Cloning the remote Git repository
Cloning repository http://example.com/repository.git
 > $JENKINS_HOME/tools/mingw64/bin/git.exe/mingw64/bin/git.exe init $WORKSPACE_PATH # timeout=10*

 

 

3.Issue analysis:{}

• Path to Git executable

Intended purpose: This should specify the final executable filename (e.g., git.exe)

• Subdirectory 

Intended purpose: This should specify the subdirectory path where Git resides 

• Visual representation

 

# Expected structure
tools/
└── git/
    └── mingw64/
        └── bin/
            └── git.exe  # Correct executable# Actual structure
tools/
└── git/
    ├── mingw64/          
    │   └── bin/
    │        └── git.exe/   # WRONG: Created as directory
    │             └── mingw64/
    │            └── bin/
    │           └── git.exe

 

 

 

[jenkins-infra-bot]

markewaite:

• Original comment link
• Raw content of original comment:

  I cannot duplicate the issue that you are reporting.  I think that may be because you are mislead by the label on the field and are not placing the value from the documentation in the field.  On my Windows 11 computer, I followed the documentation and defined a new MinGit-Auto tool then used it to download a git repository.  My configuration screen looked like this:
  
    
  
  The console log from my job included this:
  
  
  Unpacking https://home.markwaite.net/~mwaite/git/MinGit-2.50.0-64-bit.zip to C:\Users\MarkE\tmp\JENKINS-75812\tools\git on Jenkins
  The recommended git tool is: NONE
  No credentials specified
  Cloning the remote Git repository
  Cloning repository https://github.com/MarkEWaite/implied-labels-plugin.git
   > C:\Users\MarkE\tmp\JENKINS-75812\tools\git\mingw64\bin\git.exe init C:\Users\MarkE\tmp\JENKINS-75812\workspace\MinGit-test # timeout=10
  Fetching upstream changes from https://github.com/MarkEWaite/implied-labels-plugin.git
   > C:\Users\MarkE\tmp\JENKINS-75812\tools\git\mingw64\bin\git.exe --version # timeout=10
   > git --version # 'git version 2.50.0.windows.1'
   > C:\Users\MarkE\tmp\JENKINS-75812\tools\git\mingw64\bin\git.exe fetch --tags --force --progress -- https://github.com/MarkEWaite/implied-labels-plugin.git +refs/heads/*:refs/remotes/origin/* # timeout=10
  
  
  

I cannot duplicate the issue that you are reporting. I think that may be because you are mislead by the label on the field and are not placing the value from the documentation in the field. On my Windows 11 computer, I followed the documentation and defined a new MinGit-Auto tool then used it to download a git repository. My configuration screen looked like this:

The console log from my job included this:

Unpacking https://home.markwaite.net/~mwaite/git/MinGit-2.50.0-64-bit.zip to C:\Users\MarkE\tmp\JENKINS-75812\tools\git on Jenkins
The recommended git tool is: NONE
No credentials specified
Cloning the remote Git repository
Cloning repository https://github.com/MarkEWaite/implied-labels-plugin.git
 > C:\Users\MarkE\tmp\JENKINS-75812\tools\git\mingw64\bin\git.exe init C:\Users\MarkE\tmp\JENKINS-75812\workspace\MinGit-test # timeout=10
Fetching upstream changes from https://github.com/MarkEWaite/implied-labels-plugin.git
 > C:\Users\MarkE\tmp\JENKINS-75812\tools\git\mingw64\bin\git.exe --version # timeout=10
 > git --version # 'git version 2.50.0.windows.1'
 > C:\Users\MarkE\tmp\JENKINS-75812\tools\git\mingw64\bin\git.exe fetch --tags --force --progress -- https://github.com/MarkEWaite/implied-labels-plugin.git +refs/heads/*:refs/remotes/origin/* # timeout=10

[jenkins-infra-bot]

paeryu:

• Original comment link
• Raw content of original comment:

  markewaite I appreciate your testing, but the fundamental issue remains: the fields' labels contradict their actual functionality. This isn't about documentation - it's a design flaw in the configuration interface.
  Core Problem:
  
  	
  "Path to Git executable"
  
  
  
  
  	
  
  	
  
  		
  Implied meaning: Full path to executable (e.g., mingw64/bin/git.exe)
  		
  Actual function: Subfolder name (git)
  	
  	
  
  
  	
  "Subdirectory"
  
  
  
  
  	
  
  	
  
  		
  Implied meaning: Subfolder name (e.g., MinGit)
  		
  Actual function: Defines the full installation path (e.g., mingw64/bin/git.exe)
  	
  	
  
  
  
  Consequences:
  
  	
  Interface Misleads Users: The labels encourage incorrect configurations
  	
  System Fragility: When other plugins (e.g., SCM handlers) retrieve the Git path: other plugins can't locate real Git binary
  
  
  
  
  

markewaite I appreciate your testing, but the fundamental issue remains: the fields' labels contradict their actual functionality. This isn't about documentation - it's a design flaw in the configuration interface.

Core Problem:

1. "Path to Git executable"

• • Implied meaning: Full path to executable (e.g., mingw64/bin/git.exe)
  • Actual function: Subfolder name (git)

1. "Subdirectory"

• • Implied meaning: Subfolder name (e.g., MinGit)
  • Actual function: Defines the full installation path (e.g., mingw64/bin/git.exe)

Consequences:

• Interface Misleads Users: The labels encourage incorrect configurations
• System Fragility: When other plugins (e.g., SCM handlers) retrieve the Git path: other plugins can't locate real Git binary

[jenkins-infra-bot]

markewaite:

• Original comment link
• Raw content of original comment:

  the fundamental issue remains: the fields' labels contradict their actual functionality. This isn't about documentation - it's a design flaw in the configuration interface.
  
  Yes, I agree that is the fundamental issue.  The documentation is written that way because that is the configuration that works well in the most conditions.  There is an implementation flaw in the git client plugin that is visible to users through those labels.
  
  The git client plugin makes the mistake of using the value of "Path to Git executable" value in the getGitExe method but receives that value from a field named "home".  It also passes the value of the field named "home" to the ToolInstallation constructor so that it is used as the home directory of the tool.  The field named "home" is used by other tool installers (like JDK, Maven, and Ant) to only define the home directory of the tool.  
  
  The use of "home" to define the home directory of the tool is the correct usage, but the git client plugin does more than that, it uses the same field to define the name of the git executable.  You can see that in the GitTool constructor use of the "home" field and in the getGitExe use of getHome().  The ToolInstallation javadoc states that the home field is the home directory of the tool, but the git client plugin uses that field as both the home directory of the tool and the name of the git executable.
  
  I have not attempted to adjust those field labels or field usages for fear of breaking compatibility or losing clarity in other cases.  Using the simple value "git" for the "Path to Git executable" works well when a Windows controller has Windows agents and when a Windows controller has Linux agents.  It works well when a Linux controller has Windows agents and when a Linux controller has Linux agents.
  
  The git client plugin use of "home" as the path to the git executable is inconsistent with the other tool installers.  Unfortunately, that has been the behavior of the git client plugin for over 10 years.  Changing that behavior of the git client plugin will likely break many Jenkins users without providing significant benefit.
  

the fundamental issue remains: the fields' labels contradict their actual functionality. This isn't about documentation - it's a design flaw in the configuration interface.

Yes, I agree that is the fundamental issue. The documentation is written that way because that is the configuration that works well in the most conditions. There is an implementation flaw in the git client plugin that is visible to users through those labels.

The git client plugin makes the mistake of using the value of "Path to Git executable" value in the getGitExe method but receives that value from a field named "home". It also passes the value of the field named "home" to the ToolInstallation constructor so that it is used as the home directory of the tool. The field named "home" is used by other tool installers (like JDK, Maven, and Ant) to only define the home directory of the tool.

The use of "home" to define the home directory of the tool is the correct usage, but the git client plugin does more than that, it uses the same field to define the name of the git executable. You can see that in the GitTool constructor use of the "home" field and in the getGitExe use of getHome(). The ToolInstallation javadoc states that the home field is the home directory of the tool, but the git client plugin uses that field as both the home directory of the tool and the name of the git executable.

I have not attempted to adjust those field labels or field usages for fear of breaking compatibility or losing clarity in other cases. Using the simple value "git" for the "Path to Git executable" works well when a Windows controller has Windows agents and when a Windows controller has Linux agents. It works well when a Linux controller has Windows agents and when a Linux controller has Linux agents.

The git client plugin use of "home" as the path to the git executable is inconsistent with the other tool installers. Unfortunately, that has been the behavior of the git client plugin for over 10 years. Changing that behavior of the git client plugin will likely break many Jenkins users without providing significant benefit.

[jenkins-infra-bot]

paeryu:

• Original comment link
• Raw content of original comment:

  Thank you for acknowledging the design inconsistency. To help users avoid configuration pitfalls, could we explore:
  
  	
  Documenting the legacy behavior
  	
  Clarifying UI labels{}
  	
  Only modify the git client plugin
  
  
  
  We're seeing real user confusion:
  
  	
  {}Git Branch Source plugin shows false "git executable not found" warnings
  	
  Repository URL validation consistently fails in job configuration screens
  
  
  

Thank you for acknowledging the design inconsistency. To help users avoid configuration pitfalls, could we explore:

• Documenting the legacy behavior
• Clarifying UI labels{}
• Only modify the git client plugin

We're seeing real user confusion:

• {}Git Branch Source plugin shows false "git executable not found" warnings
• Repository URL validation consistently fails in job configuration screens

[jenkins-infra-bot]

markewaite:

• Original comment link
• Raw content of original comment:

  
  To help users avoid configuration pitfalls, could we explore:
  
  	
  Documenting the legacy behavior
  	
  Clarifying UI labels
  	
  Only modify the git client plugin
  
  
  
  The legacy behavior is documented in the git client plugin documentation as part of the MinGit tool description .
  
  I'm open to pull requests that improve the UI labels so long as they are supported by automated tests that confirm the improved UI labels are still accurate for all the cases.
  We're seeing real user confusion:
  
  	
  Git Branch Source plugin shows false "git executable not found" warnings
  	
  Repository URL validation consistently fails in job configuration screen
  
  
  Are users confused even when they follow the documentation? Repository URL validation does not fail in my controller when the correct tool configuration is used. Git branch source does not report "git executable not found" in my controller.
  
  Do users click the "?" link next to the field description when they are confused? If so, then we might consider adding more details to the online help that might help some of them be more successful.
  
  The "Path to git executable" online help includes the following help text currently:
  Set path to git executable. This can be just "git" or complete path.
  The "Subdirectory of extracted archive" is using the help provided by the tool installation parent code.
  
  In the more general case, I prefer to have git already installed on the agent images so that jobs do not waste time downloading and installing git each time they run. That is already a recommendation in the JDK tool installer where it says:
  The recommended approach is to download the JDK distribution using other installers, for example downloading it from a well known URL (preferably hosted on your own network) with ZIP Tool Installer, having it pre-installed in agent docker images, or executing a script to do the job. If an external download is needed due to any reason,
  

To help users avoid configuration pitfalls, could we explore:

• Documenting the legacy behavior
• Clarifying UI labels
• Only modify the git client plugin

The legacy behavior is documented in the git client plugin documentation as part of the MinGit tool description .

I'm open to pull requests that improve the UI labels so long as they are supported by automated tests that confirm the improved UI labels are still accurate for all the cases.

We're seeing real user confusion:

• Git Branch Source plugin shows false "git executable not found" warnings
• Repository URL validation consistently fails in job configuration screen

Are users confused even when they follow the documentation? Repository URL validation does not fail in my controller when the correct tool configuration is used. Git branch source does not report "git executable not found" in my controller.

Do users click the "?" link next to the field description when they are confused? If so, then we might consider adding more details to the online help that might help some of them be more successful.

The "Path to git executable" online help includes the following help text currently:

Set path to git executable. This can be just "git" or complete path.

The "Subdirectory of extracted archive" is using the help provided by the tool installation parent code.

In the more general case, I prefer to have git already installed on the agent images so that jobs do not waste time downloading and installing git each time they run. That is already a recommendation in the JDK tool installer where it says:

The recommended approach is to download the JDK distribution using other installers, for example downloading it from a well known URL (preferably hosted on your own network) with ZIP Tool Installer, having it pre-installed in agent docker images, or executing a script to do the job. If an external download is needed due to any reason,

[jenkins-infra-bot]

paeryu:

• Original comment link
• Raw content of original comment:

  Thank you for the clarification on documentation and willingness to review UI improvements. We understand the historical constraints and respect the compatibility priorities.
  
  To summarize where we land:
  
  	
  Will reference MinGit documentation when guiding Windows users
  	
  Will pause further changes since current configurations work when following the docs
  	
  Appreciate your openness to future PRs with automated tests
  
  
  
  Thanks for your consistent maintenance of this critical plugin.
  

Thank you for the clarification on documentation and willingness to review UI improvements. We understand the historical constraints and respect the compatibility priorities.

To summarize where we land:

1. Will reference MinGit documentation when guiding Windows users
2. Will pause further changes since current configurations work when following the docs
3. Appreciate your openness to future PRs with automated tests

Thanks for your consistent maintenance of this critical plugin.