Metadata-Version: 2.4
Name: eof-fixer
Version: 0.5.0
Summary: CLI tool that ensures text files end with exactly one newline
Keywords: cli,pre-commit,formatter,newline,eof,linter,python
Author: modern-python
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
Requires-Dist: pathspec>=0.12
Requires-Python: >=3.11, <4
Project-URL: Homepage, https://modern-python.org
Project-URL: Repository, https://github.com/modern-python/eof-fixer
Project-URL: Issues, https://github.com/modern-python/eof-fixer/issues
Project-URL: Changelog, https://github.com/modern-python/eof-fixer/releases
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)"  srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/eof-fixer/lockup-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/eof-fixer/lockup-light.svg">
    <img alt="eof-fixer" src="https://raw.githubusercontent.com/modern-python/.github/main/brand/projects/eof-fixer/lockup.png" width="420">
  </picture>
</p>

[![PyPI version](https://img.shields.io/pypi/v/eof-fixer.svg)](https://pypi.org/project/eof-fixer/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/eof-fixer.svg)](https://pypi.org/project/eof-fixer/)
[![Downloads](https://static.pepy.tech/badge/eof-fixer/month)](https://pepy.tech/projects/eof-fixer)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/eof-fixer/actions/workflows/ci.yml)
[![CI](https://github.com/modern-python/eof-fixer/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/eof-fixer/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/modern-python/eof-fixer.svg)](https://github.com/modern-python/eof-fixer/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/modern-python/eof-fixer)](https://github.com/modern-python/eof-fixer/stargazers)
[![Context7](https://img.shields.io/badge/Context7-docs-blue)](https://context7.com/modern-python/eof-fixer)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)

A command-line tool that ensures all your text files end with exactly one newline character.
This tool helps maintain consistent file formatting across your codebase by automatically adding or removing trailing newlines as needed.

## Why this matters

Many POSIX systems expect text files to end with a newline character. Having consistent line endings:
- Prevents spurious diffs in version control
- Ensures proper concatenation of files
- Matches the POSIX definition of a text line
- Improves readability in terminal environments

## Features

- Automatically adds a newline to files that don't end with one
- Removes excess trailing newlines from files that have too many
- Respects nested `.gitignore` files throughout the tree to avoid processing unwanted files
- Skip extra paths with the repeatable `--exclude` flag
- Works with all text file types
- Cross-platform compatibility (Windows, macOS, Linux)
- Check mode (`--check`) to preview changes before applying them

## Installation

### Using uv

```bash
uv tool install eof-fixer
```

Or run it once without installing:

```bash
uvx eof-fixer .
```

### Using pip

```bash
pip install eof-fixer
```

## Usage

### Basic usage

The path argument must be a directory. To fix all files in the current directory and subdirectories:

```bash
eof-fixer .
```

To check which files would be modified without making changes:

```bash
eof-fixer . --check
```

To skip extra directories on top of the defaults, pass `--exclude` (repeatable):

```bash
eof-fixer . --exclude node_modules --exclude dist
```

## How it works

The eof-fixer processes files in the following way:

1. A file with no trailing newline gets exactly one newline appended.
2. A file with exactly one trailing newline is left unchanged.
3. A file with multiple trailing newlines is truncated to exactly one newline.
4. A file containing only newlines is truncated to empty.
5. An empty file is left unchanged.

### Examples

| Original file content | After processing |
|-----------------------|------------------|
| `hello world`         | `hello world\n`  |
| `hello world\n`       | `hello world\n`  |
| `hello world\n\n\n`   | `hello world\n`  |
| `\n\n\n`              | (empty file)     |
| (empty file)          | (unchanged)      |

> **Note on line endings:** when appending a missing terminator, eof-fixer always
> writes an LF (`\n`), regardless of the existing line-ending style of the file.
> A file that otherwise uses CRLF or CR will end up with a mixed terminator on
> its last line. This matches the behavior of pre-commit's `end-of-file-fixer`.
> Files that already end with a single CRLF, CR, or LF are left untouched.

## Configuration

The tool respects your `.gitignore` files, so it won't process files that are ignored by Git. It honors the full nested convention: the `.gitignore` at the root **and** any `.gitignore` files in subdirectories, with Git precedence: deeper files override shallower ones, and `!` negations re-include. Ignore resolution is pure-filesystem: `.git/info/exclude` and the global `core.excludesFile` are not consulted, and Git itself is never invoked, so the tool works on any directory, repository or not.

It also skips:
- `.git` directories (always, not configurable)
- `.cache` and `.uv-cache` directories (used by uv) by default; pass `--exclude DIR` (repeatable) to add more names to skip on top of these
- Binary files (detected by null bytes in the first 1024 bytes)

## Exit codes

- `0`: No files needed fixing.
- `1`: At least one file needed fixing. In `--check` mode no changes are written;
  in the default (fix) mode the files have been rewritten in place. The non-zero
  exit in fix mode is intentional so the tool can be used as a CI gate. A second
  run exits `0`.
- `2`: Usage error, including a path that is not a directory.

## Development

### Prerequisites

- [uv](https://docs.astral.sh/uv/) for dependency management

### Setup

```bash
# Clone the repository
git clone https://github.com/modern-python/eof-fixer.git
cd eof-fixer

# Install dependencies
just install
```

### Running tests

```bash
# Run tests
just test
```

### Linting

```bash
# Run linting and formatting
just lint
```

## Contributing

Fork the repository, make your change on a branch, run `just lint` and `just test`, and open a pull request.

## Acknowledgments

The core file-fixing logic in this project is derived from the
[`end-of-file-fixer`](https://github.com/pre-commit/pre-commit-hooks/blob/main/pre_commit_hooks/end_of_file_fixer.py)
hook in [`pre-commit/pre-commit-hooks`](https://github.com/pre-commit/pre-commit-hooks),
which is also distributed under the MIT License. This project repackages that
logic as a standalone CLI with `.gitignore`-aware directory traversal so it can
be used outside of the pre-commit framework.

## Related projects

- [pre-commit](https://pre-commit.com/) - A framework for managing and maintaining multi-language pre-commit hooks
- [editorconfig](https://editorconfig.org/) - Helps maintain consistent coding styles across different editors and IDEs

## 📦 [PyPI](https://pypi.org/project/eof-fixer)

## 📝 [License](https://github.com/modern-python/eof-fixer/blob/main/LICENSE)

## Part of `modern-python`

Browse the full list of templates and libraries in
[`modern-python`](https://github.com/modern-python). The org profile has the categorized index.
