> ## 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 code before commits with [SCANOSS pre-commit hooks](https://github.com/scanoss/pre-commit-hooks), ensuring transparency and compliance are built directly into your workflow.

The SCANOSS pre-commit hook runs just before your changes are committed, triggering automated checks to detect undeclared open-source components. This shift-left approach helps catch compliance issues early in the development process.

## 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 your `scanoss.json` declarations
3. Blocks the commit if undeclared components are found

### Example Output

```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 Software:
┌──────────────┬─────────┬────────────┬─────────┬──────────────┬──────────────┐
│ 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.
```

The commit is blocked until you either:

1. Declare the components in `scanoss.json`
2. Run [`scanoss-cc`](/en/latest/poc/license-dataset/snippet-detection/scanoss-cc) in the terminal to review and declare the components
3. Remove the problematic 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']
```