Documentation
¶
Index ¶
- Variables
- func ClearStash() error
- func CreateTree() (string, error)
- func DropStash(index int) error
- func FindCommit(hash string) (models.Commit, error)
- func FindMergeBases(h1, h2 string) ([]string, error)
- func GetLastCommit() (models.Commit, error)
- func GetRef(name string) (string, error)
- func HashAndStageBlob(path string) (string, error)
- func ListStashes() ([]string, error)
- func LoadIndex() (map[string]plumbing.IndexEntry, error)
- func LockFile(f *os.File) error
- func ParseTree(hash string) (map[string]TreeEntry, error)
- func PeekStash() (string, error)
- func PopStash() (string, error)
- func PushStash(commitID string) error
- func ReadCommits() ([]models.Commit, error)
- func ReadObject(hash string) ([]byte, error)
- func SafeWriteFile(filename string, data []byte, perm os.FileMode) (err error)
- func UpdateIndex(fn func(index map[string]plumbing.IndexEntry) error) error
- func WriteIndex(simpleMap map[string]string) error
- func WriteIndexFromTree(tree map[string]TreeEntry) error
- type TreeEntry
Constants ¶
This section is empty.
Variables ¶
var ErrNoCommits = errors.New("no commits found")
ErrNoCommits indicates that the repository does not yet contain any commit history. It is returned when HEAD cannot be resolved to a valid commit reference.
var ErrNoStash = errors.New("no stash entries found")
ErrNoStash indicates that a stash operation requiring an existing entry was attempted while the stash stack is empty.
Functions ¶
func ClearStash ¶
func ClearStash() error
ClearStash removes all stash entries by truncating the stash log file.
If the stash file does not exist, the operation is treated as a no-op.
func CreateTree ¶
CreateTree constructs a tree object from the current repository index and writes it to object storage using a legacy flat text format (one "mode hash path\n" line per entry).
DEPRECATED (M4): This function is unreachable from any production code path. plumbing.WriteTree (used everywhere else) writes proper binary Git tree objects; having two incompatible tree formats in the same repo is a silent landmine. ParseTree has a compatibility shim for the flat format, but new code must never call CreateTree. This function is preserved only for historical reference and will be removed in a future cleanup. Replace any new call sites with plumbing.WriteTree instead.
func FindCommit ¶
FindCommit loads a commit object by hash from the object database and parses its contents into a models.Commit structure.
func FindMergeBases ¶
FindMergeBases returns all lowest common ancestors (Git-style merge bases)
func GetLastCommit ¶
GetLastCommit resolves the repository HEAD reference to the most recent commit object.
HEAD may contain either:
- A direct commit hash
- A symbolic reference such as "ref: refs/heads/main"
Symbolic references are resolved by reading the referenced file inside the repository directory.
func GetRef ¶
GetRef reads the content of a reference file located within the repository directory and returns the trimmed reference value.
References typically contain commit hashes or symbolic references such as "ref: refs/heads/main".
func HashAndStageBlob ¶
HashAndStageBlob reads the file at path (or the symlink target if path is a symlink), writes its content as a "blob" object into the object store, and returns the 40-character hex SHA-1 of that object. It both hashes AND persists — callers that only want the hash without writing should not use this function.
func ListStashes ¶
ListStashes reads the stash log file and returns all stored commit IDs in last-in-first-out (LIFO) order.
Internally the file stores entries oldest-to-newest. The returned slice is reversed so callers always see the most recent stash first.
func LoadIndex ¶
func LoadIndex() (map[string]plumbing.IndexEntry, error)
LoadIndex reads the repository index file from disk and converts the underlying slice of plumbing.IndexEntry values into a path-keyed map.
The returned map is optimized for mutation by higher-level storage operations that need efficient lookup or modification of entries by path. If the index file does not yet exist, an empty map is returned.
func LockFile ¶
LockFile applies an exclusive advisory lock to the provided file descriptor using syscall.Flock.
The lock is process-scoped and blocks until the lock becomes available. Callers must keep the file descriptor open while the lock is held.
func ParseTree ¶
ParseTree reads a tree object from the object database and reconstructs a flattened map of file entries keyed by full path.
The function supports two formats:
- Legacy flat text format used by earlier versions of the repository implementation.
- Standard Git binary tree object format.
Directory entries are recursively expanded so the resulting map contains only file paths mapped to their corresponding TreeEntry metadata.
func PeekStash ¶
PeekStash returns the most recent stash entry without removing it from the stash stack.
func PopStash ¶
PopStash removes and returns the most recent stash entry.
The stash stack is logically LIFO. Internally the newest entry appears at the end of the file, but ListStashes returns entries reversed so index 0 always represents the most recent stash.
func PushStash ¶
PushStash appends a commit ID to the stash stack.
The stash is stored as a newline-delimited file where the newest entry is appended to the end. Logical LIFO ordering is reconstructed during reads by reversing the file order.
func ReadCommits ¶
ReadCommits walks commit history starting from the current HEAD and returns a linear slice of commits following parent pointers.
Traversal stops when:
- A commit has no parent (root commit)
- A referenced parent cannot be resolved
- A previously seen commit ID appears (cycle protection)
Cycle detection protects against corrupted commit graphs that could otherwise produce infinite loops.
func ReadObject ¶
ReadObject locates, decompresses, and returns the raw payload of an object stored in the repository object database.
Objects are stored in a Git-style format under repo.ObjectsDir using a fan-out directory structure where the first two hex characters of the hash form the directory and the remainder form the filename.
The stored object format is:
"<type> <size>\0<payload>"
This function removes the header and returns only the payload.
func SafeWriteFile ¶
SafeWriteFile writes data to a file atomically and with durability guarantees.
The function ensures that readers of the target filename will never observe partially written data. This is achieved by writing the contents to a temporary file in the same directory and then atomically renaming it over the destination.
Implementation guarantees:
- Writes occur to a uniquely named temporary file to avoid writer collisions.
- File contents are flushed to disk before rename to protect against power loss.
- The rename operation replaces the target atomically on supported filesystems.
- The parent directory is synced after rename to persist metadata changes.
Platform behavior:
- Relies on POSIX atomic rename semantics on Unix-like systems.
- On Windows, the rename relies on the equivalent filesystem replace behavior.
func UpdateIndex ¶
func UpdateIndex(fn func(index map[string]plumbing.IndexEntry) error) error
UpdateIndex acquires an exclusive index lock, exposes the in-memory index map to the provided mutation callback, and then persists the resulting state back to disk.
The callback receives the mutable map representation of the index. If the callback returns an error, the update is aborted and the index file is left unchanged.
func WriteIndex ¶
WriteIndex is a compatibility helper that converts a simplified path-to-hash map into the richer TreeEntry representation used by tree reconstruction logic.
This function exists primarily to support older tests and legacy call sites that operate on simple string mappings.
func WriteIndexFromTree ¶
WriteIndexFromTree rebuilds the index file from a flattened tree snapshot representation.
Each TreeEntry is converted into a plumbing.IndexEntry, reconstructing the necessary fields such as the raw hash bytes and file mode. The resulting index is then written to disk in canonical order.
Source Files