docs(website): document range-endpoint options and --dry-run

- usage/args.md: list --dry-run, the four range endpoint options, and a "Range selection" section.
- configuration/git.md: document the `start_at` / `start_after` / `end_at` / `end_before` keys.
- usage/examples.md: examples for the new endpoint options and --dry-run.

Author: cds-amal

website/docs/configuration/git.md

@@ -42,6 +42,12 @@ limit_commits = 42
 recurse_submodules = false
 include_paths = ["src/", "doc/**/*.md"]
 exclude_paths = ["unrelated/"]
+
+# Range selection (optional; mutually exclusive with each other within a pair).
+# start_at    = "v1.0.0"   # include this revision as the lower bound
+# start_after = "v0.9.0"   # exclude this revision; walk forward from its successor
+# end_at      = "v2.0.0"   # include this revision as the upper bound
+# end_before  = "v2.1.0"   # exclude this revision; stop before it
 ```
 
 ### conventional_commits
@@ -373,3 +379,27 @@ This setting takes priority over `include_paths`.
 
 - If a commit touches both included and excluded paths, it **will be included**.
 - If a commit **only** modifies files that match both `include_paths` and `exclude_paths`, it **will be excluded**.
+
+## Range endpoints
+
+Four _optional_ string keys select the commit range explicitly. `start_at` / `start_after` set the lower bound (inclusive / exclusive); `end_at` / `end_before` set the upper bound (inclusive / exclusive). Within each pair, at most one may be set. Any unspecified side falls back to its default (first commit on the left, `HEAD` on the right).
+
+These config keys cannot be combined with the legacy range flags (`--latest`, `--current`, `--unreleased`, `--bump`, positional `A..B`). If a corresponding CLI option is passed, it takes precedence over the config key on the same side.
+
+See the [command-line reference](../usage/args.md#range-selection) for the full surface, including how legacy flags map to endpoint pairs.
+
+### start_at
+
+`start_at` includes the given revision as the lower bound (`[start_at, ...`). The revision itself is part of the output. Any commits before it are excluded.
+
+### start_after
+
+`start_after` excludes the given revision; the walk starts from its successor (`(start_after, ...`). Equivalent to git's `A..` range syntax.
+
+### end_at
+
+`end_at` includes the given revision as the upper bound (`..., end_at]`). The revision itself is part of the output; commits after it are excluded.
+
+### end_before
+
+`end_before` excludes the given revision; the walk stops at its parent (`..., end_before)`). Useful for "everything up to but not including a tag."

website/docs/usage/args.md

@@ -21,6 +21,7 @@ git-cliff [FLAGS] [OPTIONS] [--] [RANGE]
     --topo-order       Sorts the tags topologically
     --use-branch-tags  Include only the tags that belong to the current branch
     --no-exec          Disables the external command execution
+    --dry-run          Prints the computed commit range and exits without rendering
 -x, --context          Prints changelog context as JSON
     --use-native-tls   Load TLS certificates from the native certificate store
 ```
@@ -43,6 +44,10 @@ git-cliff [FLAGS] [OPTIONS] [--] [RANGE]
     --ignore-tags <PATTERN>        Sets the tags to ignore in the changelog [env: GIT_CLIFF_IGNORE_TAGS=]
     --count-tags <PATTERN>         Sets the tags to count in the changelog [env: GIT_CLIFF_COUNT_TAGS=]
     --skip-commit <SHA1>...        Sets commits that will be skipped in the changelog [env: GIT_CLIFF_SKIP_COMMIT=]
+    --start-at <REV>               Include this revision as the lower bound (walk forward from here) [env: GIT_CLIFF_START_AT=]
+    --start-after <REV>            Exclude this revision; start walking forward from its successor [env: GIT_CLIFF_START_AFTER=]
+    --end-at <REV>                 Include this revision as the upper bound (walk back from here) [env: GIT_CLIFF_END_AT=]
+    --end-before <REV>             Exclude this revision; stop walking before reaching it [env: GIT_CLIFF_END_BEFORE=]
 -p, --prepend <PATH>               Prepends entries to the given changelog file [env: GIT_CLIFF_PREPEND=]
 -o, --output [<PATH>]              Writes output to the given file [env: GIT_CLIFF_OUTPUT=]
 -t, --tag <TAG>                    Sets the tag for the latest version [env: GIT_CLIFF_TAG=]
@@ -73,3 +78,48 @@ git-cliff [FLAGS] [OPTIONS] [--] [RANGE]
 ```
 [RANGE]  Sets the commit range to process
 ```
+
+## Range selection
+
+Every git-cliff invocation selects a contiguous slice of history. The flags above are named shortcuts for picking the two endpoints of that slice, with inclusivity baked in. The four `--*-at` / `--*-before` / `--*-after` options make the endpoints (and their inclusivity) explicit.
+
+### New endpoint options
+
+| CLI flag          | Config key          | Meaning                                  |
+| ----------------- | ------------------- | ---------------------------------------- |
+| `--start-at X`    | `start_at = "X"`    | Include `X`; walk forward. `[X, ...`     |
+| `--start-after X` | `start_after = "X"` | Exclude `X`; walk forward. `(X, ...`     |
+| `--end-at Y`      | `end_at = "Y"`      | Include `Y`; walk back. `..., Y]`        |
+| `--end-before Y`  | `end_before = "Y"`  | Exclude `Y`; stop before it. `..., Y)`   |
+
+The naming convention: `*_at` is inclusive, `*_before` / `*_after` is exclusive. Within each pair, at most one may be set. The two pairs are independent, so any inclusivity combination is expressible. Unspecified sides fall back to the existing defaults (left = first commit, right = `HEAD`).
+
+CLI values override config values on the same side, so a shared team config can be locally overridden without editing the file.
+
+### Conflicts
+
+- `--start-at` and `--start-after` cannot be combined; same for `--end-at` and `--end-before`.
+- The new endpoint options cannot be combined with the legacy range flags (`--latest`, `--current`, `--unreleased`, `--bump`, positional `A..B`). Pick one style.
+
+### How legacy flags map to endpoints
+
+| Legacy         | Equivalent endpoint form                              |
+| -------------- | ----------------------------------------------------- |
+| (no flags)     | `--end-at HEAD` (left defaults to first commit)       |
+| `--unreleased` | `--start-after <last_tag> --end-at HEAD`              |
+| `--latest`     | `--start-after <prev_tag> --end-at <last_tag>`        |
+| `--current`    | `--start-after <prev_tag> --end-at <current_tag>`     |
+| `<A>..<B>`     | `--start-after A --end-at B`                          |
+
+### Previewing with `--dry-run`
+
+`--dry-run` prints the computed interval, the number of commits it covers, and the git revision range that will be walked, then exits without rendering a changelog:
+
+```
+$ git cliff --start-at v0.1.0 --end-at v0.2.0 --dry-run
+range:    [v0.1.0, v0.2.0]
+commits:  3
+emitted:  02deb7a7...^..9f14f5d1...
+```
+
+The `range:` line uses the revisions you specified (math-interval notation; `[` / `]` are inclusive, `(` / `)` are exclusive). The `emitted:` line shows the git revision range actually passed to the walker, with revisions resolved to full commit SHAs.

website/docs/usage/examples.md

@@ -45,6 +45,37 @@ git cliff v2.2.1..
 git cliff v0.1.0..HEAD
 ```
 
+Select a range with explicit endpoint inclusivity (`*-at` is inclusive; `*-after` / `*-before` is exclusive):
+
+```bash
+# include v1.0.0 itself; walk forward to HEAD
+git cliff --start-at v1.0.0
+
+# everything since v1.0.0, but not v1.0.0 itself
+git cliff --start-after v1.0.0
+
+# everything up to and including v2.0.0
+git cliff --end-at v2.0.0
+
+# strictly between two tags, both excluded
+git cliff --start-after v1.0.0 --end-before v2.0.0
+```
+
+These options can also be set in `cliff.toml` under `[git]`:
+
+```toml
+[git]
+start_after = "v1.0.0"
+end_at      = "v2.0.0"
+```
+
+Preview the selection before rendering with `--dry-run`:
+
+```bash
+# prints the interval, commit count, and emitted git range; no changelog is written
+git cliff --start-at v1.0.0 --end-at v2.0.0 --dry-run
+```
+
 Only include the tags from the current branch:
 
 ```bash