🚧 FENCE — FENCE Ensures Nothing Crosses Edges

FENCE is a command-line tool that helps you ensure that your code changes do not exceed a specified line limit when compared to a base branch. It is particularly useful for maintaining code quality and preventing large, unwieldy pull requests.

Index

• ▶️ Quick Demonstration
• 📦 Installation
• 🚀 Usage
  • Examples
  • Customizing Messages
  • Reporting Issues
• ⚙️ Persisting Configuration
• 🧩 GitHub Action
  • ✅ Basic usage
  • ⚙️ Customizing the action
• 🔄 Uninstalling
• 📄 License

▶️ Quick Demonstration

fence-demonstration.mov

📦 Installation

macOS and Linux

curl -sSL https://raw.githubusercontent.com/nascjoao/fence/main/install.sh | sh

🚀 Usage

fence [base-branch] [options]

Options

Flag	Description
-b, --bug-report	Open GitHub issue template for bug reports
-c, --install-completion	Install shell autocomplete for FENCE
-f, --fail <message>	Customize fail message (use {total} and {limit})
-g, --suggest	Open GitHub issue template for suggestions
-h, --help	Show this help message
-i, --ignore <patterns>	Exclude files or folders from diff (space-separated)
-k, --skip-update	Skip update check
-l, --limit <number>	Set max allowed modified lines (default: 250)
-n, --remote-name <name>	Specify remote name (default: 'origin')
-r, --remote	Compare against remote branch (e.g., origin/main)
-s, --success <message>	Customize success message (use {total} and {limit})
-u, --update	Check for updates
-v, --version	Show installed version

Important: Default branch

If no base branch is specified, fence assumes main by default.

Remote mode (-r | --remote)

When -r is provided, fence compares your current local branch against its remote counterpart (e.g., origin/main or origin/feature-branch).

• Without -r: compares changes against the specified or default local branch.
• With -r: compares changes against the remote tracking branch.

You can set the remote name with -n or --remote-name (default is origin):

fence -r -n upstream

Or set it via the environment variable:

export FENCE_REMOTE_NAME=upstream

Examples

fence                          # Compares with `main` branch within the default limit: 250
fence develop                  # Compares with `develop` branch within the default limit
fence develop -l 100           # Sets custom limit
fence -r                       # Compares against origin/main
fence develop -r              # Compares against origin/develop
fence -b                       # Opens GitHub issue to report a bug
fence -g                       # Opens GitHub issue to suggest an idea
fence -i node_modules dist/    # Ignores specific paths during diff

FENCE also ignores common lockfiles by default (e.g., package-lock.json, yarn.lock, pnpm-lock.yaml).

Customizing Messages

fence \
  -s "✅ All good: {total} lines changed, within {limit}" \
  -f "❌ Too many changes: {total} lines, max allowed is {limit}"

Reporting Issues

FENCE makes it easy to contribute feedback:

• Run fence -b to open a bug report template with system info prefilled.
• Run fence -g to open a suggestion template to propose improvements.

⚙️ Persisting Configuration

Set environment variables to define defaults:

export FENCE_SUCCESS="✅ Inside limit! {total} lines, limit is {limit}"
export FENCE_FAIL="❌ Over the limit! {total} lines, limit is {limit}"
export FENCE_LIMIT=300
export FENCE_DEFAULT_BRANCH="develop"
export FENCE_REMOTE_NAME="upstream"

To persist these across terminal sessions, add them to your shell config (e.g., ~/.bashrc, ~/.zshrc):

echo 'export FENCE_LIMIT=300' >> ~/.zshrc

🧩 GitHub Action

You can use FENCE to block large PRs in GitHub Actions.

✅ Basic usage

.github/workflows/fence.yml:

name: FENCE

on:
  pull_request:

jobs:
  check-size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run FENCE
        uses: nascjoao/fence@v0

⚙️ Customizing the action

      - name: Run FENCE with custom messages
        uses: nascjoao/fence@v0
        with:
          base_branch: develop
          limit: 100
          success_msg: "✅ Within limit: {total} modified lines."
          fail_msg: "❌ Too many changes! Limit is {limit}, but found {total}."

🔄 Uninstalling

curl -sSL https://raw.githubusercontent.com/nascjoao/fence/main/uninstall.sh | sh

📄 License

This project is licensed under the MIT License.