Skip to main content
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

pip install pre-commit

​
Getting Started

​
Configure the Hook

Create .pre-commit-config.yaml at the root of your repository: 
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

pre-commit validate-config

​
Install the Hook

pre-commit install

​
Test the Hook

# 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: 
# .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: 
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

$ 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 in the terminal to review and declare the components
  3. Remove the problematic code

​
Troubleshooting

​
Enable Debug Mode

Method 1: Environment Variable 
export SCANOSS_DEBUG=true
git commit -m "test"
Method 2: .env File 
# .env
SCANOSS_DEBUG=true
Method 3: Command-Line Argument 
repos:
- repo: https://github.com/scanoss/pre-commit-hooks
  rev: v0.4.0
  hooks:
    - id: scanoss-check-undeclared-code
      args: ['--debug']