WSLGit

本项目提供了一个小型可执行文件，能够将所有参数转发给运行在 Windows 上的 Bash 或 Windows 子系统 Linux (WSL) 中的 git。

开发此工具的主要目的是让 Visual Studio Code (VSCode) 中的 Git 插件能够与 WSL 中安装的 git 命令协同工作。为了实现两者的互操作，该工具会在 Windows 路径（C:\Foo\Bar）和 Linux 路径（/mnt/c/Foo/Bar）表示形式之间进行转换。

安装

最新的二进制版本可从 发布页面 下载。

[可选步骤 1] 以管理员身份运行 install.bat 脚本。
install.bat 脚本会创建一个类似于 Git For Windows 所使用的文件夹结构，并在 wslgit\cmd 和 wslgit\bin 文件夹中创建一些有用的符号链接。

[可选步骤 2] 将 wslgit\cmd 目录添加到 Windows 的 Path 环境变量中（用户或系统级别均可）。
要修改环境变量，请在开始菜单/Windows 搜索中输入“编辑账户的环境变量”，然后使用该工具编辑 Path。

您可能还需要安装最新的 Microsoft Visual C++ Redistributable for Visual Studio 2017。

WSL 发行版和文件系统

当使用 UNC 路径（\\wsl$\dist\path 或 \\wsl.localhost\dist\path）访问 WSL 发行版中的文件系统时，会从该路径中提取所使用的发行版。这意味着您打算访问的所有发行版都必须正确配置 git。

当访问 Windows 文件系统或映射的网络驱动器上的文件时，将使用默认的 WSL 发行版，除非设置了 WSLGIT_DEFAULT_DIST 环境变量。或者，您也可以设置 WSLGIT_WINDOWS_GIT 环境变量，在这些情况下完全绕过 WSL。

如果默认的 WSL 发行版是 WSL2 类型，那么强烈建议将 WSLGIT_DEFAULT_DIST 设置为某个 WSL1 实例的名称，因为 WSL1 在访问 Windows 文件系统时速度更快，并且能够访问 WSL2 无法访问的映射网络驱动器。

提示：在所有发行版中使用符号链接将文件和文件夹映射到一个公共目录，以避免维护多个副本。例如，您可以将所有 WSL 发行版中的 ~/.ssh 文件夹链接到 Windows 主文件夹中的 .ssh 文件夹。

在 VSCode 中的使用方法

如果已执行了两个可选的安装步骤，VSCode 会自动找到 git 可执行文件。

如果未执行，则需在 VSCode 的 settings.json 中设置相应路径：

{
    "git.path": "C:\\CHANGE\\TO\\PATH\\TO\\wslgit\\cmd\\wslgit.exe"
}

同时，请确保你使用无密码的 SSH 密钥访问 git 仓库，或者在启动 VSCode 之前，已将 SSH 密钥添加到 WSL 中运行的 SSH 代理。 你无法在 VSCode 中输入密码短语！

如果你使用 SSH 代理，请确保它在交互式 bash shell 启动期间不会输出任何文本（例如 Agent pid 123）。如果 bash shell 启动时有任何额外输出，VSCode 的 Git 插件将无法正确解析输出内容。

命令行使用方法

如果你已完成两个可选的安装步骤，那么只需在 Windows 控制台中运行 wslgit COMMAND 或 git COMMAND，即可使用 WSL 中安装的 Git 版本执行任何 git 命令。

在 Fork 中使用

要让 Fork 使用 WSL 中的 git，你必须已完成第一个可选安装步骤（运行 install.bat）。然后进入 Fork 的偏好设置，选择自定义 git 实例，并将其指向 wslgit\bin 文件夹中的 git.exe（不是 cmd 文件夹！）。

如果收到无法执行 Fork.RI 的错误消息，请确保 Fork.RI 脚本在 WSL 中是可执行的（如有需要，运行 chmod +x Fork.RI）。

注意事项

目前，路径转换和 shell 转义功能非常有限，仅足以使其在 VSCode 中正常工作。

所有绝对路径都会被转换，但相对路径仅在指向现有文件或目录时才会被转换。否则，将无法判断某个参数是相对路径还是其他字符串。VSCode 对相对路径始终使用正斜杠，因此在这种情况下无需转换。

此外，请注意 shell 会解释的特殊字符。目前仅处理参数中的空格和换行符。

高级用法

WSLGIT_USE_INTERACTIVE_SHELL

为了自动支持 ssh-agent 或类似工具通过交互式模式下的 .bashrc 进行设置这一常见情况，默认情况下，wslgit 会通过在 WSL 环境中启动的 bash 来执行 git。对于某些命令（clone、fetch、pull 和 push），bash 会以交互式模式启动；而对于所有其他命令，则以非交互式模式启动。

可以通过在 Windows 中设置名为 WSLGIT_USE_INTERACTIVE_SHELL 的环境变量来选择此行为，该变量可设置为以下值之一：

• false 或 0 - 强制 wslgit 始终 以非交互式模式启动 bash。
• true、1 或空值 - 强制 wslgit 始终 以交互式模式启动 bash。
• smart（默认值）- 对 clone、fetch、pull、push 命令使用交互式模式，对所有其他命令使用非交互式模式。如果未设置此变量，则默认使用此值。

此外，如果未设置 WSLGIT_USE_INTERACTIVE_SHELL，但 Windows 环境变量 BASH_ENV 已设置为某个 bash 启动脚本，且环境变量 WSLENV 包含字符串 "BASH_ENV"，则 wslgit 会假定 BASH_ENV 指定的强制启动脚本已包含所需的所有内容，因此也会以非交互式模式启动 bash。

此功能仅在 Windows 10 版本 17063 及更高版本中可用。

WSLGIT_DEFAULT_DIST

设置一个名为 WSLGIT_DEFAULT_DIST 的 Windows 环境变量，将其值设为某个 WSL 发行版的名称。当访问 Windows 文件系统上的文件或映射的网络共享时，将使用该发行版，而非默认的 WSL 发行版。

注意，若要访问映射的网络驱动器上的文件，必须使用 WSL1 发行版。

WSLGIT_WINDOWS_GIT

若要完全绕过 WSL，直接运行 Windows 版 Git 可执行文件来处理 Windows 文件系统上的仓库，请设置一个名为 WSLGIT_WINDOWS_GIT 的 Windows 环境变量，并将其值设为该可执行文件的路径（通常为 C:\Program Files\Git\bin\git.exe）。在以下几种情况下，此设置可能非常有用（甚至是必需的）：

• 在混合环境中，部分 git 仓库位于 WSL 内，而其他仓库位于 Windows 文件系统上。尤其是当你希望 WSL 和 Windows 分别使用不同的 .gitconfig 文件时。
• 作为一种优化手段，可省去转换到 WSL 环境以及在 WSL 中运行 git 所带来的开销。
• 如果你希望同时为 WSL 内和 Windows 文件系统上的仓库使用 TortoiseGit，此设置是必需的。具体操作是在 TortoiseGit 设置中将 Git.exe 路径指向 wslgit\bin。TortoiseGit 不支持对 Windows 文件系统上的仓库使用 WSL Git 可执行文件（usr\bin\git）。

WSLGIT

wslgit 会设置一个名为 WSLGIT 的变量，将其值设为 1 并共享给 WSL。此变量可在 .bashrc 中用于判断 WSL 是否由 wslgit 调用。例如，若该变量已设置，则只需执行 git 正常运行所需的最基本初始化操作。 结合 WSLGIT_USE_INTERACTIVE_SHELL=smart（默认值），可使每个 git 命令的执行开销降至最低。

此功能仅在 Windows 10 版本 17063 及更高版本中可用。

从源代码构建

首先，从 https://www.rust-lang.org 安装 Rust。Windows 版 Rust 还需要 Visual Studio 或 Visual C++ Build Tools 来进行链接操作。

然后，可通过运行以下命令构建最终的可执行文件：

cargo build --release

在本项目的根目录内。生成的二进制文件将位于 ./target/release/ 中。

由于更改环境变量时存在竞争条件，必须使用一个测试线程运行测试：

# Run all tests
cargo test -- --test-threads=1
# Run only unit tests
cargo test test -- --test-threads=1
# Run only integration tests
cargo test integration -- --test-threads=1
# Run benchmarks (requires nightly toolchain!)
cargo +nightly bench