From 95c2e5126a264333ccad4111f7f8340e050ba401 Mon Sep 17 00:00:00 2001
From: Jax Young <jaxvanyang@gmail.com>
Date: Fri, 7 Jun 2024 15:00:15 +0800
Subject: [PATCH] docs(README): add project information & examples

---
 README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/README.md b/README.md
index 3f373dc..d1c2660 100644
--- a/README.md
+++ b/README.md
@@ -7,4 +7,71 @@
 [![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)
 [![Flake8: checked](https://img.shields.io/badge/flake8-checked-blueviolet)](https://flake8.pycqa.org)
 
+[![PyPI - Version](https://img.shields.io/pypi/v/batchlink)](https://pypi.org/project/batchlink)
+
 Batch link files without modifying original files.
+
+## Why
+
+To solve the problem - [Is there a way to rename files from a torrent and still be able to seed?](https://www.reddit.com/r/qBittorrent/comments/ie3p10/is_there_a_way_to_rename_files_from_a_torrent_and)
+If you are serving BT files on a media server like [Jellyfin](https://jellyfin.org), you
+may want this.
+
+## Features
+
+- A CLI to easily batch link, rename, copy files.
+- An extensible library.
+
+## Examples
+
+Create example files:
+
+```bash
+mkdir -p a b && touch a/0.log a/1.log a/1.txt a/2.txt
+```
+
+Create hard links in `b/` pointing to all files in `a/` with original file names:
+
+> [!NOTE]
+> It's recommended to add option `--dry-run` to see what will happen at first.
+
+```console
+$ batchlink -S a -d b '*' '{path}'
+Create hard link b/0.log to a/0.log
+Create hard link b/1.log to a/1.log
+Create hard link b/1.txt to a/1.txt
+Create hard link b/2.txt to a/2.txt
+```
+
+Only create links for log files:
+
+```console
+$ batchlink -S a -d b '*.log' '{path}'
+Create hard link b/0.log to a/0.log
+Create hard link b/1.log to a/1.log
+```
+
+And rename to one-based numbering file names:
+
+```console
+$ batchlink -S a -d b '*.log' '{num}.log'
+Create hard link b/1.log to a/0.log
+Create hard link b/2.log to a/1.log
+```
+
+Format replacement values:
+
+```console
+$ batchlink -S a -d b '*.log' '{num:02}.log'
+Create hard link b/01.log to a/0.log
+Create hard link b/02.log to a/1.log
+```
+
+Absolute symbolic link, relative symbolic link, rename, copy:
+
+```bash
+batchlink -s -S a -d b '*.log' '{num:02}.log'
+batchlink -sR -S a -d b '*.log' '{num:02}.log'
+batchlink -r -S a -d b '*.log' '{num:02}.log'
+batchlink -c -S a -d b '*.log' '{num:02}.log'
+```