GitLite/docs/api-contract.md

# API Contract

The frontend calls Tauri commands with `@tauri-apps/api/core.invoke`.

## Shared payloads

```ts
type FileStatusKind = "modified" | "added" | "deleted" | "renamed" | "untracked" | "conflicted" | "unknown";

interface GitStatus {
  repo_path: string;
  current_branch: string | null;
  upstream: string | null;
  ahead: number;
  behind: number;
  files: GitFileStatus[];
  clean: boolean;
  rebase_in_progress: boolean;
  cherry_pick_in_progress: boolean;
  merge_in_progress: boolean;
}

interface GitFileStatus {
  path: string;
  old_path: string | null;
  staged: FileStatusKind | null;
  unstaged: FileStatusKind | null;
}

interface GitBranch {
  name: string;
  current: boolean;
  remote: boolean;
}

interface GitWorktree {
  path: string;
  head: string | null;
  short_head: string | null;
  branch: string | null;
  bare: boolean;
  detached: boolean;
  locked: boolean;
  lock_reason: string | null;
  prunable: boolean;
  prune_reason: string | null;
  missing: boolean;
  is_main: boolean;
  is_current: boolean;
  clean: boolean;
  changed_files: number;
}

interface GitCommit {
  hash: string;
  short_hash: string;
  summary: string;
  author_name: string;
  author_email: string;
  date: string;
  refs: string[];
  files: GitCommitFile[];
}

interface GitCommitFile {
  path: string;
  old_path: string | null;
  status: FileStatusKind;
}

interface GitRepositoryFile {
  path: string;
  tracked: boolean;
  status: FileStatusKind | null;
}

interface GitLfsStatus {
  available: boolean;
  bundled: boolean;
  version: string | null;
  filters_configured: boolean;
  hook_installed: boolean;
  repository_uses_lfs: boolean;
  patterns: GitLfsPattern[];
  files: GitLfsFile[];
}

interface GitLfsPattern {
  pattern: string;
  source: string;
  lockable: boolean;
  tracked: boolean;
}

interface GitLfsFile {
  name: string;
  size: number;
  checkout: boolean;
  downloaded: boolean;
  oid_type: string;
  oid: string;
  version: string;
}
```

## Commands

The command list below includes the repository-management and synchronization API. The TypeScript wrappers in `src/lib/git.ts` are the authoritative full list.

- `open_repository(path: string): Promise<GitStatus>`
- `init_repository(path: string, initialBranch?: string): Promise<GitStatus>`
- `clone_repository(...): Promise<RepositoryBundle>`
- `get_status(path: string): Promise<GitStatus>`
- `git_lfs_status(path: string): Promise<GitLfsStatus>`
- `git_lfs_install(path: string): Promise<GitLfsStatus>`
- `git_lfs_track(path: string, pattern: string, lockable?: boolean): Promise<GitLfsStatus>`
- `git_lfs_untrack(path: string, pattern: string): Promise<GitLfsStatus>`
- `git_lfs_pull(path: string, remote?: string, username?: string, password?: string): Promise<GitLfsStatus>`
- `git_lfs_prune(path: string): Promise<GitLfsStatus>`
- `pull(...)` automatically runs `git lfs pull` after a successful Git pull when
  the repository contains LFS attributes or tracked LFS objects.
- `list_branches(path: string): Promise<GitBranch[]>`
- `list_remotes(path: string): Promise<GitRemote[]>`
- `add_remote(path: string, name: string, url: string): Promise<GitRemote[]>`
- `update_remote(path: string, name: string, url: string): Promise<GitRemote[]>`
- `remove_remote(path: string, name: string): Promise<GitRemote[]>`
- `set_branch_upstream(path: string, branch: string, upstream?: string): Promise<GitStatus>`
- `delete_remote_branch(path: string, remote: string, branch: string): Promise<GitStatus>`
- `checkout_branch(path: string, branch: string): Promise<GitStatus>`
- `list_worktrees(path: string): Promise<GitWorktree[]>`
- `add_worktree(path: string, worktreePath: string, ...): Promise<GitWorktree[]>`
- `remove_worktree(path: string, worktreePath: string, force?: boolean): Promise<GitWorktree[]>`
- `move_worktree(path: string, worktreePath: string, destination: string): Promise<GitWorktree[]>`
- `lock_worktree(path: string, worktreePath: string, reason?: string): Promise<GitWorktree[]>`
- `unlock_worktree(path: string, worktreePath: string): Promise<GitWorktree[]>`
- `prune_worktrees(path: string): Promise<GitWorktree[]>`
- `repair_worktree(path: string, worktreePath: string): Promise<GitWorktree[]>`
- `stage_files(path: string, files: string[]): Promise<GitStatus>`
- `unstage_files(path: string, files: string[]): Promise<GitStatus>`
- `add_to_gitignore(path: string, target: string, kind: "file" | "extension" | "folder"): Promise<GitStatus>`; appends a repository-root `.gitignore` rule and unstages newly-added matching files.
- `untrack_paths(path: string, targets: string[]): Promise<GitStatus>`; removes files or folders from the Git index while preserving their working-tree contents.
- `restore_files(path: string, files: string[], staged: boolean): Promise<GitStatus>`
- `stash_push(path: string, message?: string, includeUntracked?: boolean, paths?: string[]): Promise<GitStatus>`; when `paths` is provided, only matching files are stashed.
- `commit(path: string, message: string): Promise<GitStatus>`
- `fetch(path: string, prune?: boolean, remote?: string): Promise<GitStatus>`
- `pull(path: string, strategy?: "merge" | "rebase" | "ff-only", remote?: string, branch?: string): Promise<GitStatus>`
- `push(path: string, forceWithLease?: boolean, remote?: string): Promise<GitStatus>`
- `list_commits(path: string, limit?: number, skip?: number): Promise<GitCommit[]>`
- `restore_to_commit(path: string, commit: string): Promise<GitStatus>`
- `restore_file_from_commit(path: string, commit: string, file: string): Promise<GitStatus>` (the `file` argument can also be a folder path)
- `merge_branch(path: string, branch: string, strategy?: "default" | "squash" | "ff-only" | "no-ff"): Promise<GitStatus>`
- `merge_continue(path: string): Promise<GitStatus>`
- `merge_abort(path: string): Promise<GitStatus>`
- `revert_commit(path: string, commit: string): Promise<GitStatus>`
- `list_repository_files(path: string): Promise<GitRepositoryFile[]>`
- `list_file_history(path: string, file: string, limit?: number): Promise<GitCommit[]>` (the `file` argument can also be a folder path)