API Reference
Core API
Repository Operations
initRepo()
Initializes a new dGit repository in the current directory.
async function initRepo(): Promise<void>;
Example:
import { initRepo } from "dgit/core";
await initRepo();
// Creates .dgit directory with initial structure
addFiles(files: string[])
Stages files for commit.
async function addFiles(files: string[]): Promise<void>;
Parameters:
files: Array of file paths to stage
Example:
import { addFiles } from "dgit/core";
// Add single file
await addFiles(["file.txt"]);
// Add multiple files
await addFiles(["file1.txt", "file2.txt"]);
// Add with glob pattern
await addFiles(["src/*.js"]);
createCommit(options)
Creates a new commit with staged changes.
interface CommitOptions {
message: string;
}
async function createCommit(options: CommitOptions): Promise<string>;
Parameters:
options.message: Commit message
Returns:
- Commit hash
Example:
import { createCommit } from "dgit/core";
const hash = await createCommit({
message: "Initial commit",
});
console.log(`Created commit: ${hash}`);
Storage API
Class: Storage
Constructor
constructor(repoPath?: string)
Parameters:
repoPath: Optional repository path (defaults to ‘.dgit’)
Methods
init()
Initializes the storage database.
async init(): Promise<void>
saveCommit(hash, data)
Stores a commit object.
interface CommitData {
tree: string;
parent: string | null;
author: string;
timestamp: string;
message: string;
signature: string;
}
async saveCommit(hash: string, data: CommitData): Promise<void>
getCommit(hash)
Retrieves a commit object.
async getCommit(hash: string): Promise<CommitData | null>
getCommitHistory()
Gets the ordered list of commit hashes.
async getCommitHistory(): Promise<string[]>
saveObject(hash, content)
Stores a blob or tree object.
async saveObject(hash: string, content: any): Promise<void>
getObject(hash)
Retrieves an object by hash.
async getObject(hash: string): Promise<any | null>
saveIndex(data)
Updates the staging area.
interface IndexData {
files: {
[path: string]: {
hash: string;
size: number;
timestamp: number;
type: string;
mode: string;
}
}
}
async saveIndex(data: IndexData): Promise<void>
getIndex()
Gets the current staging area state.
async getIndex(): Promise<IndexData>
Usage Examples
Basic Repository Operations
import { initRepo, addFiles, createCommit } from "dgit/core";
// Initialize repository
await initRepo();
// Stage files
await addFiles(["README.md", "src/*.js"]);
// Create commit
const hash = await createCommit({
message: "Initial commit",
});
Working with Storage Directly
import { getStorage } from "dgit/storage";
const storage = getStorage();
await storage.init();
// Save a blob
const content = "Hello, World!";
const hash = computeHash(content);
await storage.saveObject(hash, content);
// Retrieve commit history
const history = await storage.getCommitHistory();
for (const commitHash of history) {
const commit = await storage.getCommit(commitHash);
console.log(`${commitHash}: ${commit.message}`);
}
Error Handling
All API methods may throw errors that should be handled:
try {
await addFiles(["nonexistent.txt"]);
} catch (error) {
console.error("Failed to add files:", error.message);
}
Common error types:
RepositoryError: Repository-related issuesStorageError: Database or filesystem errorsValidationError: Invalid input parameters
Type Definitions
For TypeScript users, type definitions are available:
import { CommitOptions, CommitData, IndexData } from "dgit/types";
Next Steps
- See Example Workflows
- Check Troubleshooting
- Review Architecture