# 参照

参照（refs）は、コミットを指す名前付きポインターです。ブランチ、タグ、HEAD、リモート追跡参照はすべてrefsです。Pitmasterはルーズファイル、packed-refs、reftableから参照を読み込み、ルーズファイルとpacked-refsに書き込みます。

## RefDatabase

`RefDatabase`は複合レイヤーで、まずルーズ参照を検索し、次に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とワークツリーごとのその他の疑似参照（`ORIG_HEAD`、`MERGE_HEAD`、`CHERRY_PICK_HEAD`、`REVERT_HEAD`、`REBASE_HEAD`、`BISECT_HEAD`）をワークツリーごとのgitディレクトリに保持します。ブランチ、タグ、その他の`refs/`エントリーは共通ディレクトリに書き込まれ、`packed-refs`は常に共通ディレクトリから読み込まれます。

## ルーズ参照

ルーズ参照は`.git/refs/`内の個別ファイルです。各ファイルには、対象オブジェクトの16進数ハッシュ（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: refs/heads/main\n
```

**detached**：コミットハッシュを直接指す：
```
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`ファイルは、多数の参照を効率よく1つのファイルにまとめます。Gitは`git pack-refs`または`git gc`の実行時にこのファイルを作成します。

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

`^`で始まる行はpeeled値です。これは、注釈付きタグが最終的に指すコミットです。

```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";
}
```

### peeled値

注釈付きタグの場合、packed-refsファイルには、タグ参照の次の行にpeeled（参照解除済み）値が含まれることがあります。peeled値は、タグオブジェクトが（複数のタグオブジェクトを経由する場合も含めて）最終的に指すコミットです。

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

## 参照の解決順序

参照を解決するとき、Pitmasterは次の順に確認します：

1. ルーズ参照（`.git/refs/`内のファイル）
2. Reftable（`.git/reftable/tables.list`が存在する場合）
3. パック参照（`.git/packed-refs`内のエントリー）

ルーズ参照が優先されます。パック参照を更新すると、新しい値はルーズ参照として書き込まれます（packed-refsファイルは書き換えられません）。参照を削除すると、ルーズファイルとパック内のエントリーの両方が削除されます。`$repo->packRefs()`は現在の参照から`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は参照の変更を記録し、`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は、多数（数千）のブランチがある場合のパフォーマンス向上を目的とした、新しいバイナリ形式の参照ストレージです。ルーズ参照とpacked-refsの両方を置き換えます。

Reftableファイルは`.git/reftable/`に保存され、次の情報を含みます：
- 参照レコード（名前順）
- ログレコード（reflogエントリー）
- 高速検索用のブロックレベルインデックス

Pitmasterはreftableファイルがある場合に参照レコードを読み込みますが、ログレコードは読み込みません。reftableが存在する場合、一覧表示では`packed-refs`に代わって使用されます。参照の更新は常にルーズファイルに書き込まれますが、reftableリポジトリではgitがこれを読み込まないため、reftableリポジトリは読み取り専用として扱ってください。

## 参照の命名規則

| パターン | 意味 |
|---------|---------|
| `refs/heads/<name>` | ローカルブランチ |
| `refs/tags/<name>` | タグ（軽量または注釈付き） |
| `refs/remotes/<remote>/<name>` | リモート追跡ブランチ |
| `refs/stash` | stashスタック |
| `refs/notes/<namespace>` | Gitノート |
| `HEAD` | 現在のチェックアウト（シンボリックまたはdetached） |
| `FETCH_HEAD` | 最後のfetch結果（gitが書き込みます。Pitmasterの`fetch()`では書き込まれません） |
| `MERGE_HEAD` | マージ対象のブランチ（マージ中） |
| `ORIG_HEAD` | 前のHEAD（危険な操作の前） |

## Repositoryを使った参照の操作

```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');
```