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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
use ;
use LazyLock;
/// Return the unoverridden location at which an installation-specific Git configuration file can be found, or
/// `None` if the binary could not be executed or its results could not be parsed.
///
/// The Git query ignores `GIT_CONFIG_SYSTEM` and `GIT_CONFIG_NOSYSTEM`; callers must apply these
/// variables according to their own environment-access policy.
///
/// ### Performance
///
/// This can invoke the Git binary. An unambiguous Git for Windows
/// installation identified by `EXEPATH`, or by `git.exe` in its `cmd` or `bin` directories,
/// avoids that invocation when its modern configuration file exists.
/// Prefixes derived from the selected executable are shared with core-directory, prefix, and shell discovery.
/// Registered MSYS2 Git packages use their known configuration path, translated by `cygpath`.
/// Their core and configuration paths share a single cached conversion.
/// On Unix, the first executable in `PATH` is resolved through symlinks. Known Homebrew Cellar
/// layouts, Linux `/usr/bin/git` and `/bin/git`, and direct Apple developer binaries avoid the query
/// when their expected configuration file exists. Without `/etc/gitconfig`, Linux `/usr/bin/git` and
/// `/bin/git` have no installation configuration, which also needs no query. Apple's `/usr/bin/git` shim still queries Git,
/// leaving developer-directory and toolchain selection to the shim.
/// Unknown layouts, relative `PATH` entries, and restricted execute bits also query Git.
/// Indirect Apple Git invocations also query Git, as their config can differ from the symlink target's.
/// These shortcuts assume the recognized installations use their standard build-time config paths.
/// Return whether [`installation_config()`] was reported with system scope by Git.
///
/// `GIT_CONFIG_SYSTEM` replaces system-scoped installation configuration, but not installation
/// configuration reported with another scope, such as Apple Git's `unknown` scope.
/// Returns `false` if no installation path was found or Git was too old to report scopes.
/// Return the location at which git installation specific configuration files are located, or `None` if the binary
/// could not be executed or its results could not be parsed.
///
/// ### Performance
///
/// This shares the discovery and caching of [`installation_config()`].
/// Return the unoverridden location of the system-wide Git configuration file.
///
/// On Windows this shares the single Git invocation used by [`installation_config()`].
/// The caller is responsible for applying `GIT_CONFIG_SYSTEM` and `GIT_CONFIG_NOSYSTEM`.
/// Return the shell that Git would use, the shell to execute commands from.
///
/// On Windows, this is the full path to `sh.exe` bundled with Git for Windows if we can find it.
/// If the bundled shell on Windows cannot be found, `sh.exe` is returned as the name of a shell,
/// as it could possibly be found in `PATH`. On Unix it's `/bin/sh` as the POSIX-compatible shell.
///
/// Use [`shell_command()`] when constructing a command. On Windows, it passes `--posix` to the
/// Git for Windows `bin/sh.exe` shim so its delegated `bash.exe` behaves like `sh`.
///
/// Note that the returned path might not be a path on disk, if it is a fallback path or if the
/// file was moved or deleted since the first time this function is called.
/// Return a command configured to run the shell that Git would use.
///
/// On Windows, when [`shell()`] selected the Git for Windows `sh.exe` shim, this also requests
/// POSIX mode explicitly. The shim delegates to `bash.exe`, which otherwise behaves as Bash
/// rather than as `sh`. Other shells, including a caller-provided shell, must not receive this
/// Bash-specific option.
/// Return the name of the Git executable to invoke it.
///
/// If it's in the `PATH`, it will always be a short name.
///
/// Note that on Windows, we will find the executable in the `PATH` if it exists there, or search it
/// in alternative locations which when found yields the full path to it.
/// Fallbacks prioritize cheap probes, then expected installer prevalence. Fixed paths come first:
/// standard Git for Windows locations, `GIT_INSTALL_ROOT/cmd`, WinGet's user and machine `Links`
/// directories, `ChocolateyToolsLocation/git/cmd`, Scoop's user and global `current` installations,
/// the active Conda/Mamba environment's `CONDA_PREFIX/Library/bin`, and MSYS2's
/// `GIT_INSTALL_ROOT/usr/bin`. Next come direct Git for Windows registry registrations, including
/// custom roots. Directory scans for Scoop installations without junctions follow, with the broader
/// MSYS2 uninstall-registry scan last. An executable selected by `PATH` always takes precedence.
///
/// Scoop uses `SCOOP`/`SCOOP_GLOBAL`, defaulting to `USERPROFILE/scoop` and `ProgramData/scoop`.
/// When Scoop's `current` junction is absent, its most recently installed version is used.
/// Installation roots must be absolute paths. Registry discovery prefers current-user
/// registrations to machine registrations.
/// Fallback sources are inspected only when earlier locations do not contain Git, and the
/// selected executable is cached for the lifetime of the process.
/// File symlinks, including WinGet's portable links, are resolved for layout discovery while
/// retaining the selected invocation.
/// Plain Scoop shims are resolved through their `.shim` sidecars; shims with arguments or
/// unsupported metadata still require querying Git.
/// Returns the fully qualified path in the *xdg-home* directory (or equivalent in the home dir) to
/// `file`, accessing `env_var(<name>)` to learn where these bases are.
///
/// Note that the `HOME` directory should ultimately come from [`home_dir()`] as it handles Windows
/// correctly. The same can be achieved by using [`var()`] as `env_var`.
static GIT_CORE_DIR: = new;
/// Return the directory that `git --exec-path` would report.
///
/// Known Git for Windows layouts avoid starting Git when their core directory exists and
/// `GIT_EXEC_PATH` is unset. Other installations and overrides are queried from Git.
/// Registered MSYS2 Git packages also avoid the Git query, translating their known core path
/// through the same installation's `cygpath` to respect custom mounts.
/// This conversion is shared with configuration discovery.
/// Returns `None` if Git could not be found, returned an error, or its path could not be translated.
/// Return the path at which the Git-provided program with bare `name` resides within the [`core_dir()`],
/// or `None` if it doesn't exist there or if Git could not be found.
///
/// This is the location `git` itself uses to find the programs implementing its subcommands, and is
/// useful to invoke programs like `git-upload-pack` that are shipped with Git but aren't necessarily
/// present in `PATH`.
///
/// Use [`installation_program()`] to also search Git for Windows' wider installation for bundled
/// programs such as `sh` and `vim`.
///
/// Note that installations differ in which programs they provide as separate executables - builds
/// with `SKIP_DASHED_BUILT_INS`, like Git for Windows, omit programs for builtin subcommands, which
/// can then still be run through `git` itself.
/// Return the path at which a program distributed with Git resides, or `None` if it cannot be found.
///
/// Unlike [`core_dir_program()`], which searches only [`core_dir()`], this also searches the `bin`
/// and `usr/bin` directories of the Git for Windows installation on Windows. These contain programs
/// such as `sh`, `vim`, and, in some versions, `vi`.
///
/// Only a bare program `name` without path separators is accepted.
/// Returns the platform dependent system prefix or `None` if it cannot be found (right now only on Windows).
///
/// On Windows this is Git's runtime prefix, such as `C:/Program Files/Git/ucrt64` or
/// `C:/Program Files/Git/mingw64`. Git for Windows keeps its system configuration and attributes
/// in the sibling `etc` directory. On other platforms this returns `/`.
///
/// ### Performance
///
/// On Windows, the slowest part is the launch of the Git executable in the PATH. This is often
/// avoided by inspecting the environment, when launched from inside a Git Bash MSYS2 shell,
/// or by finding Git for Windows' `cmd` or `bin` directories in the PATH, including the
/// launchers installed by Chocolatey portable and Conda/Mamba.
///
/// ### When `None` is returned
///
/// This happens only Windows if the git binary can't be found at all for obtaining its executable
/// path, or if the git binary wasn't built with a well-known directory structure or environment.
/// Returns `$HOME` or `None` if it cannot be found.
/// Tries to obtain the home directory from `HOME` on all platforms, but falls back to
/// [`std::env::home_dir()`] for more complex ways of obtaining a home directory, particularly useful
/// on Windows.
///
/// The reason `HOME` is tried first is to allow Windows users to have a custom location for their
/// linux-style home, as otherwise they would have to accumulate dot files in a directory these are
/// inconvenient and perceived as clutter.
/// Returns the contents of an environment variable of `name` with some special handling for
/// certain environment variables (like `HOME`) for platform compatibility.