How Bitbucket Server / Data Center searches for git executable to be used on the server during startup
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
In order for Bitbucket to successfully start it has to find a valid git executable on the server. Now as a user you would rarely be concerned about the algorithm that Bitbucket uses to look for a valid git executable on the server if you just have one git version/executable installed on the server. However in case where there are multiple versions of git installed on the server at different locations, it is worth understanding how Bitbucket searches for available git executables and how it decides which one to use.
Solution
Order in which Bitbucket searches for the git executable
In order to log the process for troubleshooting, enable TRACE logging for the class com.atlassian.stash.internal.scm.git.binary.DefaultGitBinaryHelper during Bitbucket startup.
Bitbucket Server / Data Center searches for a valid git executable on the server in the following order:
Explicitly configured git executable path
Bitbucket first looks for the explicitly configured git executable path in bitbucket.properties using the configuration parameter plugin.bitbucket-git.path.executable.
Now Bitbucket will give this highest priority when looking for valid git executables on the server.
1
2
3
2022-09-13 18:34:12,142 INFO [main] c.a.s.i.s.g.b.DefaultGitBinaryHelper Switching to log level [TRACE]
2022-09-13 18:35:01,789 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking the configured git executable: /opt/git-2.34.1/git
2022-09-13 18:35:01,794 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Using explicitly configured git executable at /opt/git-2.34.1/gitOS PATH Environment variable
If no explicit git path has been configured or if Bitbucket does not find a valid git executable in the configured path, it next searches for git through all the directories in the OS PATH environment variable in the order they are stored to check if it can find one there.
1
2
3
4
5
6
2022-09-13 10:45:15,021 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Searching PATH for git executable
2022-09-13 10:45:15,021 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/bin
2022-09-13 10:45:15,023 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /bin
2022-09-13 10:45:15,026 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /bin/git
2022-09-13 10:45:15,033 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.34.1 at /bin/git
2022-09-13 10:45:40,096 INFO [spring-startup] c.a.s.internal.scm.PluginScmService Bitbucket is using /bin/git version 2.34.1You can verify the value of the PATH variable that the Bitbucket service user is seeing from the application.xml file in the instance Support Zip.
1
2
<environment-variables>
<PATH>/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin</PATH>Default Locations
If Bitbucket does not find git in the OS PATH Environment variable it next searches through some hardcoded default locations.
For systems such as Linux and Mac the default locations are:
1
2
3
4
5
"/usr/bin", "/bin", "/usr/sbin", "/sbin", // standard paths (should already be in the PATH env)
"/usr/local/bin", // Homebrew
"/opt/local/bin", // MacPort
"/usr/local/git/bin", // git-osx-installer
"/opt/bin", SystemUtils.USER_HOME + "/bin");For systems such as Windows:
1
2
3
"C:\\Program Files (x86)\\Git\\bin", "C:\\Program Files\\Git\\bin", // msysgit
"C:\\Cygwin\\bin", // cygwin git
"C:\\Git\\bin");Below logs show Bitbucket first searches in PATH and then in the Default locations where it finds the git executable.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2022-09-13 18:38:45,885 INFO [main] c.a.s.i.s.g.b.DefaultGitBinaryHelper Switching to log level [TRACE]
2022-09-13 18:39:34,578 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Searching PATH for git executable
2022-09-13 18:39:34,578 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/bin
2022-09-13 18:39:34,580 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /bin
2022-09-13 18:39:34,580 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/bin
2022-09-13 18:39:34,580 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/sbin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/sbin
2022-09-13 18:39:34,581 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Searching default locations for git executable
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/bin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /bin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/sbin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /sbin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/bin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /opt/local/bin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/git/bin
2022-09-13 18:39:34,581 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /opt/bin
2022-09-13 18:39:34,584 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /opt/bin/git
2022-09-13 18:39:34,589 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.34.1 at /opt/bin/git
2022-09-13 18:40:02,332 INFO [spring-startup] c.a.s.internal.scm.PluginScmService Bitbucket is using /opt/bin/git version 2.34.1MINIMUM_REQUIRED_VERSION and NEXT_MINIMUM_VERSION
Minimum Required Version
This is the minimum git version supported by your Bitbucket instance. This check is a show stopper and will prevent Bitbucket from starting if not met.
Even if the git executable configured explicitly does not meet the MINIMUM_REQUIRED_VERSION criteria, Bitbucket would still keep on looking through PATH and Default locations until it finds a git executable that meets the minimum required version.
In the below example we can see Bitbucket discards the explicitly configured git path since it does not meet the MINIMUM_REQUIRED_VERSION criteria and proceed to search further in the PATH as well as Default locations.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2022-09-13 18:57:03,298 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking the configured git executable: /opt/git-1.8.3.1/git
2022-09-13 18:57:03,303 WARN [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper The configured git executable, /opt/git-1.8.3.1/git, is version 1.8.3.1; 2.11.0 is the minimum required version
2022-09-13 18:57:03,306 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Searching PATH for git executable
2022-09-13 18:57:03,306 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/bin
2022-09-13 18:57:03,309 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /bin
2022-09-13 18:57:03,309 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/bin
2022-09-13 18:57:03,309 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/sbin
2022-09-13 18:57:03,309 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/sbin
2022-09-13 18:57:03,309 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Searching default locations for git executable
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/bin
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /bin
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/sbin
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /sbin
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/bin
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /opt/local/bin
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/git/bin
2022-09-13 18:57:03,310 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /opt/bin
2022-09-13 18:57:03,312 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /opt/bin/git
2022-09-13 18:57:03,321 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.34.1 at /opt/bin/git
2022-09-13 18:57:28,953 INFO [spring-startup] c.a.s.internal.scm.PluginScmService Bitbucket is using /opt/bin/git version 2.34.1Next Minimum Version
This is the minimum git version required by the next major Bitbucket version. This check is not a show stopper and Bitbucket would still startup with a warning.
In case the explicitly configured git executable path does meet the NEXT_MINIMUM_VERSION criteria, Bitbucket would still use that version of git but with a warning as shown below.
1
2
3
4
2022-09-13 19:16:31,033 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking the configured git executable: /opt/git-2.24.1/git
2022-09-13 19:16:31,038 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Using explicitly configured git executable at /opt/git-2.24.1/git
2022-09-13 19:16:31,039 WARN [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper /opt/git-2.24.1/git is version 2.24.1. The next major Bitbucket version will require Git 2.31.0 or higher.
2022-09-13 19:16:58,557 INFO [spring-startup] c.a.s.internal.scm.PluginScmService Bitbucket is using /opt/git-2.24.1/git version 2.24.1In case Bitbucket finds a git executable while scanning PATH (or the default locations) that does not meet the NEXT_MINIMUM_VERSION, Bitbucket would still keep looking till it either finds one that meets the criteria or till it runs out of options.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
2022-09-13 19:26:13,785 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Searching PATH for git executable
2022-09-13 19:26:13,785 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/bin
2022-09-13 19:26:13,788 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /bin
2022-09-13 19:26:13,793 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /bin/git
2022-09-13 19:26:13,799 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.24.1 at /bin/git
2022-09-13 19:26:13,799 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/bin
2022-09-13 19:26:13,800 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /usr/bin/git
2022-09-13 19:26:13,809 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.24.1 at /usr/bin/git
2022-09-13 19:26:13,809 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/sbin
2022-09-13 19:26:13,809 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/sbin
2022-09-13 19:26:13,809 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Searching default locations for git executable
2022-09-13 19:26:13,812 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/bin
2022-09-13 19:26:13,814 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /usr/bin/git
2022-09-13 19:26:13,819 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.24.1 at /usr/bin/git
2022-09-13 19:26:13,820 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /bin
2022-09-13 19:26:13,820 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /bin/git
2022-09-13 19:26:13,828 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.24.1 at /bin/git
2022-09-13 19:26:13,829 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/sbin
2022-09-13 19:26:13,829 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /sbin
2022-09-13 19:26:13,829 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/bin
2022-09-13 19:26:13,830 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /opt/local/bin
2022-09-13 19:26:13,830 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /usr/local/git/bin
2022-09-13 19:26:13,830 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Looking for Git executable in /opt/bin
2022-09-13 19:26:13,831 TRACE [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Checking version for /opt/bin/git
2022-09-13 19:26:13,834 DEBUG [spring-startup] c.a.s.i.s.g.b.DefaultGitBinaryHelper Found git version 2.34.1 at /opt/bin/git
2022-09-13 19:26:39,001 INFO [spring-startup] c.a.s.internal.scm.PluginScmService Bitbucket is using /opt/bin/git version 2.34.1Was this helpful?