no-push-oops

Getting Started

InstallationSetup

Overview

Prevent "oops" moments by running preflight checks before every Git push

A lightweight, configurable Git pre-push hook that automatically runs your quality checks (tests, linting, type-checking, etc.) before allowing a push to go through.

Features

  • Zero Configuration - Works out of the box with sensible defaults
  • Highly Configurable - Customize commands, messages, and behavior
  • Auto-Installation - Automatically sets up Git hooks on install
  • Beautiful Output - Color-coded, clean terminal output
  • Timeout Support - Prevent hung processes
  • Branch-Specific - Skip checks on specific branches
  • CI-Aware - Automatically skips in CI environments
  • TypeScript Support - Fully typed for better DX

Installation

Install no-push-oops as a dev dependency in your project:

# npm
npm install --save-dev no-push-oops

# yarn
yarn add -D no-push-oops

# pnpm
pnpm add -D no-push-oops

Manual Hook Installation

If the hook isn't installed automatically, run:

npx no-push-oops install

Quick Start

  1. Install the package:
# Choose your package manager
npm install --save-dev no-push-oops
# or
yarn add -D no-push-oops
# or
pnpm add -D no-push-oops
  1. Add configuration to your package.json:
{
  "no-push-oops": {
    "command": "npm run pr-preflight"
  },
  "scripts": {
    "pr-preflight": "npm run lint && npm run test && npm run build"
  }
}
  1. That's it! Now every time you push, your preflight checks will run automatically.

Configuration

ConfigurationSetup

Configuration Methods

You can configure no-push-oops in three ways:

1. In package.json:

{
  "no-push-oops": {
    "command": "npm run pr-preflight",
    "message": "Running quality checks...",
    "skipCI": true,
    "skipOnBranches": ["main", "develop"],
    "verbose": false,
    "timeout": 300000
  }
}

2. In .nopushoopsrc.json:

{
  "command": "npm run pr-preflight",
  "message": "Running quality checks...",
  "skipCI": true
}

3. In .nopushoopsrc:

{
  "command": "npm run pr-preflight"
}

Configuration Options

OptionTypeDefaultDescription
commandstring"npm run pr-preflight"Single command to run
commandsstring[]-Multiple commands to run in sequence
messagestring"Running pr-preflight checks before push"Custom message to display
skipCIbooleantrueSkip checks in CI environments
skipOnBranchesstring[][]Branches to skip checks on
verbosebooleanfalseShow detailed output
timeoutnumber300000Command timeout in milliseconds

Usage & Examples

UsageExamples

Usage

Once installed, no-push-oops will automatically run on every git push. If the checks fail, the push will be aborted.

Manual Run

You can manually run the checks:

npx no-push-oops run

Bypass Hook (Emergency Only)

If you need to bypass the hook (not recommended):

git push --no-verify

Uninstall

To remove the hook:

npx no-push-oops uninstall

Common Use Cases

Basic Linting and Testing

{
  "no-push-oops": {
    "command": "npm run lint && npm run test"
  }
}

Full CI Pipeline

{
  "no-push-oops": {
    "commands": [
      "npm run lint",
      "npm run test:unit",
      "npm run test:integration",
      "npm run type-check",
      "npm run build"
    ],
    "message": "Running full CI pipeline...",
    "timeout": 600000
  }
}

Skip on Main Branch

{
  "no-push-oops": {
    "command": "npm run validate",
    "skipOnBranches": ["main", "master", "production"]
  }
}

Verbose Mode for Debugging

{
  "no-push-oops": {
    "command": "npm run test",
    "verbose": true
  }
}

Comparison & FAQ

ComparisonFAQ

Comparison with Other Tools

Featureno-push-oopshuskypre-commit
Zero configYesNoNo
TypeScriptYesNoNo
Pre-push focusYesNoNo
Auto-installYesYesYes
Branch filteringYesNoYes
Timeout supportYesNoYes

Why choose no-push-oops?

  • Focused on pre-push - Specifically designed for running checks before pushing
  • Zero configuration - Works out of the box with sensible defaults
  • TypeScript-first - Fully typed API for better developer experience
  • Simple and lightweight - Does one thing well without unnecessary complexity

API Reference

APIAdvanced

Programmatic Usage

You can use no-push-oops programmatically in your Node.js scripts:

import { 
  loadConfig, 
  runPreflightChecks, 
  installHook, 
  uninstallHook 
} from 'no-push-oops';

// Load configuration
const config = loadConfig();

// Run preflight checks
const success = await runPreflightChecks(config);

// Install/uninstall hooks programmatically
installHook();
uninstallHook();

API Functions

TypeScript Types

export interface NoPushOopsConfig {
  command?: string;
  commands?: string[];
  message?: string;
  skipCI?: boolean;
  skipOnBranches?: string[];
  verbose?: boolean;
  timeout?: number;
}

export interface CommandResult {
  success: boolean;
  exitCode: number;
  command: string;
  output?: string;
  error?: string;
}

Example: Custom Pre-Push Script

import { 
  loadConfig, 
  runPreflightChecks, 
  isCI, 
  getCurrentBranch 
} from 'no-push-oops';

async function customPrePush() {
  const config = loadConfig();
  
  // Skip in CI
  if (config.skipCI && isCI()) {
    console.log('Skipping in CI environment');
    return true;
  }
  
  // Skip on specific branches
  const branch = getCurrentBranch();
  if (branch && config.skipOnBranches?.includes(branch)) {
    console.log(`Skipping on branch: ${branch}`);
    return true;
  }
  
  // Run checks
  return await runPreflightChecks(config);
}

customPrePush().then(success => {
  process.exit(success ? 0 : 1);
});