# 引用

引用（ref）是指向 commit 的具名指针。分支、tag、HEAD 和远程跟踪引用都属于 ref。Pitmaster 从松散文件、packed-refs 和 reftable 中读取 ref，并将其写入松散文件和 packed-refs。

## RefDatabase

`RefDatabase` 是组合层，会先搜索松散 ref，然后搜索 reftable（如果仓库中存在），最后搜索 packed-refs。

```php
use Pitmaster\Ref\RefDatabase;

$refs = new RefDatabase($gitDir, $commonDir);

// Resolve a ref to an ObjectId
$id = $refs->resolve('refs/heads/main');

// Resolve HEAD (follows symbolic refs)
$headId = $refs->resolveHead();

// Read HEAD as a symbolic ref (null when HEAD is detached)
$symref = $refs->readHead();
echo $symref?->target;  // 'refs/heads/main'

// List all refs
foreach ($refs->list() as $name => $id) {
    echo "{$id->hex} {$name}\n";
}

// Update a ref
$refs->update('refs/heads/main', $newCommitId);

// Delete a ref
$refs->delete('refs/heads/old-branch');
```

对于链接的工作树，`RefDatabase` 会将 HEAD 及其他每个工作树专属的伪 ref（`ORIG_HEAD`、`MERGE_HEAD`、`CHERRY_PICK_HEAD`、`REVERT_HEAD`、`REBASE_HEAD`、`BISECT_HEAD`）保存在每个工作树专属的 git 目录中。分支、tag 和其他 `refs/` 条目会写入公共目录，而 `packed-refs` 始终从公共目录读取。

## 松散引用

松散 ref 是 `.git/refs/` 中的独立文件。每个文件都包含目标对象的十六进制哈希（40 个字符，SHA-256 时为 64 个字符），后接换行符。

```
.git/refs/heads/main           -> abc123def456...\n
.git/refs/tags/v1.0.0          -> 789012abc345...\n
.git/refs/remotes/origin/main  -> abc123def456...\n
```

```php
use Pitmaster\Ref\LooseRefStore;

$store = new LooseRefStore($gitDir, $commonDir); // $commonDir defaults to $gitDir

$id = $store->resolve('refs/heads/main');
$store->update('refs/heads/main', $commitId);
$store->delete('refs/heads/old');
```

### HEAD

HEAD 是一种特殊 ref，可以是以下任一类型：

**符号引用**：指向另一个 ref（最常见的情况是位于某个分支上）：
```
ref: refs/heads/main\n
```

**分离引用**：直接指向 commit 哈希：
```
abc123def456789012abc345def678901234abcd\n
```

```php
use Pitmaster\Ref\SymbolicRef;

$symref = SymbolicRef::parse('HEAD', $headContent);

if ($symref !== null) {
    echo "On branch: {$symref->target}\n";
    // 'refs/heads/main'
} else {
    echo "Detached HEAD\n";
}
```

## 打包引用

`packed-refs` 文件将许多 ref 合并到一个文件中，以提高效率。Git 会在 `git pack-refs` 或 `git gc` 期间创建它。

```
# pack-refs with: peeled fully-peeled sorted
abc123def456789012abc345def678901234abcd refs/heads/main
789012abc345def678901234abcdabc123def456 refs/tags/v1.0.0
^def456789012abc345def678901234abcdabc12
```

以 `^` 开头的行是剥离值：带注释的 tag 最终指向的 commit。

```php
use Pitmaster\Ref\PackedRefStore;

$store = new PackedRefStore($commonDir);

$id = $store->resolve('refs/heads/main');

foreach ($store->list() as $name => $id) {
    echo "{$id->hex} {$name}\n";
}
```

### 剥离值

对于带注释的 tag，packed-refs 文件可能会在 tag ref 后面的行中包含剥离（取消引用）后的值。剥离值是 tag 对象最终指向的 commit（中间可能经过多个 tag 对象）。

```php
$peeled = $store->peeled('refs/tags/v1.0.0');
// Returns the commit ObjectId, or null if not peeled
```

## 引用解析顺序

解析 ref 时，Pitmaster 会按以下顺序检查：

1. 松散 ref（`.git/refs/` 中的文件）
2. Reftable（若 `.git/reftable/tables.list` 存在）
3. 打包 ref（`.git/packed-refs` 中的条目）

松散 ref 优先级最高。更新打包 ref 时，新值会写入为松散 ref（不会重写 packed-refs 文件）。删除 ref 会同时移除松散文件和打包条目。`$repo->packRefs()` 会根据当前 ref 重写 `packed-refs`，并移除松散文件。

## SymbolicRef

符号引用是指向其他引用、而非直接指向对象的引用。

```php
use Pitmaster\Ref\SymbolicRef;

// Parse
$ref = SymbolicRef::parse('HEAD', "ref: refs/heads/main\n");
echo $ref->name;    // 'HEAD'
echo $ref->target;  // 'refs/heads/main'

// Update
$refs->updateSymbolic('HEAD', 'refs/heads/feature');
```

## Reflog

reflog 会记录 ref 变更时间，从而让 `git reflog` 能够显示 HEAD 和分支顶端的历史记录。

Reflog 文件位于 `.git/logs/` 中：
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

每行记录：
```
<old-hash> <new-hash> <author> <timestamp> <tz>\t<message>
```

```php
use Pitmaster\Ref\Reflog;

$reflog = Reflog::open($gitDir, 'HEAD');

// Read entries
$entries = $reflog->entries();
foreach ($entries as $entry) {
    echo "{$entry['old']} -> {$entry['new']}: {$entry['message']}\n";
}

// Append an entry
$reflog->append(
    $oldId,
    $newId,
    'Name <email> 1700000000 +0000',
    'commit: Add feature',
);
```

stash 使用 `refs/stash` 的 reflog 作为其堆栈存储。

## Reftable

Reftable 是一种用于存储 ref 的较新二进制格式，专为提升大量 ref（数千个分支）时的性能而设计。它取代了松散 ref 和 packed-refs。

Reftable 文件存储在 `.git/reftable/` 中，包含：
- ref 记录（按名称排序）
- 日志记录（reflog 条目）
- 用于快速查找的块级索引

Pitmaster 在存在 reftable 文件时会读取其中的 ref 记录，但不会读取日志记录。存在 reftable 时，它会取代 `packed-refs` 用于列表显示。ref 更新始终写入为松散文件，而 git 在 reftable 仓库中不会读取这些文件，因此应将 reftable 仓库视为只读。

## Ref 命名约定

| 模式 | 含义 |
|---------|---------|
| `refs/heads/<name>` | 本地分支 |
| `refs/tags/<name>` | Tag（轻量或带注释）|
| `refs/remotes/<remote>/<name>` | 远程跟踪分支 |
| `refs/stash` | Stash 堆栈 |
| `refs/notes/<namespace>` | Git 备注 |
| `HEAD` | 当前检出项（符号引用或分离引用）|
| `FETCH_HEAD` | 上次 fetch 结果（由 git 写入；Pitmaster 的 `fetch()` 不会写入）|
| `MERGE_HEAD` | 正在合并的分支（合并期间）|
| `ORIG_HEAD` | 上一个 HEAD（危险操作前）|

## 通过 Repository 使用 ref

```php
// Read
$branch = $repo->branch();          // Current branch name
$branches = $repo->branches();      // All branch names
$tags = $repo->tags();              // All tag names
$refs = $repo->allRefs();           // All refs as name => hash

// Write
$repo->createBranch('feature');     // Create refs/heads/feature
$repo->deleteBranch('feature');     // Delete refs/heads/feature
$repo->createTag('v1.0', 'Release');// Create annotated tag
$repo->createLightweightTag('v1.0-lite'); // Create lightweight tag
$repo->updateRef('refs/heads/main', $id); // Direct ref update

// Resolve
$id = $repo->resolve('HEAD');
$id = $repo->resolve('main');
$id = $repo->resolve('v1.0.0');
$id = $repo->resolve('HEAD~3');
```