Lib.rs

gitoxide 是用 Rust 编写的 git 实现，旨在开发对未来有保障的应用程序，这些应用程序力求正确性和性能，同时提供愉悦且令人惊讶的开发者体验。

gitoxide 提供了用于命令行的 gix 和 ein 二进制文件，以允许实验关键功能，如 fetch 和 clone，并验证由 gix 包提供的 API 的可用性和控制。

gitoxide 力求成为生产级服务器实现，而 ein 二进制文件力求成为与 Git 仓库交互的默认方式。

开发状态

命令行工具以及每个包的状态在 包状态文档 中描述。

在应用程序中使用时，请查找 gix 包，它作为各种底层管道包（如 gix-config）提供的功能的入口点。

功能发现

gix 能否完成我所需要的操作？

上述内容可能难以回答，本段旨在帮助进行功能发现。

请查看 crate-status.md，其中包含已实现和计划中的功能相当详尽的文档。

此外，使用 gix 包文档 并带有 git2 搜索词，可以帮助找到所有目前已知 git2 等效方法调用。请注意，此列表肯定不是详尽的，但可能有助于您从 git2 过来。

以下是一个高级功能列表以及计划中的功能

• clone
• fetch
• blame
• 推
• 重置
• 状态
• blob-diff
• 合并
• 变基
• 提交
• 工作树检出和工作树流
• 对象的读写
• 引用的读写
• 读取和写入 .git/index
• 读取和写入 git 配置
• 路径规范
• 修订规范
• .gitignore 和 .gitattributes

Crates

跟随链接的 crate 名称以获取详细信息。请注意，所有 crates 都遵循 semver 以及 稳定性指南。

生产级

• 稳定性等级 1

  • gix-lock

• 稳定性等级 2

  • gix-tempfile

稳定候选者

似乎功能完整并需要在发布为 1.0 之前使用一段时间才能发布的 crates。文档完整且至少审查过一次。

• gix-mailmap
• gix-chunk
• gix-ref
• gix-config
• gix-config-value
• gix-glob
• gix-actor
• gix-hash

初始开发

这些 crates 可能缺少一些功能，因此某些方面可能不完整，但现有功能在某种程度上是可用的。

• 可用 (具有粗糙但完整的文档，可能功能不完整)
  • gix (⬅ 入口点)
  • gix-object
  • gix-validate
  • gix-url
  • gix-packetline
  • gix-packetline-blocking
  • gix-transport
  • gix-protocol
  • gix-pack
  • gix-odb
  • gix-commitgraph
  • gix-diff
  • gix-traverse
  • gix-features
  • gix-credentials
  • gix-sec
  • gix-quote
  • gix-discover
  • gix-path
  • gix-attributes
  • gix-ignore
  • gix-pathspec
  • gix-index
  • gix-revision
  • gix-revwalk
  • gix-command
  • gix-prompt
  • gix-refspec
  • gix-fs
  • gix-utils
  • gix-hashtable
  • gix-worktree
  • gix-bitmap
  • gix-negotiate
  • gix-filter
  • gix-worktree-stream
  • gix-archive
  • gix-submodule
  • gix-status
  • gix-worktree-state
  • gitoxide-core
• 非常早期 (可能没有任何文档和许多粗糙的边缘)
  • gix-date
  • gix-dir
• idea (仅作为名称占位符)
  • gix-note
  • gix-fetchhead
  • gix-lfs
  • gix-rebase
  • gix-sequencer
  • gix-tui
  • gix-tix
  • gix-bundle
  • gix-fsck

压力测试

• 验证大打包文件
• 将打包文件爆炸到磁盘
• 生成和验证大提交图
• 从大量散列对象生成大打包文件

稳定性和 MSRV

我们的 稳定性指南 帮助判断在依赖此工作区中的 crates 时可以预期多少变动。

安装

下载二进制发行版

使用 cargo binstall，可以获取 二进制发行版。您可以通过 cargo install cargo-binstall 安装它，假设存在 rust 工具链。

然后使用 cargo binstall gitoxide 安装 gitoxide。

请参阅 发行版部分 以获取手动安装和各种替代构建方法，这些方法根据您的需求可以是 更瘦 或 更小，适用于 Linux、MacOS 和 Windows。

从 Arch 存储库下载

对于 Arch Linux，您可以从 community 存储库下载 gitoxide

pacman -S gitoxide

从Exherbo Linux Rust仓库下载

对于Exherbo Linux，您可以从Rust仓库下载gitoxide

cave resolve -x repository/rust
cave resolve -x gitoxide

通过源代码和Cargo

cargo是Rust包管理器，可以通过rustup轻松获取。有了它，您可以轻松构建自己的二进制文件，并针对您的特定CPU进行优化，以获得额外的性能提升。

最低支持的Rust版本在CI配置文件中有记录，最新稳定版本也能使用。

存在多种构建配置，它们都在这里有文档记录。这些文档对于需要调整外部依赖的打包者也很有用。

# A certain way to install `gitoxide` with just Rust and a C compiler installed.
# If there are problems with SSL certificates during clones, try to omit `--locked`.
cargo install gitoxide --locked --no-default-features --features max-pure

# The default installation, 'max', is the fastest, but also needs some libraries available to build successfully.
# Installing these is platform-dependent and thus can't be explained here.
cargo install gitoxide

# For smaller binaries and even faster build times that are traded for a less fancy CLI implementation, use `lean`
# or `lean-termion` respectively.
cargo install gitoxide --locked --no-default-features --features lean

以下是从git直接安装最新未发布版本的命令

cargo install --git https://github.com/Byron/gitoxide  gitoxide

如何处理构建失败

在某些平台上，由于缺少C工具链所需的工具，安装可能会失败。通常可以通过以下命令进行安装来避免这种情况：cargo install gitoxide --no-default-features --features max-pure。

以下是一个已知失败列表。

• 在Fedora上，需要安装perl才能正确构建OpenSSL。可以使用以下命令完成此操作：dnf install perl（见此问题）。

使用Docker

某些CI/CD管道利用仓库克隆。以下是一个可复制粘贴的示例，用于构建此类工作流程的Docker镜像。由于尚无官方镜像，必须首先构建镜像。

[!注意] 由于成本太高，Dockerfile不会持续测试，因此可能已经损坏。欢迎提交PR。

构建最兼容的基础镜像

docker build -f etc/docker/Dockerfile.alpine -t gitoxide:latest --compress . --target=pipeline

在管道中的基本使用

例如，如果当前的Dockerfile使用类似以下内容：RUN git clone https://github.com/Byron/gitoxide，首先构建镜像

docker build -f etc/docker/Dockerfile.alpine -t gitoxide:latest --compress .

然后将二进制文件复制到您的镜像中，并用gix替换git指令。

COPY --from gitoxide:latest /bin/gix /usr/local/bin/
COPY --from gitoxide:latest /bin/ein /usr/local/bin/

RUN /usr/local/bin/gix clone --depth 1 https://github.com/Byron/gitoxide gitoxide

使用方法

安装完成后，有两个二进制文件

• ein
  • 高级命令，porcelain，用于日常使用，优化用户体验
• gix
  • 低级命令，plumbing，用于更专业的情况，以及在现实场景中验证新编写的代码

项目目标

项目目标会随着时间的推移而变化，因为我们了解得更多，它们也可以受到挑战。

• git的纯Rust实现
  • 包括传输、对象数据库、引用、cli和tui
  • 提供简单的命令行界面，用于最常用的git操作，优化用户体验。就像一个simple-git。
  • 成为任何想解决git相关问题的首选实现，并在这个过程中成为GitPython和libgit2的替代品。
  • 成为GitHub分布式替代品的基石，甚至可能用于GitHub本身
• 从最佳实践中学到最好，写出尽可能好的idiomatic Rust
  • libgit2是一个极好的资源，可以了解哪些抽象是有效的，我们将使用它们
  • 利用Rust的类型系统来使误用成为不可能
• 成为性能最佳的实现
  • 利用Rust的类型系统来优化未执行的工作，同时保持易用性
  • 从一开始就利用并行性
  • 自第一天起支持稀疏检出
• 确保磁盘一致性
  • 确保读取操作不会干扰并发写入
  • 确保多个并发写入不会引起问题
• 走捷径，但不在质量上
  • 二进制可能使用 anyhow::Error 完全地处理，知道这些错误完全是面向用户的。
  • 库使用使用 quick-error 或 thiserror 实现的轻量级自定义错误。
  • 国际化目前不是我们关注的重点。
  • 由于打开文件句柄不足导致的IO错误不总是会引发操作失败
• 跨平台支持，包括Windows
  • 鉴于这里可用的工具和经验，没有理由不支持Windows。
  • 在CI上测试Windows，并且失败会阻止发布。

非目标

随着我们了解更多，项目非目标可能会改变，它们也可以被挑战。

• 完美复制 git 命令功能
  • git 是 git，没有理由不使用它。我们的道路是简单化，使开始使用git变得容易。
• 与git不兼容
  • 磁盘格式必须保持兼容，我们永远不会与之竞争。
• 在所有地方使用异步IO
  • 大部分情况下，git操作严重依赖于内存映射IO以及CPU来解压缩数据，这并不适合直接使用异步IO。
  • 使用 blocking 以及 gix-features::interrupt 将操作带入异步世界，并控制长时间运行的操作。
  • 在TCP连接上连接或流式传输时，尤其是在服务器上接收时，异步似乎是一个必须的，但需要通过功能标志。

贡献

如果您到目前为止所看到的内容激发了您想要贡献的兴趣，那么让我们说：我们很高兴您加入我们，并帮助您开始。

我们建议在开发过程中运行 just test，以确保在推送之前CI是绿色的。

一个工作待办事项列表可以在 项目的看板中找到，其中包含如何选择任务的说明。如果它是空的或您有其他问题，请随时 开始讨论 或私下联系 @Byron 联系。

有关更多详细信息，还可以查看 协作指南。

通过视频教程入门

• 使用 Gitoxide 学习 Rust
  • 在17集中，您可以学习所有对有意义地贡献 gitoxide 有用的内容。
• 深入了解 Gitoxide
  • 了解 gitoxide 本身，这对于任何贡献都是良好的基础，但这也不是贡献的要求。
• 赠送 Gitoxide
  • 了解PR的审查过程以及许多内心独白。

其他媒体

• Rustacean Station播客

路线图

1.0版本的功能

提供一个CLI，用于最基本用户旅程

• 初始化仓库
• fetch
  • 并更新工作树
• 克隆仓库
  • 裸
  • 带有工作树
• 在添加工作树文件后创建提交
• 添加远程
• 推
  • 创建（薄）包

示例想法

• gix tool open-remote 打开远程URL，可能在使用已知转换后从 ssh 转换到 https。
• tix 是 tig 的一个示例实现，显示提交图的一个版本，有助于练习如何制作高度响应的GUI。
• 类似于 git-sizer，但利用索引包的极快解压缩速度。
• 使用 sqlite虚拟表 打开SQL用于git。也可以看看gitqlite。MVP（最小可行产品）是什么样的？也许甚至可以与gitoxide一起分发。参见 这个Go实现作为示例。
• 一个真正令人惊叹的历史重写器，它使得理解发生了什么变得容易，同时避免了所有陷阱。想想BFG，但更棒，如果可能的话。
• gix-tui 应该从 fossil-scm 那里学到很多关于数据展示的知识。也许 这个 可以用于提示。可能 magit 也有很多可以提供的。

衍生产品想法

• 一个与 gix-lfs 紧密集成的系统，允许多级架构，以便资产可以存储在git中，并且可以从内部网络位置快速访问（例如通过网络只读访问存储），而服务器将更改立即推送到其他边缘位置，如 云 或备份。稀疏检出以及资源管理器/查找器集成使得只在工作的小部分文件上本地工作变得方便。克隆可以包含某人需要从其位置高效工作所需的所有配置，以及git历史和LFS资源的身份验证使系统安全。可以想象对云中的不受信任位置提供加密支持，尽管还需要进行更多研究以使其真正安全。
• 一个类似于 syncthing 的客户端/服务器应用程序。这是为了展示如何将底层crate组合成自定义应用程序，这些应用程序仅使用git技术的部分来达成自己的目的。注意大文件支持、多设备跨同步、使用全加密的不受信任目的地的可能性、不区分大小写的和敏感的文件系统以及扩展文件属性以及忽略文件。
• 一个基于事件的数据库，它使用提交消息来存储差异，而偶尔将实际状态聚合在树中。当然，它是分布式性质的，允许人们离线工作。
  • 它被抽象化以完全隐藏其背后的实际数据模型，从而允许在顶部实现各种事物。
  • 提交可能需要一个纳秒组件作为时间戳，这可以通过自定义头字段添加。
  • 记录所有更改允许在客户端或服务器上进行完美的合并，同时保持一个自然的审计日志，这使得它在商业中的关键数据库中非常有用。
  • 应用
    • Markdown可以用作数据库吗？这样，问题跟踪器以及元数据就可以是主要是可由人工编辑的Markdown文件？用户界面是否可以感知元数据并仅隐藏现在在GUI中可编辑的元数据块？这样做将比sqlite数据库更容易解决冲突。
    • 一个时间跟踪器 - 简单的数据，很可能自然无冲突，并且有趣地看到它以团队或公司的形式使用，也许GitHub作为认证的后盾。
      • 是否支持多个不同的跟踪器，就像不同的远程一样？

缺点与限制

请查看 SHORTCOMINGS.md 文件 以获取详细信息。

致谢

• itertools (MIT 许可证)
  • 我们在代码中使用 izip! 宏
• deflate2 (MIT 许可证)
  • 我们使用各种抽象来实现对 miniz_oxide 库的底层压缩和解压缩的直接实现

🙏 特别感谢 🙏

至少到目前为止，本节专门用于突出 Josh Triplett 在以下方面的出色支持：建议、赞助以及无数其他具有极大意义的益处。如果没有他的参与，我几乎不可能全身心投入 gitoxide，对此我感激不尽 😌。

许可证

本项目可根据您的选择使用以下任一许可证：

• Apache License 2.0，(LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

有趣的事实

• 最初，@Byron 对 这个问题 感到非常着迷，并相信通过 gitoxide 可以提供针对该问题的最快解决方案。
• @Byron 自从 13 多年前第一次接触 git 以来，就对 git 深感敬畏，并尝试以多种形式和 多次 实现 它。现在，使用 Rust，@Byron 终于找到了完成这项工作的正确工具！