0
# Group Management
1

2
Project organization system for managing file groups, variant groups, and hierarchical project structure with support for custom groups and localization.
3

4
## Capabilities
5

6
### Group Creation and Management
7

8
Create and manage PBXGroup structures for organizing files in the Xcode project navigator.
9

10
```javascript { .api }
11
/**
12
 * Create new PBXGroup with files
13
 * @param {string[]} filePathsArray - Array of file paths to include in group
14
 * @param {string} name - Group name displayed in Xcode
15
 * @param {string} path - Group path on filesystem (optional)
16
 * @param {string} sourceTree - Source tree type (default: "<group>")
17
 * @returns {object} Group object with UUID and group data
18
 */
19
addPbxGroup(filePathsArray, name, path, sourceTree);
20

21
/**
22
 * Remove PBXGroup by name
23
 * @param {string} groupName - Name of group to remove
24
 */
25
removePbxGroup(groupName);
26

27
/**
28
 * Create new PBXGroup with UUID generation
29
 * @param {string} name - Group name
30
 * @param {string} pathName - Optional path for group
31
 * @returns {string} Generated UUID for the new group
32
 */
33
pbxCreateGroup(name, pathName);
34
```
35

36
**Usage Examples:**
37

38
```javascript
39
// Create group with files
40
const sourceGroup = proj.addPbxGroup(
41
    ['src/Model.m', 'src/View.m', 'src/Controller.m'],
42
    'MVC Components',
43
    'src'
44
);
45
console.log('Created group with UUID:', sourceGroup.uuid);
46

47
// Create empty group and add files later
48
const utilsGroupUuid = proj.pbxCreateGroup('Utilities', 'utils');
49
proj.addFile('utils/Helper.m', utilsGroupUuid);
50
proj.addFile('utils/Constants.h', utilsGroupUuid);
51

52
// Remove group
53
proj.removePbxGroup('Old Components');
54
```
55

56
### Variant Group Management
57

58
Create and manage PBXVariantGroup for localization and file variants.
59

60
```javascript { .api }
61
/**
62
 * Create new PBXVariantGroup for localization
63
 * @param {string} name - Variant group name
64
 * @returns {string} Generated UUID for the variant group
65
 */
66
pbxCreateVariantGroup(name);
67

68
/**
69
 * Add localization variant group with build phase integration
70
 * @param {string} name - Name of the localization group
71
 * @returns {object} Variant group object with build phase integration
72
 */
73
addLocalizationVariantGroup(name);
74
```
75

76
**Usage Examples:**
77

78
```javascript
79
// Create variant group for localization
80
const localizedStrings = proj.addLocalizationVariantGroup('Localizable.strings');
81

82
// Create empty variant group
83
const imageVariantUuid = proj.pbxCreateVariantGroup('AppIcon.png');
84

85
// Add localized files to variant group
86
proj.addFile('en.lproj/Localizable.strings', localizedStrings.fileRef);
87
proj.addFile('es.lproj/Localizable.strings', localizedStrings.fileRef);
88
```
89

90
### Group Access and Search
91

92
Find and access existing groups in the project structure.
93

94
```javascript { .api }
95
/**
96
 * Find group by name
97
 * @param {string} name - Group name to search for
98
 * @returns {object|null} Group object or null if not found
99
 */
100
pbxGroupByName(name);
101

102
/**
103
 * Get group by UUID key
104
 * @param {string} key - Group UUID
105
 * @returns {object} Group object
106
 */
107
getPBXGroupByKey(key);
108

109
/**
110
 * Get variant group by UUID key
111
 * @param {string} key - Variant group UUID
112
 * @returns {object} Variant group object
113
 */
114
getPBXVariantGroupByKey(key);
115

116
/**
117
 * Find group key by search criteria
118
 * @param {object} criteria - Search criteria (name, path, or both)
119
 * @returns {string|null} Group UUID or null if not found
120
 */
121
findPBXGroupKey(criteria);
122

123
/**
124
 * Find variant group key by search criteria
125
 * @param {object} criteria - Search criteria
126
 * @returns {string|null} Variant group UUID or null if not found
127
 */
128
findPBXVariantGroupKey(criteria);
129
```
130

131
**Usage Examples:**
132

133
```javascript
134
// Find existing groups
135
const resourcesGroup = proj.pbxGroupByName('Resources');
136
if (resourcesGroup) {
137
    console.log('Resources group children:', resourcesGroup.children.length);
138
}
139

140
// Search by criteria
141
const sourceGroupKey = proj.findPBXGroupKey({ name: 'Sources', path: 'src' });
142
const docGroupKey = proj.findPBXGroupKey({ path: 'Documentation' });
143

144
// Access group by UUID
145
const group = proj.getPBXGroupByKey(sourceGroupKey);
146
console.log('Group name:', group.name);
147
```
148

149
### File-to-Group Operations
150

151
Add and remove files to/from specific groups.
152

153
```javascript { .api }
154
/**
155
 * Add file to existing PBXGroup
156
 * @param {object|string} file - File object or group key
157
 * @param {string} groupKey - Target group UUID
158
 */
159
addToPbxGroup(file, groupKey);
160

161
/**
162
 * Remove file from PBXGroup
163
 * @param {object} file - File object to remove
164
 * @param {string} groupKey - Source group UUID
165
 */
166
removeFromPbxGroup(file, groupKey);
167

168
/**
169
 * Add file to PBXVariantGroup
170
 * @param {object} file - File object to add
171
 * @param {string} groupKey - Target variant group UUID
172
 */
173
addToPbxVariantGroup(file, groupKey);
174

175
/**
176
 * Remove file from PBXVariantGroup
177
 * @param {object} file - File object to remove
178
 * @param {string} groupKey - Source variant group UUID
179
 */
180
removeFromPbxVariantGroup(file, groupKey);
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
// Add file to existing group
187
const sourceFile = proj.addFile('NewClass.m', null); // Create without group
188
const sourcesGroupKey = proj.findPBXGroupKey({ name: 'Sources' });
189
proj.addToPbxGroup(sourceFile, sourcesGroupKey);
190

191
// Add file to variant group for localization
192
const localizedFile = proj.addFile('en.lproj/Main.strings', null);
193
const stringsVariantKey = proj.findPBXVariantGroupKey({ name: 'Main.strings' });
194
proj.addToPbxVariantGroup(localizedFile, stringsVariantKey);
195

196
// Remove file from group
197
proj.removeFromPbxGroup(sourceFile, sourcesGroupKey);
198
```
199

200
### Default Group Management
201

202
Access and manage standard Xcode groups.
203

204
```javascript { .api }
205
// Standard group access methods (internal but commonly used)
206

207
/**
208
 * Add file to Plugins group (creates if doesn't exist)
209
 * @param {object} file - File object to add
210
 */
211
addToPluginsPbxGroup(file);
212

213
/**
214
 * Add file to Resources group (creates if doesn't exist)
215
 * @param {object} file - File object to add
216
 */
217
addToResourcesPbxGroup(file);
218

219
/**
220
 * Add file to Frameworks group (creates if doesn't exist)
221
 * @param {object} file - File object to add
222
 */
223
addToFrameworksPbxGroup(file);
224

225
/**
226
 * Add file to Products group (creates if doesn't exist)
227
 * @param {object} file - File object to add
228
 */
229
addToProductsPbxGroup(file);
230
```
231

232
**Usage Examples:**
233

234
```javascript
235
// These are typically called automatically by higher-level methods
236
// but can be used directly for custom organization
237

238
// Add framework to Frameworks group
239
const framework = { fileRef: 'UUID', basename: 'MyFramework.framework' };
240
proj.addToFrameworksPbxGroup(framework);
241

242
// Add resource to Resources group
243
const resource = { fileRef: 'UUID', basename: 'icon.png' };
244
proj.addToResourcesPbxGroup(resource);
245
```
246

247
### Localization and Region Management
248

249
Manage known regions for localization support.
250

251
```javascript { .api }
252
/**
253
 * Add known region for localization
254
 * @param {string} name - Region code (e.g., 'en', 'es', 'fr')
255
 */
256
addKnownRegion(name);
257

258
/**
259
 * Remove known region
260
 * @param {string} name - Region code to remove
261
 */
262
removeKnownRegion(name);
263

264
/**
265
 * Check if region is known
266
 * @param {string} name - Region code to check
267
 * @returns {boolean} True if region is known
268
 */
269
hasKnownRegion(name);
270
```
271

272
**Usage Examples:**
273

274
```javascript
275
// Add localization regions
276
proj.addKnownRegion('en');
277
proj.addKnownRegion('es');
278
proj.addKnownRegion('fr');
279

280
// Check if region exists
281
if (!proj.hasKnownRegion('de')) {
282
    proj.addKnownRegion('de');
283
    console.log('Added German localization');
284
}
285

286
// Remove unused region
287
proj.removeKnownRegion('old-region');
288
```
289

290
### Group Structure Types
291

292
```javascript { .api }
293
/**
294
 * Group structure definitions
295
 */
296
interface PBXGroup {
297
  /** Group type identifier */
298
  isa: 'PBXGroup';
299
  
300
  /** Array of child file/group references */
301
  children: GroupChild[];
302
  
303
  /** Group name displayed in Xcode */
304
  name?: string;
305
  
306
  /** Filesystem path (optional) */
307
  path?: string;
308
  
309
  /** Source tree type */
310
  sourceTree: string;
311
}
312

313
interface PBXVariantGroup {
314
  /** Variant group type identifier */
315
  isa: 'PBXVariantGroup';
316
  
317
  /** Array of variant file references */
318
  children: GroupChild[];
319
  
320
  /** Variant group name */
321
  name: string;
322
  
323
  /** Source tree type */
324
  sourceTree: string;
325
}
326

327
interface GroupChild {
328
  /** Reference UUID */
329
  value: string;
330
  
331
  /** Display comment/name */
332
  comment: string;
333
}
334
```
335

336
### Search Criteria Options
337

338
```javascript { .api }
339
/**
340
 * Search criteria for finding groups
341
 */
342
interface GroupSearchCriteria {
343
  /** Group name to match */
344
  name?: string;
345
  
346
  /** Group path to match */
347
  path?: string;
348
}
349
```
350

351
**Usage Examples:**
352

353
```javascript
354
// Search by name only
355
const resourcesKey = proj.findPBXGroupKey({ name: 'Resources' });
356

357
// Search by path only
358
const srcKey = proj.findPBXGroupKey({ path: 'src' });
359

360
// Search by both name and path
361
const specificKey = proj.findPBXGroupKey({ 
362
    name: 'Custom Sources', 
363
    path: 'custom/src' 
364
});
365
```
366

367
### Advanced Group Patterns
368

369
**Hierarchical Group Structure:**
370
```javascript
371
// Create nested group structure
372
const mainGroupKey = proj.pbxCreateGroup('Application');
373
const modelsGroupKey = proj.pbxCreateGroup('Models', 'src/models');
374
const viewsGroupKey = proj.pbxCreateGroup('Views', 'src/views');
375

376
// Add sub-groups to main group
377
proj.addToPbxGroup(modelsGroupKey, mainGroupKey);
378
proj.addToPbxGroup(viewsGroupKey, mainGroupKey);
379

380
// Add files to sub-groups
381
proj.addFile('src/models/User.m', modelsGroupKey);
382
proj.addFile('src/views/UserView.m', viewsGroupKey);
383
```
384

385
**Localization Setup:**
386
```javascript
387
// Set up complete localization structure
388
const supportedLanguages = ['en', 'es', 'fr', 'de'];
389

390
// Add known regions
391
supportedLanguages.forEach(lang => {
392
    proj.addKnownRegion(lang);
393
});
394

395
// Create localized strings variant group
396
const stringsGroup = proj.addLocalizationVariantGroup('Localizable.strings');
397

398
// Add localized files
399
supportedLanguages.forEach(lang => {
400
    const localizedFile = proj.addFile(`${lang}.lproj/Localizable.strings`, null);
401
    proj.addToPbxVariantGroup(localizedFile, stringsGroup.fileRef);
402
});
403
```
404

405
### Low-Level Group Operations
406

407
Advanced methods for direct group manipulation at the PBX level, useful for custom group types and specialized operations.
408

409
```javascript { .api }
410
/**
411
 * Add file or group to any PBXGroup type
412
 * Generic method that works with PBXGroup, PBXVariantGroup, etc.
413
 * @param {object|string} file - File object or group key to add
414
 * @param {string} groupKey - Target group UUID
415
 * @param {string} groupType - PBX group type (PBXGroup, PBXVariantGroup)
416
 */
417
addToPbxGroupType(file, groupKey, groupType);
418

419
/**
420
 * Remove file or group from any PBXGroup type
421
 * Generic removal method for all group types
422
 * @param {object|string} file - File object or group key to remove
423
 * @param {string} groupKey - Target group UUID  
424
 * @param {string} groupType - PBX group type (PBXGroup, PBXVariantGroup)
425
 */
426
removeFromPbxGroupAndType(file, groupKey, groupType);
427

428
/**
429
 * Get group object by key and type
430
 * Direct access to group objects in project structure
431
 * @param {string} key - Group UUID
432
 * @param {string} groupType - PBX group type
433
 * @returns {object|undefined} Group object or undefined if not found
434
 */
435
getPBXGroupByKeyAndType(key, groupType);
436

437
/**
438
 * Get any PBX object section by name
439
 * Generic access to project object sections
440
 * @param {string} name - Section name (PBXGroup, PBXFileReference, etc.)
441
 * @returns {object} Section object containing all items of that type
442
 */
443
getPBXObject(name);
444
```
445

446
**Usage Examples:**
447

448
```javascript
449
// Direct group type manipulation
450
proj.addToPbxGroupType(file, groupKey, 'PBXVariantGroup');
451
proj.removeFromPbxGroupAndType(file, groupKey, 'PBXGroup');
452

453
// Access specific section types
454
const allGroups = proj.getPBXObject('PBXGroup');
455
const allFileRefs = proj.getPBXObject('PBXFileReference');
456

457
// Direct group access by type
458
const variantGroup = proj.getPBXGroupByKeyAndType(groupKey, 'PBXVariantGroup');
459
const regularGroup = proj.getPBXGroupByKeyAndType(groupKey, 'PBXGroup');
460

461
// Advanced group manipulation
462
Object.keys(allGroups).forEach(groupKey => {
463
    if (!groupKey.endsWith('_comment')) {
464
        const group = allGroups[groupKey];
465
        console.log(`Group ${group.name} has ${group.children.length} children`);
466
    }
467
});
468
```