> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-Commit Hooks

> Automatically scan your staged files for undeclared open-source components before each commit using SCANOSS pre-commit hooks.

The SCANOSS pre-commit hooks run just before your changes are committed, triggering
automated scans to detect open-source components that have not been declared in your
`scanoss.json` configuration. By catching undeclared components at commit time, issues
are identified early in the development process rather than later in the pipeline.

## Prerequisites

Before you begin, ensure the following are installed and configured:

* [Pre-Commit Framework](https://pre-commit.com/): The framework that manages and
  runs the hooks.
* [SCANOSS Pre-Commit Plugin](https://github.com/scanoss/pre-commit-hooks): The
  SCANOSS hook for detecting undeclared open-source components.
* [SCANOSS Code Compare (`scanoss-cc`)](https://github.com/scanoss/scanoss-cc): A
  CLI tool for reviewing and declaring detected components.
* [SCANOSS Settings (`scanoss.json`)](/en/latest/poc/license-dataset/snippet-detection/scanoss-settings):
  The configuration file in which component declarations are managed. This file must
  exist at the root of your repository before the hook can validate against it.

## Installation

```bash theme={null}
pip install pre-commit
```

## Getting Started

### Configure the Hook

Create `.pre-commit-config.yaml` at the root of your repository:

```yaml theme={null}
repos:
  - repo: https://github.com/scanoss/pre-commit-hooks
    rev: v0.4.0 # Use the latest version from https://github.com/scanoss/pre-commit-hooks/releases
    hooks:
      - id: scanoss-check-undeclared-code
```

### Verify Configuration

```bash theme={null}
pre-commit validate-config
```

### Install the Hook

```bash theme={null}
pre-commit install
```

### Test the Hook

```bash theme={null}
# Stage files to test
git add .

# Run hook against all files
pre-commit run --all-files
```

## Configuration

### Environment Variables

The hook automatically loads variables from a `.env` file in your project root:

```bash theme={null}
# .env
SCANOSS_API_KEY=your_api_key_here
SCANOSS_SCAN_URL=https://api.scanoss.com/scan/direct
HTTPS_PROXY=http://proxy.example.com:8080
SCANOSS_DEBUG=true
```

## How It Works

### Example Workflow

Given this project structure:

```
my-project/
├── src/
│   ├── scanner.py
│   └── utils.c
├── .env
└── .pre-commit-config.yaml
```

When you commit:

```bash theme={null}
git add src/
git commit -m "Add new features"
```

The hook automatically:

1. Scans staged files for open-source components.
2. Compares detected components against the declarations in your `scanoss.json` file.
   A **declaration** is an explicit acknowledgement that a given open-source component
   is present and approved for use in your project.
3. Blocks the commit if any undeclared components are found.

### Example Output

The following is an example of output produced when undeclared components are detected.
File paths and package identifiers are truncated for brevity.

```bash theme={null}
$ git commit -m "updating relevant files"
[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to ~/.cache/pre-commit/patch1763626421-7396.
SCANOSS Undeclared Check.................................................Failed
- hook id: scanoss-check-undeclared-code
- duration: 7.75s
- exit code: 1
- files were modified by this hook

SCANOSS detected 2 files containing potential open-source components:
┌──────────────┬─────────┬────────────┬─────────┬──────────────┬──────────────┐
│ File         │ Status  │ Match Type │ Matched │ Purl         │ License      │
├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤
│ src/copyrig… │ pending │ snippet    │ 95%     │ pkg:github/… │ GPL-2.0-only │
├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤
│ src/scanner… │ pending │ snippet    │ 96%     │ pkg:github/… │ MIT          │
└──────────────┴─────────┴────────────┴─────────┴──────────────┴──────────────┘
Run 'scanoss-cc' in the terminal to view the results in more detail.

[WARNING] Stashed changes conflicted with hook auto-fixes... Rolling back fixes...
[INFO] Restored changes from ~/.cache/pre-commit/patch1763626421-7396.
```

> **Note:** The `files were modified by this hook` message indicates that the hook
> wrote scan result metadata to your working directory as part of its analysis.
> These modifications are rolled back if a conflict with unstaged changes is detected,
> as shown in the output above.

The commit is blocked until you take one of the following actions:

1. Declare the components in `scanoss.json`.
2. Run [`scanoss-cc`](/en/latest/clients/code-compare)
   in the terminal to review and declare the components interactively.
3. Remove the non-compliant or undeclared code.

## Troubleshooting

### Enable Debug Mode

**Method 1: Environment Variable**

```bash theme={null}
export SCANOSS_DEBUG=true
git commit -m "test"
```

**Method 2: `.env` File**

```bash theme={null}
# .env
SCANOSS_DEBUG=true
```

**Method 3: Command-Line Argument**

```yaml theme={null}
repos:
  - repo: https://github.com/scanoss/pre-commit-hooks
    rev: v0.4.0
    hooks:
      - id: scanoss-check-undeclared-code
        args: ["--debug"]
```