Metadata-Version: 2.4
Name: githooklib
Version: 0.1.1
Summary: A Python framework (and CLI) for creating, managing, and installing Git hooks with python
Author-email: danielnachumdev <danielnachumdev@gmail.com>
License: MIT License
        
        Copyright (c) 2022 danielnachumdev
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/danielnachumdev/githooklib
Project-URL: Bug Tracker, https://github.com/danielnachumdev/githooklib/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.8.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fire
Dynamic: license-file

# githooklib

A Python framework for creating, managing, and installing Git hooks with automatic discovery and CLI tools.

## Installation

```bash
pip install githooklib
```

## Quick Start

### 1. Create a Hook

Create a hook by subclassing `GitHook` in a `githooks/` directory:

```python
# githooks/pre_commit.py
from githooklib import GitHook, HookResult, GitHookContext


class PreCommitHook(GitHook):
    @property
    def hook_name(self) -> str:
        return "pre-commit"

    def execute(self, context: GitHookContext) -> HookResult:
        self.logger.info("Running pre-commit checks...")
        result = self.command_executor.run(["python", "-m", "pytest"])
        if not result.success:
            return HookResult(
                success=False,
                message="Tests failed. Commit aborted.",
                exit_code=1
            )
        return HookResult(success=True, message="All checks passed!")
```

### 2. Install the Hook

```bash
githooklib install pre-commit
```

### 3. Seed Example Hooks

```bash
githooklib seed                    # List available examples
githooklib seed pre_commit_black   # Seed an example
```

## CLI Commands

```bash
githooklib list                    # List available hooks
githooklib show                    # Show installed hooks
githooklib install <hook-name>     # Install a hook
githooklib uninstall <hook-name>   # Uninstall a hook
githooklib run <hook-name>         # Run a hook manually
githooklib run <hook-name> --debug # Run with debug logging
githooklib seed [example-name]     # Seed example hooks
```

## API Reference

### GitHook

Base class for all Git hooks. Subclass and implement:

- `hook_name` (property): The name of the Git hook (e.g., "pre-commit", "pre-push")
- `execute(context: GitHookContext) -> HookResult`: Your hook logic

Available attributes:
- `logger`: Logger instance for logging messages
- `command_executor`: CommandExecutor instance for running shell commands

### GitHookContext

Provides context when a hook is executed:

- `hook_name`: The name of the hook being executed
- `stdin_lines`: List of lines from stdin
- `project_root`: Path to the project root
- `get_stdin_line(index: int, default: Optional[str]) -> Optional[str]`: Get a specific line from stdin
- `has_stdin() -> bool`: Check if stdin contains data

### HookResult

Return value from `execute()`:

- `success`: Whether the hook passed (bool)
- `message`: Optional message to display (str)
- `exit_code`: Exit code (0 for success, non-zero for failure)

## Requirements

- Python 3.8+

## License

See LICENSE file for details.

## Homepage

https://github.com/danielnachumdev/githooklib
