BREAKING CHANGE: v0.0.8 -> sort/merge --rename impl + merge preserves unique metadata lines

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chaintools"
-version = "0.0.7"
+version = "0.0.8"
 edition = "2024"
 authors = ["alejandrogzi <alejandrxgzi@gmail.com>"]
 license = "MIT"

README.md

@@ -10,8 +10,8 @@
   </span>
 
   <p align="center">
-    <a href="https://img.shields.io/badge/version-0.0.7-green" target="_blank">
-      <img alt="Version Badge" src="https://img.shields.io/badge/version-0.0.7-green">
+    <a href="https://img.shields.io/badge/version-0.0.8-green" target="_blank">
+      <img alt="Version Badge" src="https://img.shields.io/badge/version-0.0.8-green">
     </a>
     <a href="https://crates.io/crates/chaintools" target="_blank">
       <img alt="Crates.io Version" src="https://img.shields.io/crates/v/chaintools">
@@ -29,7 +29,7 @@
         <span>work with .chain files in Rust</span>
         <br>
         <br>
-        <a href="https://docs.rs/chaintools/0.0.7/chaintools/">docs</a> .
+        <a href="https://docs.rs/chaintools/0.0.8/chaintools/">docs</a> .
         <a href="https://github.com/alejandrogzi/chaintools/tree/master/assets/usage/usage.md">usage</a> .
         <a href="https://github.com/alejandrogzi/chaintools/tree/master/assets/tools">tools</a> .
         <a href="https://genome.ucsc.edu/goldenpath/help/chain.html">chains</a> 
@@ -60,7 +60,7 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-chaintools = { version = "0.0.7", features = ["mmap", "gzip", "parallel"] }
+chaintools = { version = "0.0.8", features = ["mmap", "gzip", "parallel"] }
 ```
 ## Benchmarks
 

assets/changelog/Changelog.md

@@ -5,6 +5,32 @@ All notable changes to **chaintools** are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.8] - 2025-06-13
+
+### Added
+
+- **`--rename`/`-r` flag for `merge`** — `chaintools merge --rename` reassigns chain
+  IDs sequentially in sorted output order, so the first emitted chain receives
+  `id 1`, the next `2`, and so on. The flag implies sorting: it defaults to
+  `--sort-by score` when no key is given, and respects an explicit `--sort-by <KEY>`
+  when one is provided. Renaming is applied at final emission for both the in-memory
+  and external (spill-to-disk) merge paths, with no extra pass over the data. Backed
+  by new `write_chain_dense_with_id` / `write_chain_header_with_id` writer helpers.
+
+- **`--rename`/`-r` flag for `sort`** — `chaintools sort --rename` reassigns chain
+  IDs sequentially in sorted output order, following the selected `--sort-by` key
+  (default `score`). When combined with `--out-index`, the recorded offsets are
+  computed against the renamed output so they remain consistent with the written
+  bytes.
+
+### Changed
+
+- **`merge` deduplicates metadata** — when merging with `--sort-by`/`--rename`,
+  identical metadata (`#`) lines that appear in more than one input (for example,
+  files produced by a previous `split`) are now emitted once, in first-seen order.
+  Deduplication is performed at the byte level and does not affect `sort`, which
+  continues to preserve a single input's metadata verbatim.
+
 ## [0.0.7] - 2026-06-11
 
 ### Added

assets/tools/merge.md

@@ -42,8 +42,14 @@ Sorting:
 - no `--sort-by`: merge input text in input order without reparsing
 - `--sort-by score|id|reference|query`: parse all inputs, sort deterministically, and write canonical chain text
 
+Renaming:
+- `--rename`/`-r`: reassign chain IDs sequentially in sorted output order, so the first emitted chain gets `id 1`, the next `2`, and so on
+- `--rename` implies sorting: it defaults to `--sort-by score` when no key is given, and respects an explicit `--sort-by <KEY>` when one is provided
+- renaming is applied only to the final sorted output (both the in-memory and external-merge paths); original IDs are otherwise preserved
+
 Notes:
 - `reference` is the target/reference-name sort used elsewhere as target sort
 - unsorted merge preserves input text order and only inserts record separators when needed between files
 - sorted merge preserves metadata lines, then emits sorted chains
+- sorted merge deduplicates metadata lines at the byte level: an identical metadata line appearing in more than one input (e.g. files produced by a previous split) is emitted once, in first-seen order
 - `--max-gb <GB>` controls the in-memory working set for sorted merge and defaults to `8`

assets/tools/sort.md

@@ -53,6 +53,14 @@ Sort chain records from a chain file or standard input.
 - `--max-gb <GB>`: spill sorted runs to temporary files when the in-memory
   working set grows past this limit. The default is `8`.
 
+## Renaming
+
+- `--rename`/`-r`: reassign chain IDs sequentially in sorted output order, so
+  the first emitted chain gets `id 1`, the next `2`, and so on. The IDs follow
+  the selected `--sort-by` key (default `score`).
+- When combined with `--out-index`, the index offsets are computed against the
+  renamed output, so they stay consistent with the written bytes.
+
 ## Differences from UCSC chainSort / chainMergeSort
 
 - `sort` is the only user-facing sorting command. Large inputs are handled by
@@ -64,8 +72,9 @@ Sort chain records from a chain file or standard input.
   separate UCSC boolean flags.
 - Equal primary keys are normalized to a deterministic order. Ties are broken by
   chain id, then target fields, then query fields, then remaining chain content.
-- The implementation preserves existing chain ids. It does not renumber them
-  the way UCSC `chainMergeSort` does by default.
+- The implementation preserves existing chain ids by default. Pass `--rename`
+  to renumber them sequentially in sorted order, similar to UCSC
+  `chainMergeSort`.
 - `--out-index` is not allowed together with `--gzip` because index offsets are
   defined on uncompressed output bytes.
 - Metadata lines beginning with `#` are copied to the beginning of the output in