#setup

The rs setup command installs project-local Git hooks in the current repository.

#Usage

rs setup [options]

By default, project hook scripts are stored in .rstack/hooks. If the current directory is not inside a Git repository, the command skips installation.

Add rs setup to the prepare script in the root package.json to automatically generate hook files when dependencies are installed:

{
  "scripts": {
    "prepare": "rs setup"
  }
}

Run the script once to generate the hook files:

npm run prepare

yarn run prepare

pnpm run prepare

bun run prepare

For example, create a pre-commit hook that runs rs staged:

rs staged

#Options

#--hooks-dir

Sets the directory for project hook scripts, relative to the current directory.

rs setup --hooks-dir config/git-hooks

# Quote paths that contain spaces
rs setup --hooks-dir "config/git hooks"

When using a custom directory, add the full command to the prepare script in the root package.json:

{
  "scripts": {
    "prepare": "rs setup --hooks-dir config/git-hooks"
  }
}

#--help

--help (or -h) displays the command's usage and options.

rs setup --help

#Hook files

The default directory structure is:

.rstack/
└── hooks/
    ├── pre-commit        # Project hook script: edit and commit
    └── _/                # Generated by rs setup; ignored by Git
        ├── .gitignore
        ├── runner
        ├── pre-commit
        ├── commit-msg
        └── ...

Files next to _ are project hook scripts. The _ directory contains generated files and is ignored by Git. rs setup points core.hooksPath to .rstack/hooks/_; rerun it after cloning the repository or when generated files are missing.

#Supported hooks

Rstack supports these client-side Git hooks:

• pre-commit
• pre-merge-commit
• prepare-commit-msg
• commit-msg
• post-commit
• applypatch-msg
• pre-applypatch
• post-applypatch
• pre-rebase
• post-rewrite
• post-checkout
• post-merge
• pre-push
• pre-auto-gc

Create a file with the matching name next to the _ directory.

#Hook runtime

Rstack runs hook scripts with POSIX sh -e, forwards Git's arguments and standard input, and returns the hook's exit code. It also prepends node_modules/.bin to PATH.

#Disable and debug

Set RSTACK_HOOKS=0 to skip installation or hook execution:

RSTACK_HOOKS=0 git commit -m "Skip hooks"

Set RSTACK_HOOKS=2 to trace Rstack's hook runtime, including how it invokes the hook script and handles its exit code; to trace commands inside the hook script, add set -x to the script:

RSTACK_HOOKS=2 git commit -m "Trace hooks"

#Configure the hook environment

Before running a hook script, Rstack loads this optional POSIX shell file:

${XDG_CONFIG_HOME:-$HOME/.config}/rstack/hooks-init.sh

Use it to initialize a Node.js version manager, update PATH, or set RSTACK_HOOKS=0 for the current user.

#Monorepo

In a monorepo, a project may be located in a Git repository subdirectory, such as frontend/. When run from that directory, rs setup creates the hooks directory relative to the project and includes the project path in core.hooksPath:

frontend/.rstack/hooks/
frontend/.rstack/hooks/_/
core.hooksPath=frontend/.rstack/hooks/_

Git runs hooks from the repository root. If the project is in a subdirectory, change to that directory in the hook script before running project commands:

cd frontend
pnpm test

A Git repository has one core.hooksPath, so choose either the repository root or one subproject to manage hooks.

#Remove hooks

To remove Rstack-managed hooks:

1. Remove rs setup from the prepare script.

2. Unset the repository's hooks path:

   git config --local --unset core.hooksPath

3. Delete .rstack/hooks/, or the directory passed to --hooks-dir.

#Troubleshooting

#Hook does not run

• Check that the hook script has a supported name and is next to the _ directory.
• Run git config --local --get core.hooksPath and verify the configured path.
• Rerun rs setup to restore generated files and executable permissions.
• Check that RSTACK_HOOKS is not set to 0 in the environment or initialization file.

Hook scripts do not need to be executable because Rstack runs them with sh.

#Command not found

For exit code 127, Rstack prints the effective PATH. If a GUI Git client cannot find Node.js or the package manager, initialize them in hooks-init.sh.

#Windows and Yarn

On Windows, hooks run in the POSIX shell included with Git for Windows. Use LF line endings and / path separators in hooks.

Yarn PnP does not provide node_modules/.bin. Run tools through a Yarn script, such as yarn run test, and make Node.js and Yarn available through hooks-init.sh when needed.