0
# Checkout Operations
1

2
Working directory checkout operations for updating files to match specific commits, branches, or index states. The Checkout class provides comprehensive control over working directory updates with conflict resolution and progress reporting.
3

4
## Core Imports
5

6
```javascript
7
const NodeGit = require('nodegit');
8
const Checkout = NodeGit.Checkout;
9
```
10

11
## Capabilities
12

13
### Checkout Targets
14

15
Checkout different Git targets to the working directory.
16

17
```javascript { .api }
18
/**
19
 * Checkout repository HEAD to working directory
20
 * @param {Repository} repo - Repository to checkout
21
 * @param {CheckoutOptions} options - Checkout options
22
 * @returns {Promise<void>}
23
 */
24
Checkout.head(repo, options): Promise<void>;
25

26
/**
27
 * Checkout index to working directory
28
 * @param {Repository} repo - Repository to checkout
29
 * @param {Index} index - Index to checkout
30
 * @param {CheckoutOptions} options - Checkout options
31
 * @returns {Promise<void>}
32
 */
33
Checkout.index(repo, index, options): Promise<void>;
34

35
/**
36
 * Checkout a tree-ish object to working directory
37
 * @param {Repository} repo - Repository to checkout
38
 * @param {String|Tree|Commit|Reference} treeish - Object to checkout
39
 * @param {CheckoutOptions} options - Checkout options
40
 * @returns {Promise<void>}
41
 */
42
Checkout.tree(repo, treeish, options): Promise<void>;
43
```
44

45
### Checkout Strategies
46

47
Control how checkout operations handle conflicts and modifications.
48

49
**Usage Examples:**
50

51
```javascript
52
const NodeGit = require('nodegit');
53

54
// Simple HEAD checkout (reset working directory)
55
NodeGit.Repository.open('./my-repo')
56
  .then(repo => {
57
    return NodeGit.Checkout.head(repo);
58
  })
59
  .then(() => {
60
    console.log('Working directory reset to HEAD');
61
  });
62

63
// Checkout specific commit
64
NodeGit.Repository.open('./my-repo')
65
  .then(repo => {
66
    return repo.getCommit('abc123...');
67
  })
68
  .then(commit => {
69
    return NodeGit.Checkout.tree(repo, commit, {
70
      checkoutStrategy: NodeGit.Checkout.STRATEGY.SAFE
71
    });
72
  })
73
  .then(() => {
74
    console.log('Checked out specific commit');
75
  });
76

77
// Checkout with conflict resolution
78
NodeGit.Repository.open('./my-repo')
79
  .then(repo => {
80
    return NodeGit.Checkout.head(repo, {
81
      checkoutStrategy: NodeGit.Checkout.STRATEGY.FORCE,
82
      progressCallback: (path, completedSteps, totalSteps) => {
83
        console.log(`Checkout progress: ${completedSteps}/${totalSteps} - ${path}`);
84
      },
85
      notifyCallback: (why, path, baseline, target, workdir) => {
86
        console.log(`Checkout notification: ${path} - ${why}`);
87
        return 0; // continue
88
      }
89
    });
90
  });
91

92
// Checkout specific paths only
93
NodeGit.Repository.open('./my-repo')
94
  .then(repo => {
95
    return NodeGit.Checkout.head(repo, {
96
      checkoutStrategy: NodeGit.Checkout.STRATEGY.SAFE,
97
      paths: ['src/*.js', 'package.json']
98
    });
99
  })
100
  .then(() => {
101
    console.log('Checked out specific paths only');
102
  });
103

104
// Checkout branch
105
NodeGit.Repository.open('./my-repo')
106
  .then(repo => {
107
    return repo.getBranch('feature-branch');
108
  })
109
  .then(reference => {
110
    return NodeGit.Checkout.tree(repo, reference, {
111
      checkoutStrategy: NodeGit.Checkout.STRATEGY.SAFE
112
    });
113
  })
114
  .then(() => {
115
    console.log('Checked out feature branch');
116
  });
117
```
118

119
## Types
120

121
```javascript { .api }
122
interface CheckoutOptions {
123
  /** Checkout strategy flags */
124
  checkoutStrategy?: number;
125
  /** Disable file filters during checkout */
126
  disableFilters?: boolean;
127
  /** Directory permissions for new directories */
128
  dirMode?: number;
129
  /** File permissions for new files */
130
  fileMode?: number;
131
  /** File open flags */
132
  fileOpenFlags?: number;
133
  /** Notify callback for checkout events */
134
  notifyCallback?: (why: number, path: string, baseline: DiffFile, target: DiffFile, workdir: DiffFile) => number;
135
  /** Notify flags for callback triggering */
136
  notifyFlags?: number;
137
  /** Progress callback for checkout progress */
138
  progressCallback?: (path: string, completedSteps: number, totalSteps: number) => void;
139
  /** Array of paths to checkout (pathspec) */
140
  paths?: string[];
141
  /** Baseline tree for 3-way merge */
142
  baseline?: Tree;
143
  /** Target directory for checkout */
144
  targetDirectory?: string;
145
  /** Ancestor label for conflict markers */
146
  ancestorLabel?: string;
147
  /** Our label for conflict markers */
148
  ourLabel?: string;
149
  /** Their label for conflict markers */
150
  theirLabel?: string;
151
}
152

153
interface DiffFile {
154
  /** File path */
155
  path(): string;
156
  /** File size */
157
  size(): number;
158
  /** File flags */
159
  flags(): number;
160
  /** File mode */
161
  mode(): number;
162
  /** File OID */
163
  id(): Oid;
164
}
165
```
166

167
## Checkout Strategies
168

169
```javascript { .api }
170
Checkout.STRATEGY = {
171
  /** No special checkout behavior */
172
  NONE: 0,
173
  /** Safe checkout - only update files with no changes */
174
  SAFE: 1,
175
  /** Force checkout - overwrite existing files */
176
  FORCE: 2,
177
  /** Recreate missing files */
178
  RECREATE_MISSING: 4,
179
  /** Allow checkout of file with conflicts */
180
  ALLOW_CONFLICTS: 16,
181
  /** Remove untracked files not being checked out */
182
  REMOVE_UNTRACKED: 32,
183
  /** Remove ignored files not being checked out */
184
  REMOVE_IGNORED: 64,
185
  /** Update only files in index */
186
  UPDATE_ONLY: 128,
187
  /** Don't overwrite ignored files that exist */
188
  DONT_OVERWRITE_IGNORED: 256,
189
  /** Write normal files instead of symlinks */
190
  NO_REFRESH: 512,
191
  /** Skip files with unmerged index entries */
192
  SKIP_UNMERGED: 1024,
193
  /** Use ours when conflicts are encountered */
194
  USE_OURS: 2048,
195
  /** Use theirs when conflicts are encountered */
196
  USE_THEIRS: 4096,
197
  /** Disable pathspec pattern matching */
198
  DISABLE_PATHSPEC_MATCH: 8192,
199
  /** Skip locked files */
200
  SKIP_LOCKED_DIRECTORIES: 16384,
201
  /** Don't write updated files to disk */
202
  DONT_WRITE_INDEX: 32768,
203
  /** Update submodules if they have changed */
204
  UPDATE_SUBMODULES: 65536,
205
  /** Write conflict files for 3-way merge */
206
  CONFLICT_STYLE_MERGE: 131072,
207
  /** Write diff3 style conflict files */
208
  CONFLICT_STYLE_DIFF3: 262144
209
};
210
```
211

212
## Notification Types
213

214
```javascript { .api }
215
Checkout.NOTIFY = {
216
  /** File conflicts with existing file */
217
  CONFLICT: 1,
218
  /** File is dirty in working directory */
219
  DIRTY: 2,
220
  /** File was updated */
221
  UPDATED: 4,
222
  /** File was not updated (no-op) */
223
  UNTRACKED: 8,
224
  /** File was ignored */
225
  IGNORED: 16,
226
  /** Catch all notification types */
227
  ALL: 0x0FFFF
228
};
229
```