0
# Repository Operations
1

2
Core operations for initializing, cloning, and managing Git repositories.
3

4
## Capabilities
5

6
### Initialize Repository
7

8
Creates a new Git repository in the specified directory.
9

10
```javascript { .api }
11
/**
12
 * Initialize a new repository
13
 * @param args.fs - File system client
14
 * @param args.dir - Working tree directory path
15
 * @param args.gitdir - Git directory path (defaults to dir/.git)
16
 * @param args.bare - Initialize as bare repository
17
 * @param args.defaultBranch - Name of default branch (defaults to 'master')
18
 * @returns Promise resolving when complete
19
 */
20
function init(args: {
21
  fs: FsClient;
22
  dir?: string;
23
  gitdir?: string;
24
  bare?: boolean;
25
  defaultBranch?: string;
26
}): Promise<void>;
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
import git from "isomorphic-git";
33
import fs from "fs";
34

35
// Initialize a new repository
36
await git.init({
37
  fs,
38
  dir: "/path/to/new/repo"
39
});
40

41
// Initialize as bare repository
42
await git.init({
43
  fs,
44
  dir: "/path/to/bare/repo",
45
  bare: true
46
});
47

48
// Initialize with custom default branch
49
await git.init({
50
  fs,
51
  dir: "/path/to/repo",
52
  defaultBranch: "main"
53
});
54
```
55

56
### Clone Repository
57

58
Clones a remote repository to the local file system.
59

60
```javascript { .api }
61
/**
62
 * Clone a repository from a remote URL
63
 * @param args.fs - File system client
64
 * @param args.http - HTTP client for network operations
65
 * @param args.dir - Working tree directory path
66
 * @param args.gitdir - Git directory path (defaults to dir/.git)
67
 * @param args.url - URL of remote repository
68
 * @param args.corsProxy - CORS proxy for browser environments
69
 * @param args.ref - Branch to checkout (defaults to remote's default branch)
70
 * @param args.singleBranch - Only fetch a single branch
71
 * @param args.noCheckout - Skip checkout after clone
72
 * @param args.noTags - Don't fetch tags
73
 * @param args.remote - Name for the remote (defaults to 'origin')
74
 * @param args.depth - Shallow clone depth
75
 * @param args.since - Only fetch commits after this date
76
 * @param args.exclude - Branches/tags to exclude
77
 * @param args.relative - Make depth relative to current shallow depth
78
 * @param args.headers - Additional HTTP headers
79
 * @param args.onProgress - Progress callback
80
 * @param args.onMessage - Message callback
81
 * @param args.onAuth - Authentication callback
82
 * @param args.onAuthFailure - Auth failure callback
83
 * @param args.onAuthSuccess - Auth success callback
84
 * @param args.cache - Cache object
85
 * @returns Promise resolving when clone completes
86
 */
87
function clone(args: {
88
  fs: FsClient;
89
  http: HttpClient;
90
  dir: string;
91
  gitdir?: string;
92
  url: string;
93
  corsProxy?: string;
94
  ref?: string;
95
  singleBranch?: boolean;
96
  noCheckout?: boolean;
97
  noTags?: boolean;
98
  remote?: string;
99
  depth?: number;
100
  since?: Date;
101
  exclude?: string[];
102
  relative?: boolean;
103
  headers?: Record<string, string>;
104
  onProgress?: ProgressCallback;
105
  onMessage?: MessageCallback;
106
  onAuth?: AuthCallback;
107
  onAuthFailure?: AuthFailureCallback;
108
  onAuthSuccess?: AuthSuccessCallback;
109
  cache?: object;
110
}): Promise<void>;
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
import git from "isomorphic-git";
117
import http from "isomorphic-git/http/node";
118
import fs from "fs";
119

120
// Basic clone
121
await git.clone({
122
  fs,
123
  http,
124
  dir: "/path/to/repo",
125
  url: "https://github.com/user/repo.git"
126
});
127

128
// Shallow clone with single branch
129
await git.clone({
130
  fs,
131
  http,
132
  dir: "/path/to/repo",
133
  url: "https://github.com/user/repo.git",
134
  singleBranch: true,
135
  depth: 1
136
});
137

138
// Clone specific branch with progress tracking
139
await git.clone({
140
  fs,
141
  http,
142
  dir: "/path/to/repo",
143
  url: "https://github.com/user/repo.git",
144
  ref: "develop",
145
  onProgress: (event) => {
146
    console.log(`Progress: ${event.phase} ${event.loaded}/${event.total}`);
147
  }
148
});
149

150
// Browser clone with CORS proxy
151
await git.clone({
152
  fs, // LightningFS instance
153
  http, // isomorphic-git/http/web
154
  dir: "/repo",
155
  url: "https://github.com/user/repo.git",
156
  corsProxy: "https://cors.isomorphic-git.org"
157
});
158
```
159

160
### Get Version
161

162
Returns the version of isomorphic-git.
163

164
```javascript { .api }
165
/**
166
 * Get the isomorphic-git version
167
 * @returns Version string
168
 */
169
function version(): string;
170
```
171

172
**Usage Example:**
173

174
```javascript
175
import git from "isomorphic-git";
176

177
console.log(git.version()); // "1.33.1"
178
```
179

180
### Find Repository Root
181

182
Finds the root directory of a Git repository.
183

184
```javascript { .api }
185
/**
186
 * Find the root of the Git repository
187
 * @param args.fs - File system client
188
 * @param args.filepath - Path to start searching from
189
 * @returns Promise resolving to repository root path
190
 */
191
function findRoot(args: {
192
  fs: FsClient;
193
  filepath: string;
194
}): Promise<string>;
195
```
196

197
**Usage Example:**
198

199
```javascript
200
import git from "isomorphic-git";
201
import fs from "fs";
202

203
// Find repo root from any path within the repository
204
const rootDir = await git.findRoot({
205
  fs,
206
  filepath: "/path/to/repo/some/nested/directory"
207
});
208
console.log(rootDir); // "/path/to/repo"
209
```