Actions System

Post-clone manipulation system allowing repositories to define automated actions via degit.json configuration files for customizing the cloned output.

Capabilities

Actions Configuration

Actions are defined in a degit.json file placed at the root of the source repository.

// degit.json format
interface DegitAction[] {
  action: "clone" | "remove";
  // Action-specific properties
}

Usage Examples:

[
  {
    "action": "clone",
    "src": "user/another-repo"
  },
  {
    "action": "remove", 
    "files": ["LICENSE", "README.md"]
  }
]

Clone Action

Clones additional repositories into the current working directory, preserving existing content.

/**
 * Clone action configuration for adding additional repositories
 */
interface CloneAction {
  action: "clone";
  src: string;
  cache?: boolean;
  verbose?: boolean;
}

Usage Examples:

// degit.json
[
  {
    "action": "clone",
    "src": "user/additional-files"
  },
  {
    "action": "clone", 
    "src": "org/shared-config",
    "cache": true,
    "verbose": true
  }
]

Behavior:

• Clones the specified repository into the current directory
• Preserves existing files (stashes them during clone, then restores)
• Supports all the same source formats as the main degit command
• Can specify cache and verbose options per action
• Actions can be chained (cloned repos can have their own degit.json)

Remove Action

Removes specified files or directories from the cloned repository.

/**
 * Remove action configuration for deleting files/directories
 */
interface RemoveAction {
  action: "remove";
  files: string | string[];
}

Usage Examples:

// degit.json - Remove single file
[
  {
    "action": "remove",
    "files": "LICENSE"
  }
]

// Remove multiple files
[
  {
    "action": "remove", 
    "files": ["LICENSE", "README.md", "docs/"]
  }
]

Behavior:

• Removes files or directories after cloning
• Supports both individual files and directories
• Warns if attempting to remove non-existent files
• Can remove directories recursively

Action Processing

Actions are processed automatically after the main repository clone completes.

/**
 * Internal action processing system
 */
interface DirectiveActions {
  clone: (dir: string, dest: string, action: CloneAction) => Promise<void>;
  remove: (dir: string, dest: string, action: RemoveAction) => void;
}

Processing Order:

1. Main repository is cloned
2. degit.json is read from the destination directory
3. Actions are executed in the order they appear in the array
4. degit.json is automatically removed after processing
5. Stashed files (from clone actions) are restored

Event Handling:

• Clone actions emit their own info/warn events with cyan/magenta coloring
• Remove actions emit "REMOVED" info events listing deleted files
• Failed actions display red error messages and exit with code 1

File Stashing System

The actions system includes a file stashing mechanism to preserve existing content during clone actions.

/**
 * File stashing utilities for preserving content during clone actions
 */
function stashFiles(dir: string, dest: string): void;
function unstashFiles(dir: string, dest: string): void;

Stashing Behavior:

• Automatically triggered on first clone action in a degit.json
• Moves existing destination files to temporary directory
• Restores files after all actions complete
• Prevents degit.json from being restored (it's consumed during processing)
• Handles both files and directories recursively

Advanced Action Patterns

Template Composition

// Main template degit.json
[
  {
    "action": "clone",
    "src": "shared/base-config"  
  },
  {
    "action": "clone",
    "src": "shared/eslint-config"
  },
  {
    "action": "remove",
    "files": ["shared/base-config/.gitignore"]
  }
]

Conditional File Removal

// Remove development files for production template
[
  {
    "action": "remove",
    "files": [
      "test/",
      "src/__tests__/", 
      ".travis.yml",
      "jest.config.js"
    ]
  }
]

Nested Action Chains

// Repository A degit.json
[
  {
    "action": "clone", 
    "src": "org/repo-b"  // repo-b can have its own degit.json
  }
]

Configuration Detection

The actions system automatically detects and processes degit.json files.

/**
 * Configuration file detection and processing
 */
const degitConfigName = "degit.json";

function _getDirectives(dest: string): DegitAction[] | false;

Detection Process:

1. Looks for degit.json in the root of the cloned directory
2. Attempts to require/parse the JSON file
3. Clears require cache for hot reloading
4. Automatically deletes the file after reading
5. Returns false if no configuration file exists

Error Handling:

• Invalid JSON in degit.json will cause the clone to fail
• Missing source repositories in clone actions will display errors
• File permission issues during remove actions are handled gracefully