feat: collect --title=TEXT #48

Author: Ned Batchelder

changelog.d/20220914_192807_nedbat_collect_header.rst

@@ -0,0 +1,8 @@
+Added
+.....
+
+- The ``collect`` command now has a ``--title=TEXT`` option to provide the
+  exact text to use as the title of the new changelog entry.  Finishes `issue
+  48`_.
+
+.. _issue 48: https://github.com/nedbat/scriv/issues/48

docs/commands.rst

@@ -107,13 +107,15 @@ scriv collect
       Collect fragments and produce a combined entry in the CHANGELOG file.
 
     Options:
-      --add / --no-add     'git add' the updated changelog file.
+      --add / --no-add     'git add' the updated changelog file and removed
+                           fragments.
       --edit / --no-edit   Open the changelog file in your text editor.
+      --title TEXT         The title text to use for this entry.
       --keep               Keep the fragment files that are collected.
       --version TEXT       The version name to use for this entry.
       -v, --verbosity LVL  Either CRITICAL, ERROR, WARNING, INFO or DEBUG
       --help               Show this message and exit.
-.. [[[end]]] (checksum: 5a37816dcb12829eca58f1ccd42a8e62)
+.. [[[end]]] (checksum: 3f25ae739160c63a0685e98f88681927)
 
 The collect command aggregates all the current fragments into the changelog
 file.
@@ -124,8 +126,11 @@ Entry Creation
 All of the .rst or .md files in the fragment directory are read, parsed, and
 re-assembled into a changelog entry.  The entry's title is determined by the
 :ref:`config_entry_title_template` setting. The default uses the version string
-(if one is specified in the from the :ref:`config_version` setting) and the
-current date.
+(if one is specified in the :ref:`config_version` setting) and the current
+date.
+
+Instead of using the title template, you can provide an exact title to use for
+the new entry with the ``--title`` option.
 
 The output file is specified by the :ref:`config_output_file` setting.  Scriv
 looks in the file for a special marker (usually in a comment) to determine
@@ -135,6 +140,7 @@ this, you can have your changelog be just part of a larger README file.  If
 there is no marker in the file, the new entry is inserted at the top of the
 file.
 
+
 Fragment Deletion
 -----------------
 

src/scriv/collect.py

@@ -1,6 +1,7 @@
 """Collecting fragments."""
 
 import logging
+import sys
 from typing import Optional
 
 import click
@@ -14,13 +15,18 @@
 
 @click.command()
 @click.option(
-    "--add/--no-add", default=None, help="'git add' the updated changelog file."
+    "--add/--no-add",
+    default=None,
+    help="'git add' the updated changelog file and removed fragments.",
 )
 @click.option(
     "--edit/--no-edit",
     default=None,
     help="Open the changelog file in your text editor.",
 )
+@click.option(
+    "--title", default=None, help="The title text to use for this entry."
+)
 @click.option(
     "--keep", is_flag=True, help="Keep the fragment files that are collected."
 )
@@ -29,11 +35,18 @@
 )
 @click_log.simple_verbosity_option(logger)
 def collect(
-    add: Optional[bool], edit: Optional[bool], keep: bool, version: str
+    add: Optional[bool],
+    edit: Optional[bool],
+    title: str,
+    keep: bool,
+    version: str,
 ) -> None:
     """
     Collect fragments and produce a combined entry in the CHANGELOG file.
     """
+    if title is not None and version is not None:
+        sys.exit("Can't provide both --title and --version.")
+
     if add is None:
         add = git_config_bool("scriv.collect.add")
     if edit is None:
@@ -49,7 +62,10 @@ def collect(
     changelog = scriv.changelog()
     changelog.read()
 
-    new_header = changelog.entry_header(version=version)
+    if title is None:
+        new_header = changelog.entry_header(version=version)
+    else:
+        new_header = changelog.format_tools().format_header(title)
     new_text = changelog.entry_text(scriv.combine_fragments(frags))
     changelog.add_entry(new_header, new_text)
     changelog.write()

tests/test_collect.py

@@ -437,3 +437,24 @@ def test_no_fragments(cli_invoke, changelog_d, temp_dir, caplog):
     changelog_text = (temp_dir / "CHANGELOG.rst").read_text()
     assert changelog_text == "Not much\n"
     assert "No changelog fragments to collect" in caplog.text
+
+
+def test_title_provided(cli_invoke, changelog_d, temp_dir):
+    (changelog_d / "20170616_nedbat.rst").write_text(COMMENT + FRAG1 + COMMENT)
+    (changelog_d / "20170617_nedbat.rst").write_text(COMMENT + FRAG2)
+    title = "This is the Header"
+    cli_invoke(["collect", "--title", title])
+    changelog_text = (temp_dir / "CHANGELOG.rst").read_text()
+    # With --title provided, the first header is literally what was provided.
+    lines = CHANGELOG_1_2.splitlines()
+    lines[1] = title
+    lines[2] = len(title) * "="
+    assert changelog_text == "\n".join(lines) + "\n"
+
+
+def test_title_and_version_clash(cli_invoke):
+    result = cli_invoke(
+        ["collect", "--title", "xx", "--version", "1.2"], expect_ok=False
+    )
+    assert result.exit_code == 1
+    assert str(result.exception) == "Can't provide both --title and --version."