From 1977d8796519e40da8fa1e2e18353539be4d3e9d Mon Sep 17 00:00:00 2001
From: Mike Gerber <mike@mike-gerber.de>
Date: Wed, 2 Sep 2026 19:41:38 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20a=20README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7c92f52
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# git-annex-duplicates
+
+Find duplicate file paths in a [git-annex](https://git-annex.branchable.com/)
+repository.
+
+`git-annex-duplicates` groups files by their annex key and prints every group
+that contains more than one path. It is read-only: it reports duplicates but
+does not remove or otherwise modify any files.
+
+
+## Requirements
+
+- git-annex
+- Python 3.11 or newer
+- [uv](https://docs.astral.sh/uv/) (recommended for installation)
+
+
+## Installation
+
+Install the command directly from the Git repository:
+
+```sh
+uv tool install "git+https://cvs.moegen-wir.net/mikegerber/git-annex-duplicates.git"
+```
+
+Alternatively, run it from a checkout:
+
+```sh
+git clone https://cvs.moegen-wir.net/mikegerber/git-annex-duplicates.git
+cd git-annex-duplicates
+uv run git-annex-duplicates --help
+```
+
+
+## Usage
+
+Run the command from inside a git-annex repository:
+
+```sh
+git-annex-duplicates
+```
+
+The output contains one group of duplicate paths at a time, with groups
+separated by a blank line:
+
+```text
+photos/holiday.jpg
+backup/holiday.jpg
+
+documents/report.pdf
+archive/report-final.pdf
+```
+
+Exclude one or more path patterns with `--exclude`:
+
+```sh
+git-annex-duplicates --exclude '*.iso' --exclude 'archive/**'
+```
+
+Additional arguments are passed to `git annex find`. Place `--` before options
+that belong to `git annex find`, so they are not interpreted as options to
+`git-annex-duplicates`:
+
+```sh
+# Only report duplicates whose content is present in this repository
+git-annex-duplicates -- --in=here
+
+# Combine a local exclusion with a git-annex find option
+git-annex-duplicates --exclude 'archive/**' -- --in=here
+```
+
+See `git annex find --help` for the available filters.
+
+
+## How it works
+
+The command runs `git annex find`, requests each file's annex key, groups the
+returned paths by that key, and prints groups containing at least two paths.
+Files with the same annex key refer to the same content as far as git-annex is
+concerned.
+
+Only annexed files are considered. Regular Git files and untracked files are
+not included, and file content does not need to be downloaded to produce the
+report.