Skip to content
Arashi logoArashi

init Command

What It’s For

Section titled “What It’s For”

Set up a workspace so Arashi can track repositories and worktrees.

What It Does

Section titled “What It Does”
  • Creates Arashi configuration in the current project.
  • Offers to bootstrap a Git repository when you run it from a non-repository directory in an interactive terminal.
  • Prepares workspace metadata used by other commands.
  • Makes the workspace ready for repository registration.
  • Reconciles safe configured repository and worktree paths with Git before creating managed directories.

Usage

Section titled “Usage”
Terminal window
arashi init [options]

Key Options

Section titled “Key Options”
  • --repos-dir <path> set a custom repos directory (default ./repos).
  • --worktrees-dir <path> set a custom worktree base directory (default .arashi/worktrees).
  • --ignore-scope <local|tracked|none> choose repository-local rules, tracked rules, or no ignore-file writes.
  • --force overwrite an existing Arashi config (with backup).
  • --no-discover skip automatic repository discovery.
  • --dry-run preview changes without writing files.
  • --verbose print detailed initialization steps.
  • --json output machine-readable initialization results.
  • --zero-config bootstrap the root .worktrees/ convention for ad hoc use in a non-bare Git project that has not adopted Arashi configuration.

Examples

Section titled “Examples”
Terminal window
# Standard initialization
arashi init


# Share missing managed rules in the workspace-root .gitignore
arashi init --ignore-scope tracked


# Manage ignore rules manually and receive warnings for unignored paths
arashi init --ignore-scope none


# Reset an existing clone to the repository-local default without --force
arashi init --ignore-scope local


# Run from a parent directory, then enter '.' at the prompt to initialize the current directory
arashi init


# Run from a parent directory, then enter 'my-arashi-repo' at the prompt to create a child repo
arashi init


# Use a custom repositories directory
arashi init --repos-dir ../workspace-repos


# Use a custom worktree base directory
arashi init --worktrees-dir ../workspace-worktrees


# Reinitialize safely and preview file changes
arashi init --force --dry-run


# Initialize and emit JSON for automation
arashi init --json


# Use Arashi ad hoc in a project without persisted Arashi configuration
arashi init --zero-config


# Preview the standalone bootstrap as structured output
arashi init --zero-config --dry-run --json

Notes

Section titled “Notes”
  • Run this command inside an existing Git repository root, or from a parent directory in an interactive terminal when you want Arashi to create the repository for you.
  • In bootstrap mode, the repository target prompt accepts only . or a direct child directory name such as my-arashi-repo.
  • If init is run outside a Git repository without an interactive terminal, it exits with guidance instead of prompting.
  • JSON mode does not prompt; provide explicit options when running initialization from automation.
  • init creates .arashi/config.json and hook templates under .arashi/hooks/.
  • init sets worktreesDir to .arashi/worktrees by default.
  • local is the default ignore scope. Missing safe reposDir and worktreesDir rules are written to the common repository’s exclude file resolved through Git, normally .git/info/exclude; tracked .gitignore is unchanged.
  • tracked writes missing safe rules to the workspace-root .gitignore. none does not write tracked, local, or global ignore files and warns when a safe path remains unignored.
  • Explicit tracked and none choices are stored as arashi.ignoreScope in clone-local Git configuration, not shared .arashi/config.json. Selecting local removes the stored non-default preference.
  • On an existing valid workspace, supplying only --ignore-scope updates the preference and reconciles current paths without requiring --force or recreating config, hooks, or repositories. A forced init with no explicit scope preserves a valid stored preference.
  • Before writing, Arashi asks Git for each path’s effective ignore rule. Existing tracked, repository-local, nested, or global rules are preserved without duplication regardless of the selected scope.
  • Arashi never creates or modifies core.excludesFile or other global Git configuration.
  • Only normalized repository-relative subdirectories are safe to write. Repository root (././), absolute paths, and parent traversal (../ variants) are reported and skipped.
  • Reconciliation updates only Arashi-owned ignore blocks and removes stale owned entries in the active writable scope. User-authored rules remain untouched; none freezes existing ignore content.
  • --dry-run includes planned scope, preference, and ignore changes without modifying them. JSON results expose effective sources, planned or applied rules, warnings, unsafe skips, and final changed/restored state under structured managed ignore data.
  • Prefer ordinary arashi init whenever the project can adopt Arashi, including single-repository projects that benefit from repository/workspace hooks, persisted defaults, or custom paths.
  • --zero-config creates the main-root .worktrees/ directory and adds the literal .worktrees/ rule to the Git-resolved repository-local exclude only when no effective tracked, local, or global rule already covers the bootstrap probe. It is an ad hoc path for otherwise-unconfigured projects and never writes tracked or global ignore state, .arashi/, hooks, or config.
  • Zero-config mode accepts --dry-run, --verbose, and --json; it rejects configured-init options such as --repos-dir, --worktrees-dir, --ignore-scope, --force, and --no-discover before mutation.
  • Use the Standalone Repository workflow for lifecycle scope, exact-destination ignore checks, and upgrading through ordinary arashi init.
Section titled “Related Commands”