#setup

The rs setup command installs repository-level Git hooks and runs them in the project that invokes the command.

#Usage

rs setup [options]

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

Add rs setup to the prepare script of the project that should manage the repository hooks:

{
  "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 hook scripts, relative to the Git repository root.

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 of the project that manages hooks:

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

To prevent Git hook files from being created or overwritten outside the repository through parent directory paths, the path must not contain ...

#--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        # Repository hook script: edit and commit
    └── _/                # Generated by rs setup; ignored by Git
        ├── .gitignore
        ├── .owner
        ├── runner
        ├── pre-commit
        ├── commit-msg
        └── ...

Files next to _ are repository 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. Before running a hook, it changes to the project that installed the hooks and prepends that project's 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, the project that provides Rstack may be located in a subdirectory such as frontend/. Running rs setup from that directory still installs hooks at the Git repository root:

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

Rstack records frontend as the project that owns the hooks. Hook scripts remain at the repository root, but run from frontend, so they can use its configuration and dependencies without an explicit cd:

rs staged

A Git repository has one hooks owner. Only that project should include rs setup in its prepare script. Calls from another project are skipped with a warning.

To change the owner, remove rs setup from the previous project's prepare script, delete the generated _ directory, and then run rs setup from the new project.

#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.
• If another hooks setup is reported, migrate or remove the conflicting setup before rerunning the command.
• If another Rstack owner is reported, follow the ownership transfer steps in Monorepo.

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.