Rugged 库使用技术文档

1. 安装指南

Rugged 是一个 Ruby 库，用于访问 libgit2 的功能。安装 Rugged 非常简单，只需运行以下命令：

gem install rugged

在安装前，确保系统中已安装了 CMake 和 pkg-config，因为它们是构建包含的 libgit2 版本所必需的。

根据操作系统安装依赖

Debian 及 Ubuntu 系统

对于基于 Debian 的 Linux 发行版，可以使用 apt 来安装所需的包：

sudo apt install libgit2-dev cmake pkg-config

请注意，如果您想使用系统提供的 libgit2 而不是内置版本，则需要安装 libgit2-dev。此时，libgit2 和 Rugged 的主版本和次版本号必须匹配。

Mac 系统

在 OS X 上，安装 Homebrew 后，可以通过以下命令安装所需的包：

brew install cmake pkg-config

如果安装宝石时出现 ERROR: CMake is required to build Rugged. 错误，请按照以上步骤操作。

可选安装

如果希望 Rugged 支持 HTTPS 和 SSH，则需要检查 libgit2 的可选依赖。

要安装带 SSH 支持的 Rugged，请确保系统中有 LibSSH2 库，然后传递所需的 CMAKE_FLAGS：

CMAKE_FLAGS='-DUSE_SSH=ON' gem install rugged

或者使用以下构建选项：

gem install rugged -- --with-ssh

如果使用 bundler 并希望将 libgit2 与 Rugged 一起打包，可以使用 :submodules 选项：

gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true

如果想使用 SSH 支持将 Rugged 打包到 bundler 中，可以在 bundler 配置中添加 --with-ssh 构建选项：

bundle config build.rugged --with-ssh
bundle install

2. 项目使用说明

Rugged 库提供了对 Git 仓库的访问，包括读取和写入对象、遍历树结构、访问暂存区等。以下是使用 Rugged 的基础。

初始化仓库

要使用 Rugged，首先需要初始化一个仓库：

repo = Rugged::Repository.new('path/to/my/repository')

也可以创建新的仓库：

Rugged::Repository.init_at('.', :bare)

如果提供一个子目录路径，Rugged 也可以找到 .git 目录：

Rugged::Repository.discover("/Users/me/projects/repo/lib/subdir/")

访问仓库

# 检查 SHA1 是否存在于当前仓库
repo.exists?('07b44cbda23b726e5d54e2ef383495922c024202')

# 仓库状态值
repo.bare?       # 是否为裸仓库
repo.empty?      # 仓库是否为空
repo.head_unborn? # HEAD 是否未出生（未初始化）
repo.head_detached? # HEAD 是否分离

# 获取仓库信息
repo.path        # 仓库路径
repo.workdir     # 工作目录路径
repo.head        # 仓库的 HEAD 引用

写入仓库

写入仓库有多种方式，可以直接从仓库对象写入：

sha = repo.write(content, type)

或者使用 Commit 对象直接构造一个提交：

oid = repo.write("This is a blob.", :blob)
index = repo.index
index.read_tree(repo.head.target.tree)
index.add(:path => "README.md", :oid => oid, :mode => 0100644)

options = {
  tree: index.write_tree(repo),
  author: { email: "[e-mail]", name: 'Test Author', time: Time.now },
  committer: { email: "[e-mail]", name: 'Test Author', time: Time.now },
  message: "Making a commit via Rugged!",
  parents: repo.empty? ? [] : [ repo.head.target ].compact,
  update_ref: 'HEAD'
}

Rugged::Commit.create(repo, options)

3. 项目API使用文档

Rugged API 包括对 Git 仓库中不同类型的对象的访问和操作。以下是一些主要对象类型的使用方法。

Commit 对象

commit = repo.lookup('a0ae5566e3c8a3bddffab21022056f0b5e03ef07')

# 获取 commit 属性
commit.message
commit.time
commit.author
commit.tree
commit.parents

创建新提交：

author = {:email=>"[e-mail]", :time=>Time.now, :name=>"Vicent Mart\303\255"}

Rugged::Commit.create(r,
  :author => author,
  :message => "Hello world\n\n",
  :committer => author,
  :parents => ["2cb831a8aea28b2c1b9c63385585b864e4d3bad1"],
  :tree => some_tree,
  :update_ref => "HEAD")

Tag 对象

tag = repo.lookup(tag_sha)

# 获取 tag 属性
tag.target
tag.target.oid
tag.target_type # :commit, :tag, :blob
tag.name
tag.message
tag.tagger

Tree 对象

tree = repo.lookup('779fbb1e17e666832773a9825875300ea736c2da')

# 获取 tree 属性
tree.count
tree[0]
tree.first
tree.get_entry(0)

使用 TreeBuilder 创建树：

oid = repo.write("This is a blob.", :blob)
builder = Rugged::Tree::Builder.new(repo)
builder << { :type => :blob, :name => "README.md", :oid => oid, :filemode => 0100644 }

options = {
  tree: builder.write,
  author: { email: "[e-mail]", name: 'Test Author', time: Time.now },
  committer: { email: "[e-mail]", name: 'Test Author', time: Time.now },
  message: "Making a commit via Rugged!",
  parents: repo.empty? ? [] : [ repo.head.target ].compact,
  update_ref: 'HEAD'
}

Rugged::Commit.create(repo, options)

Blob 对象

Blob 对象代表 Tree 对象中的文件数据：

blob = repo.lookup('e1253910439ea902cf49be8a9f02f3c08d89ac73')
blob.content # 获取 blob 内容

4. 项目安装方式

关于 Rugged 的安装方式，请参考上文“安装指南”部分的详细步骤。简要概括如下：

使用 gem 命令安装 Rugged：

gem install rugged

确保安装必要的依赖，根据操作系统使用相应的命令安装 libgit2-dev、cmake 和 pkg-config。

如果需要支持 SSH，可以设置相应的 CMAKE_FLAGS 或使用 --with-ssh 选项。

通过 bundler 安装时，可以配置 build.rugged 选项。