0
# File Management
1

2
Comprehensive file management system supporting all Xcode file types including source files, headers, resources, frameworks, and static libraries with automatic build phase integration.
3

4
## Capabilities
5

6
### Source File Management
7

8
Add and remove source files (.m, .swift, .cpp, etc.) with automatic build phase integration.
9

10
```javascript { .api }
11
/**
12
 * Add source file to project with build phase integration
13
 * Automatically adds to PBXBuildFile, PBXFileReference, and PBXSourcesBuildPhase
14
 * @param {string} path - File path relative to project
15
 * @param {object} opt - Options including target, weak linking, compiler flags
16
 * @param {string} group - Group key for organization, defaults to plugin handling
17
 * @returns {object|boolean} File object or false if file already exists
18
 */
19
addSourceFile(path, opt, group);
20

21
/**
22
 * Remove source file from project and all build phases
23
 * @param {string} path - File path relative to project
24
 * @param {object} opt - Options including target specification
25
 * @param {string} group - Group key where file is located
26
 * @returns {object} Removed file object
27
 */
28
removeSourceFile(path, opt, group);
29
```
30

31
**Usage Examples:**
32

33
```javascript
34
// Add Objective-C source file
35
const file = proj.addSourceFile('src/MyClass.m');
36
console.log('Added file:', file.basename);
37

38
// Add Swift file with compiler flags
39
const swiftFile = proj.addSourceFile('src/MySwiftClass.swift', {
40
    compilerFlags: '-fno-objc-arc'
41
});
42

43
// Add source file to specific group and target
44
const targetFile = proj.addSourceFile('src/TargetSpecific.m', {
45
    target: 'TARGET_UUID_HERE'
46
}, 'CustomGroup');
47

48
// Remove source file
49
proj.removeSourceFile('src/OldClass.m');
50
```
51

52
### Header File Management
53

54
Add and remove header files (.h, .hpp) with proper group organization.
55

56
```javascript { .api }
57
/**
58
 * Add header file to project
59
 * Headers are typically added to file references but not build phases
60
 * @param {string} path - File path relative to project
61
 * @param {object} opt - Options object
62
 * @param {string} group - Group key for organization
63
 * @returns {object|null} File object or null if file already exists
64
 */
65
addHeaderFile(path, opt, group);
66

67
/**
68
 * Remove header file from project
69
 * @param {string} path - File path relative to project
70
 * @param {object} opt - Options object
71
 * @param {string} group - Group key where file is located
72
 * @returns {object} Removed file object
73
 */
74
removeHeaderFile(path, opt, group);
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
// Add header file
81
const header = proj.addHeaderFile('src/MyClass.h');
82

83
// Add header to specific group
84
const groupedHeader = proj.addHeaderFile('include/PublicAPI.h', {}, 'PublicHeaders');
85

86
// Remove header file
87
proj.removeHeaderFile('src/OldHeader.h');
88
```
89

90
### Plugin File Management
91

92
Add and remove plugin files with special handling for Cordova/PhoneGap plugins and embedded frameworks.
93

94
```javascript { .api }
95
/**
96
 * Add plugin file to project with plugin-specific handling
97
 * Plugin files have special path correction and are added to the plugins group
98
 * @param {string} path - File path relative to project
99
 * @param {object} opt - Options object including target specification
100
 * @returns {object|null} File object or null if file already exists
101
 */
102
addPluginFile(path, opt);
103

104
/**
105
 * Remove plugin file from project and plugins group
106
 * @param {string} path - File path relative to project
107
 * @param {object} opt - Options object including target specification
108
 * @returns {object} Removed file object
109
 */
110
removePluginFile(path, opt);
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
// Add plugin source file
117
const pluginFile = proj.addPluginFile('plugins/MyPlugin/src/MyPlugin.m');
118

119
// Add plugin file to specific target
120
const targetPlugin = proj.addPluginFile('plugins/MyPlugin/src/TargetPlugin.m', {
121
    target: 'TARGET_UUID_HERE'
122
});
123

124
// Remove plugin file
125
proj.removePluginFile('plugins/OldPlugin/src/OldPlugin.m');
126

127
// Plugin files are automatically:
128
// - Added to PBXFileReference section
129
// - Added to the plugins PBXGroup
130
// - Given proper plugin path correction
131
// - Marked with plugin flag
132
```
133

134
### Core Data Model Management
135

136
Add and manage Core Data model documents (.xcdatamodeld) with version group support.
137

138
```javascript { .api }
139
/**
140
 * Add Core Data model document to project
141
 * Handles .xcdatamodeld bundles with multiple model versions
142
 * @param {string} filePath - Path to .xcdatamodeld bundle
143
 * @param {string} group - Group key, defaults to 'Resources'
144
 * @param {object} opt - Options object
145
 * @returns {object|null} File object or null if file already exists
146
 */
147
addDataModelDocument(filePath, group, opt);
148

149
/**
150
 * Add file to XCVersionGroup section for Core Data models
151
 * Internal method used by addDataModelDocument
152
 * @param {object} file - File object with models and currentModel properties
153
 */
154
addToXcVersionGroupSection(file);
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
// Add Core Data model
161
const dataModel = proj.addDataModelDocument('Models/DataModel.xcdatamodeld');
162

163
// Add to specific group
164
const customDataModel = proj.addDataModelDocument(
165
    'CustomModels/MyModel.xcdatamodeld', 
166
    'DataModels'
167
);
168

169
// Core Data models are automatically:
170
// - Added to XCVersionGroup section
171
// - Linked to individual .xcdatamodel files
172
// - Added to appropriate build phases
173
// - Configured with current model version
174
```
175

176
### Resource File Management
177

178
Add and remove resource files (images, plists, xibs, etc.) with automatic build phase integration.
179

180
```javascript { .api }
181
/**
182
 * Add resource file with automatic build phase integration
183
 * Automatically determines file type and adds to appropriate build phases
184
 * @param {string} path - File path relative to project
185
 * @param {object} opt - Options including plugin flag, target, variant group handling
186
 * @param {string} group - Group key for organization
187
 * @returns {object|boolean} File object or false if file already exists
188
 */
189
addResourceFile(path, opt, group);
190

191
/**
192
 * Remove resource file from project and build phases
193
 * @param {string} path - File path relative to project
194
 * @param {object} opt - Options including target specification
195
 * @param {string} group - Group key where file is located
196
 * @returns {object} Removed file object
197
 */
198
removeResourceFile(path, opt, group);
199
```
200

201
**Usage Examples:**
202

203
```javascript
204
// Add image resource
205
const image = proj.addResourceFile('assets/icon.png');
206

207
// Add plist file
208
const plist = proj.addResourceFile('config/Settings.plist');
209

210
// Add resource to specific target
211
const targetResource = proj.addResourceFile('assets/target-icon.png', {
212
    target: 'TARGET_UUID_HERE'
213
});
214

215
// Add plugin resource
216
const pluginResource = proj.addResourceFile('plugins/MyPlugin.bundle', {
217
    plugin: true
218
});
219

220
// Remove resource file
221
proj.removeResourceFile('assets/old-icon.png');
222
```
223

224
### Copy File Management
225

226
Add and remove files to copy file build phases for bundling resources or frameworks.
227

228
```javascript { .api }
229
/**
230
 * Add file to copy files build phase
231
 * Used for copying files into the app bundle or specific locations
232
 * @param {string} path - File path relative to project
233
 * @param {object} opt - Options including target specification
234
 * @returns {object} File object with copy phase integration
235
 */
236
addCopyfile(path, opt);
237

238
/**
239
 * Remove file from copy files build phase
240
 * @param {string} path - File path relative to project
241
 * @param {object} opt - Options including target specification
242
 * @returns {object} Removed file object
243
 */
244
removeCopyfile(path, opt);
245
```
246

247
**Usage Examples:**
248

249
```javascript
250
// Add file to copy phase
251
const copyFile = proj.addCopyfile('resources/data.json');
252

253
// Add file to specific target's copy phase
254
const targetCopyFile = proj.addCopyfile('frameworks/Custom.framework', {
255
    target: 'TARGET_UUID_HERE'
256
});
257

258
// Remove from copy phase
259
proj.removeCopyfile('resources/old-data.json');
260
```
261

262
### File Existence Checking
263

264
Check if a file already exists in the project before adding.
265

266
```javascript { .api }
267
/**
268
 * Check if file already exists in project
269
 * @param {string} filePath - File path to check
270
 * @returns {object|boolean} File object if exists, false otherwise
271
 */
272
hasFile(filePath);
273
```
274

275
**Usage Examples:**
276

277
```javascript
278
// Check before adding
279
if (!proj.hasFile('src/NewClass.m')) {
280
    proj.addSourceFile('src/NewClass.m');
281
    console.log('File added successfully');
282
} else {
283
    console.log('File already exists in project');
284
}
285

286
// Get existing file info
287
const existingFile = proj.hasFile('src/ExistingClass.m');
288
if (existingFile) {
289
    console.log('File type:', existingFile.lastKnownFileType);
290
    console.log('File path:', existingFile.path);
291
}
292
```
293

294
### Generic File Management
295

296
Add and remove files to specific groups without build phase integration.
297

298
```javascript { .api }
299
/**
300
 * Add file to specified group without build phase integration
301
 * @param {string} path - File path relative to project
302
 * @param {string} group - Group key for organization
303
 * @param {object} opt - Options object
304
 * @returns {object|null} File object or null if file already exists
305
 */
306
addFile(path, group, opt);
307

308
/**
309
 * Remove file from specified group
310
 * @param {string} path - File path relative to project
311
 * @param {string} group - Group key where file is located
312
 * @param {object} opt - Options object
313
 * @returns {object} Removed file object
314
 */
315
removeFile(path, group, opt);
316
```
317

318
**Usage Examples:**
319

320
```javascript
321
// Add file to custom group
322
const file = proj.addFile('docs/README.md', 'Documentation');
323

324
// Add file with specific options
325
const configFile = proj.addFile('config/build.json', 'Configuration', {
326
    lastKnownFileType: 'text.json'
327
});
328

329
// Remove file from group
330
proj.removeFile('docs/OLD.md', 'Documentation');
331
```
332

333
### Product File Management
334

335
Add and remove product files (built outputs like .app, .framework).
336

337
```javascript { .api }
338
/**
339
 * Add product file with target options
340
 * Used for build outputs and target products
341
 * @param {string} targetPath - Product file path
342
 * @param {object} opt - Options including target, group, explicit file type
343
 * @returns {object} File object representing the product
344
 */
345
addProductFile(targetPath, opt);
346

347
/**
348
 * Remove product file from project
349
 * @param {string} path - Product file path
350
 * @param {object} opt - Options object
351
 * @returns {object} Removed file object
352
 */
353
removeProductFile(path, opt);
354
```
355

356
**Usage Examples:**
357

358
```javascript
359
// Add app product
360
const appProduct = proj.addProductFile('MyApp.app', {
361
    target: 'APP_TARGET_UUID',
362
    group: 'Products',
363
    explicitFileType: 'wrapper.application'
364
});
365

366
// Add framework product
367
const frameworkProduct = proj.addProductFile('MyFramework.framework', {
368
    target: 'FRAMEWORK_TARGET_UUID',
369
    explicitFileType: 'wrapper.framework'
370
});
371

372
// Remove product
373
proj.removeProductFile('OldApp.app');
374
```
375

376
### File Options Reference
377

378
```javascript { .api }
379
/**
380
 * Comprehensive options for file operations
381
 */
382
interface FileOptions {
383
  /** Target UUID for multi-target projects */
384
  target?: string;
385
  
386
  /** Enable weak linking for frameworks and libraries */
387
  weak?: boolean;
388
  
389
  /** Custom compiler flags for source files */
390
  compilerFlags?: string;
391
  
392
  /** Mark as custom framework (affects path handling) */
393
  customFramework?: boolean;
394
  
395
  /** Embed framework in app bundle */
396
  embed?: boolean;
397
  
398
  /** Code sign framework on copy */
399
  sign?: boolean;
400
  
401
  /** Mark as plugin file (affects group placement) */
402
  plugin?: boolean;
403
  
404
  /** Override explicit file type */
405
  explicitFileType?: string;
406
  
407
  /** Override detected file type */
408
  lastKnownFileType?: string;
409
  
410
  /** Override source tree setting */
411
  sourceTree?: string;
412
  
413
  /** Override text encoding for text files */
414
  defaultEncoding?: number;
415
  
416
  /** Prevent adding to variant group */
417
  variantGroup?: boolean;
418
}
419
```
420

421
### Supported File Types
422

423
The package automatically detects and handles these file types:
424

425
```javascript { .api }
426
/**
427
 * File type mappings by extension
428
 */
429
const SUPPORTED_EXTENSIONS = {
430
  // Source files
431
  'm': 'sourcecode.c.objc',
432
  'mm': 'sourcecode.cpp.objcpp', 
433
  'swift': 'sourcecode.swift',
434
  'h': 'sourcecode.c.h',
435
  'hpp': 'sourcecode.cpp.h',
436
  
437
  // Resources
438
  'plist': 'text.plist.xml',
439
  'strings': 'text.plist.strings',
440
  'xib': 'file.xib',
441
  'xcassets': 'folder.assetcatalog',
442
  
443
  // Frameworks and libraries
444
  'framework': 'wrapper.framework',
445
  'dylib': 'compiled.mach-o.dylib',
446
  'a': 'archive.ar',
447
  'tbd': 'sourcecode.text-based-dylib-definition',
448
  
449
  // Applications and bundles
450
  'app': 'wrapper.application',
451
  'appex': 'wrapper.app-extension',
452
  'bundle': 'wrapper.plug-in',
453
  
454
  // Data models
455
  'xcdatamodel': 'wrapper.xcdatamodel',
456
  
457
  // Configuration
458
  'xcconfig': 'text.xcconfig',
459
  
460
  // Scripts
461
  'sh': 'text.script.sh'
462
};
463
```