Coldstart

Coldstart is a command-line tool that simplifies the process of cloning and setting up Git repositories. It automates the process of cloning a repository, with options to remove Git-related files, initialize a new Git repository, and install dependencies.

Features

• Clone any Git repository
• Remove Git-related files and directories (.git, .gitmodules) while preserving .gitignore
• Optionally keep all Git-related files
• Optionally initialize a new Git repository
• Optionally install npm dependencies if package.json is present
• Flexible directory naming

Installation

Prerequisites

• Node.js (version 12 or higher)
• npm (usually comes with Node.js)
• Git

Global Installation

To install Coldstart globally, run:

npm install -g @coderjamie/coldstart

Local Installation

If you prefer to install it locally in your project:

npm install @coderjamie/coldstart

Usage

Basic Usage

coldstart <repository-url> [target-directory] [options]

• <repository-url>: The URL of the Git repository you want to clone (required)
• [target-directory]: The directory where you want to clone the repository (optional)

If no target directory is specified, Coldstart will use the repository name as the directory name.

Options

• --keep-git-files: Keep the original Git-related files (.git, .gitignore, .gitmodules)
• --init-git: Initialize a new Git repository after cloning
• --install-deps: Automatically install npm dependencies if a package.json file is present. Use this only with repositories you trust, because npm install scripts can execute code from the cloned project.
• -v, --version: Print the installed Coldstart version
• -h, --help: Show CLI usage and options

Examples

1. Clone a repository into a new directory:

   coldstart https://github.com/username/repo.git my-new-project

2. Clone a repository, initialize a new repo, and install dependencies:

   coldstart https://github.com/username/repo.git --init-git --install-deps

3. Clone a repository and only initialize a new Git repo:

   coldstart https://github.com/username/repo.git --init-git

4. Print version or help information:

   coldstart -v
   coldstart -h

What it does

1. Clones the specified Git repository
2. Removes Git-related files (unless --keep-git-files is used)
3. Optionally initializes a new Git repository (if --init-git is used)
4. Optionally installs npm dependencies if a package.json file is present (if --install-deps is used)

Security: intentional command execution

Coldstart intentionally runs local system commands because cloning and setting up a repository requires Git, and --install-deps optionally delegates dependency installation to npm. Supply-chain scanners such as Socket.dev may flag this package for shell access because it imports Node's child_process module.

The CLI runs commands with execFileSync(command, args), not shell command strings. Repository URLs and target directories are passed as argument array values, so shell metacharacters such as ;, &&, and backticks are treated as literal argument text instead of being interpreted by a shell.

The intended external commands are limited to:

• git clone
• git init, git add, and git commit when --init-git is used
• npm install only when --install-deps is used

Only use --install-deps with repositories you trust. npm lifecycle scripts from the cloned project can execute code during installation.

Version Notes

1.2.8

• Documentation: Added a security note explaining intentional Git/npm command execution, the Socket.dev shell access warning, and the no-shell-interpolation command pattern.
• Packaging: Marked the CLI entry point as executable for local and global installs.

1.2.7

• Improved the no-argument error to show the required repository URL and usage help.

1.2.6

• Added -v / --version and -h / --help flags.

1.2.5

• Security: Git and npm commands now run without shell interpolation, so shell metacharacters in repository URLs or target directories are treated as literal argument text.
• Documentation: --install-deps is called out as trust-sensitive because npm install scripts can execute code from cloned repositories.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Issues

If you encounter any problems or have suggestions for improvements, please open an issue on the GitHub repository.