python-kacl 0.7.0__tar.gz → 0.7.2__tar.gz

{python_kacl-0.7.0/python_kacl.egg-info → python_kacl-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kacl
-Version: 0.7.0
+Version: 0.7.2
 Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
 Author-email: Matthias Schmieder <schmieder.matthias@gmail.com>
 License: MIT
@@ -42,6 +42,8 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [Print the current release version](#print-the-current-release-version)
   - [Print a single release changelog](#print-a-single-release-changelog)
   - [Add an entry to an unreleased section](#add-an-entry-to-an-unreleased-section)
+  - [Stashing Unreleased Changes](#stashing-unreleased-changes)
+    - [Pre-commit Hook Integration](#pre-commit-hook-integration)
   - [Prepare a Changelog for a Release](#prepare-a-changelog-for-a-release)
   - [Changelog Fragments](#changelog-fragments)
     - [Configuration](#configuration)
@@ -121,13 +123,26 @@ docker -v $(pwd):$(pwd) -w $(pwd) mschmieder/kacl-cli:latest verify
 
 The package can also be used as a pre-commit hook. Just add the following to your `.pre-commit-config.yaml`
 
+**Verify Changelog Format**
+
 ```yaml
 - repo: https://gitlab.com/schmieder.matthias/python-kacl
-  rev: 'v0.3.0'
+  rev: 'v0.7.0'  # Use the latest version
   hooks:
     - id: kacl-verify
 ```
 
+**Auto-Stash Unreleased Changes (Prevent Merge Conflicts)**
+
+```yaml
+- repo: https://gitlab.com/schmieder.matthias/python-kacl
+  rev: 'v0.7.0'  # Use the latest version
+  hooks:
+    - id: kacl-stash
+```
+
+The `kacl-stash` hook automatically moves unreleased changes to stash files before each commit, preventing merge conflicts in `CHANGELOG.md`. See [Stashing Unreleased Changes](#stashing-unreleased-changes) for more details.
+
 ## CLI
 
 ```
@@ -143,6 +158,7 @@ Commands:
   get      Returns a given version from the Changelog
   new      Creates a new changelog.
   release  Creates a release for the latest 'unreleased' changes.
+  stash    Moves all unreleased changes from the changelog to the stash.
   verify   Verifies if the changelog is in "keep-a-changelog" format.
 ```
 
@@ -361,6 +377,112 @@ kacl-cli add added 'We just added some new cool stuff' --modify
 kacl-cli add changed 'And changed things a bit' --modify
 ```
 
+## Stashing Unreleased Changes
+
+```
+Usage: kacl-cli stash [OPTIONS]
+
+  Moves all unreleased changes from the changelog to the stash.
+
+Options:
+  -m, --modify  This option will modify the changelog file directly.
+  --help        Show this message and exit.
+```
+
+The `stash` command provides a powerful solution for managing unreleased changes and **preventing merge conflicts** in collaborative development environments. It moves all unreleased changes from `CHANGELOG.md` to a stash file, leaving an empty "Unreleased" section in the main changelog.
+
+**Primary Use Case: Avoiding Merge Conflicts**
+
+When multiple team members work on different branches simultaneously and manually edit `CHANGELOG.md`, merge conflicts are inevitable. The `stash` command solves this problem by:
+
+1. **Moving changes out of the main changelog** into separate stash files
+2. **Preventing conflicts** during merges since the main changelog remains minimal
+3. **Preserving all changes** in stash files that are later consolidated during release
+
+**Usage**
+
+```bash
+# Preview what would be stashed (dry-run)
+kacl-cli stash
+
+# Actually stash the changes and update CHANGELOG.md
+kacl-cli stash --modify
+```
+
+**How It Works**
+
+When you run `kacl-cli stash --modify`:
+
+1. All changes from the "Unreleased" section are extracted
+2. Changes are moved to a stash file in `.kacl_stash/` directory (default location)
+3. Stash files are named based on:
+   - Git branch name (when inside a git repository): `feature-branch.md`
+   - Current date (when outside git): `20230101.md`
+4. The "Unreleased" section in `CHANGELOG.md` is cleared
+5. During `kacl-cli release`, all stashed changes are automatically merged into the release
+
+**Example Workflow**
+
+```bash
+# Developer edits CHANGELOG.md directly
+echo "- Added new feature" >> CHANGELOG.md
+
+# Before committing, stash the changes to avoid conflicts
+kacl-cli stash --modify
+
+# CHANGELOG.md now has an empty Unreleased section
+# Changes are in .kacl_stash/your-branch.md
+
+# When ready to release, all stashed changes are included
+kacl-cli release patch --modify
+```
+
+### Pre-commit Hook Integration
+
+For maximum convenience, you can automate the stashing process using a pre-commit hook. This allows developers to continue editing `CHANGELOG.md` manually while automatically moving changes to the stash before each commit.
+
+**Setup**
+
+Add the `kacl-stash` hook to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://gitlab.com/schmieder.matthias/python-kacl
+    rev: 'v0.7.0'  # Use the latest version
+    hooks:
+      - id: kacl-stash
+```
+
+**How It Works**
+
+1. Developer manually edits `CHANGELOG.md` (traditional workflow)
+2. Pre-commit hook automatically runs `kacl-cli stash -m` before each commit
+3. Changes are moved to stash files
+4. Only the cleaned `CHANGELOG.md` is committed
+5. Multiple branches can work independently without conflicts
+6. During release, all stashed changes are consolidated
+
+**Benefits**
+
+- ✅ **No workflow changes**: Developers continue editing `CHANGELOG.md` normally
+- ✅ **Zero merge conflicts**: Main changelog stays minimal and conflict-free
+- ✅ **Automatic management**: Pre-commit hook handles everything
+- ✅ **Branch isolation**: Each branch has its own stash file
+- ✅ **Seamless integration**: Changes automatically included in releases
+
+**Configuration**
+
+You can customize the stash directory in `.kacl.yml`:
+
+```yaml
+kacl:
+  stash:
+    dir: .kacl_stash  # Custom stash directory
+    always: False     # Set to True to always use stash for 'kacl add'
+```
+
+**Note**: The `stash` command is complementary to [Changelog Fragments](#changelog-fragments). While fragments support the `kacl add` workflow, the `stash` command is specifically designed for teams that prefer manually editing `CHANGELOG.md` but want to avoid merge conflicts.
+
 ## Prepare a Changelog for a Release
 
 ```

{python_kacl-0.7.0 → python_kacl-0.7.2}/README.md

@@ -20,6 +20,8 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [Print the current release version](#print-the-current-release-version)
   - [Print a single release changelog](#print-a-single-release-changelog)
   - [Add an entry to an unreleased section](#add-an-entry-to-an-unreleased-section)
+  - [Stashing Unreleased Changes](#stashing-unreleased-changes)
+    - [Pre-commit Hook Integration](#pre-commit-hook-integration)
   - [Prepare a Changelog for a Release](#prepare-a-changelog-for-a-release)
   - [Changelog Fragments](#changelog-fragments)
     - [Configuration](#configuration)
@@ -99,13 +101,26 @@ docker -v $(pwd):$(pwd) -w $(pwd) mschmieder/kacl-cli:latest verify
 
 The package can also be used as a pre-commit hook. Just add the following to your `.pre-commit-config.yaml`
 
+**Verify Changelog Format**
+
 ```yaml
 - repo: https://gitlab.com/schmieder.matthias/python-kacl
-  rev: 'v0.3.0'
+  rev: 'v0.7.0'  # Use the latest version
   hooks:
     - id: kacl-verify
 ```
 
+**Auto-Stash Unreleased Changes (Prevent Merge Conflicts)**
+
+```yaml
+- repo: https://gitlab.com/schmieder.matthias/python-kacl
+  rev: 'v0.7.0'  # Use the latest version
+  hooks:
+    - id: kacl-stash
+```
+
+The `kacl-stash` hook automatically moves unreleased changes to stash files before each commit, preventing merge conflicts in `CHANGELOG.md`. See [Stashing Unreleased Changes](#stashing-unreleased-changes) for more details.
+
 ## CLI
 
 ```
@@ -121,6 +136,7 @@ Commands:
   get      Returns a given version from the Changelog
   new      Creates a new changelog.
   release  Creates a release for the latest 'unreleased' changes.
+  stash    Moves all unreleased changes from the changelog to the stash.
   verify   Verifies if the changelog is in "keep-a-changelog" format.
 ```
 
@@ -339,6 +355,112 @@ kacl-cli add added 'We just added some new cool stuff' --modify
 kacl-cli add changed 'And changed things a bit' --modify
 ```
 
+## Stashing Unreleased Changes
+
+```
+Usage: kacl-cli stash [OPTIONS]
+
+  Moves all unreleased changes from the changelog to the stash.
+
+Options:
+  -m, --modify  This option will modify the changelog file directly.
+  --help        Show this message and exit.
+```
+
+The `stash` command provides a powerful solution for managing unreleased changes and **preventing merge conflicts** in collaborative development environments. It moves all unreleased changes from `CHANGELOG.md` to a stash file, leaving an empty "Unreleased" section in the main changelog.
+
+**Primary Use Case: Avoiding Merge Conflicts**
+
+When multiple team members work on different branches simultaneously and manually edit `CHANGELOG.md`, merge conflicts are inevitable. The `stash` command solves this problem by:
+
+1. **Moving changes out of the main changelog** into separate stash files
+2. **Preventing conflicts** during merges since the main changelog remains minimal
+3. **Preserving all changes** in stash files that are later consolidated during release
+
+**Usage**
+
+```bash
+# Preview what would be stashed (dry-run)
+kacl-cli stash
+
+# Actually stash the changes and update CHANGELOG.md
+kacl-cli stash --modify
+```
+
+**How It Works**
+
+When you run `kacl-cli stash --modify`:
+
+1. All changes from the "Unreleased" section are extracted
+2. Changes are moved to a stash file in `.kacl_stash/` directory (default location)
+3. Stash files are named based on:
+   - Git branch name (when inside a git repository): `feature-branch.md`
+   - Current date (when outside git): `20230101.md`
+4. The "Unreleased" section in `CHANGELOG.md` is cleared
+5. During `kacl-cli release`, all stashed changes are automatically merged into the release
+
+**Example Workflow**
+
+```bash
+# Developer edits CHANGELOG.md directly
+echo "- Added new feature" >> CHANGELOG.md
+
+# Before committing, stash the changes to avoid conflicts
+kacl-cli stash --modify
+
+# CHANGELOG.md now has an empty Unreleased section
+# Changes are in .kacl_stash/your-branch.md
+
+# When ready to release, all stashed changes are included
+kacl-cli release patch --modify
+```
+
+### Pre-commit Hook Integration
+
+For maximum convenience, you can automate the stashing process using a pre-commit hook. This allows developers to continue editing `CHANGELOG.md` manually while automatically moving changes to the stash before each commit.
+
+**Setup**
+
+Add the `kacl-stash` hook to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://gitlab.com/schmieder.matthias/python-kacl
+    rev: 'v0.7.0'  # Use the latest version
+    hooks:
+      - id: kacl-stash
+```
+
+**How It Works**
+
+1. Developer manually edits `CHANGELOG.md` (traditional workflow)
+2. Pre-commit hook automatically runs `kacl-cli stash -m` before each commit
+3. Changes are moved to stash files
+4. Only the cleaned `CHANGELOG.md` is committed
+5. Multiple branches can work independently without conflicts
+6. During release, all stashed changes are consolidated
+
+**Benefits**
+
+- ✅ **No workflow changes**: Developers continue editing `CHANGELOG.md` normally
+- ✅ **Zero merge conflicts**: Main changelog stays minimal and conflict-free
+- ✅ **Automatic management**: Pre-commit hook handles everything
+- ✅ **Branch isolation**: Each branch has its own stash file
+- ✅ **Seamless integration**: Changes automatically included in releases
+
+**Configuration**
+
+You can customize the stash directory in `.kacl.yml`:
+
+```yaml
+kacl:
+  stash:
+    dir: .kacl_stash  # Custom stash directory
+    always: False     # Set to True to always use stash for 'kacl add'
+```
+
+**Note**: The `stash` command is complementary to [Changelog Fragments](#changelog-fragments). While fragments support the `kacl add` workflow, the `stash` command is specifically designed for teams that prefer manually editing `CHANGELOG.md` but want to avoid merge conflicts.
+
 ## Prepare a Changelog for a Release
 
 ```

{python_kacl-0.7.0 → python_kacl-0.7.2}/kacl/__init__.py

@@ -1,5 +1,5 @@
 # Version of the python-kacl package
-__version__ = "0.7.0"
+__version__ = "0.7.2"
 
 from kacl.document import KACLDocument
 from kacl.serializer import KACLMarkdownSerializer

{python_kacl-0.7.0 → python_kacl-0.7.2}/kacl/document.py

@@ -330,6 +330,60 @@ class KACLDocument:
                 self.__versions.insert(0, unreleased_version)
             unreleased_version.add(section.capitalize(), data)
 
+    def stash_unreleased(self):
+        """Moves all unreleased changes to the stash file.
+
+        This method takes all changes from the Unreleased section and writes them to
+        the stash file, then clears the Unreleased section from the changelog.
+        """
+        # Check if there are any unreleased changes
+        if not self.has_changes():
+            return False
+
+        # Get the unreleased version
+        unreleased_version = self.get("Unreleased")
+        if not unreleased_version:
+            return False
+
+        # Get or create the stash file
+        stash_file = self._get_stash_file()
+
+        if os.path.exists(stash_file):
+            # Load the stash file
+            kacl_changelog = kacl.load(stash_file)
+        else:
+            # Create a new stash file with an empty changelog
+            kacl_changelog = kacl.new()
+
+        # Add all unreleased changes to the stash
+        sections = unreleased_version.sections()
+        if sections:
+            for section_title, section_changes in sections.items():
+                for change_item in section_changes.items():
+                    kacl_changelog.add(section=section_title, data=change_item)
+
+        # Write the updated stash file
+        kacl_changelog_content = kacl.dump(kacl_changelog)
+        with open(stash_file, "w") as f:
+            f.write(kacl_changelog_content)
+        f.close()
+
+        # Clear the unreleased section by replacing it with an empty one
+        # Find and remove the current unreleased version but keep the link reference if it exists
+        link = None
+
+        for i, version in enumerate(self.__versions):
+            if version.version() == "Unreleased":
+                link = version.link()
+                self.__versions.pop(i)
+                break
+
+        # Add a new empty unreleased version
+        new_unreleased = KACLVersion(version="Unreleased", link=link)
+        self.__versions.insert(0, new_unreleased)
+
+        return True
+
     def release(
         self,
         version=None,

{python_kacl-0.7.0 → python_kacl-0.7.2}/kacl/kacl_cli.py

@@ -44,7 +44,7 @@ def raise_on_invalid(kacl_changelog):
         sys.exit(1)
 
 
-def load_changelog(ctx):
+def load_changelog(ctx, load_stash_files=True):
     config_file_path = ctx.obj["config"]
     input_file = ctx.obj["file"]
 
@@ -69,7 +69,8 @@ def load_changelog(ctx):
     # read the changelog
     kacl_changelog = kacl.load(kacl_config.changelog_file_path)
     kacl_changelog.config = kacl_config
-    kacl_changelog.load_stash()
+    if load_stash_files:
+        kacl_changelog.load_stash()
 
     # share the objects
     return kacl_changelog
@@ -159,6 +160,51 @@ def add(ctx, section, message, modify, stash):
         click.echo(kacl_changelog_content)
 
 
+@cli.command()
+@click.pass_context
+@click.option(
+    "-m",
+    "--modify",
+    is_flag=True,
+    help="This option will modify the changelog file directly.",
+)
+def stash(ctx, modify):
+    """Moves all unreleased changes from the changelog to the stash."""
+    # Load changelog WITHOUT loading stash files to avoid circular stashing
+    kacl_changelog = load_changelog(ctx, load_stash_files=False)
+
+    # Check if there are changes to stash
+    if not kacl_changelog.has_changes():
+        click.echo(
+            click.style("Info: ", fg="yellow") + "No unreleased changes to stash."
+        )
+        return
+
+    # Stash the unreleased changes
+    kacl_changelog.stash_unreleased()
+
+    stash_file = kacl_changelog._get_stash_file()
+    click.echo(
+        click.style("Success: ", fg="green")
+        + f"Unreleased changes have been moved to {stash_file}"
+    )
+
+    # Update the changelog file if modify flag is set
+    if modify:
+        kacl_changelog_content = kacl.dump(kacl_changelog)
+        with open(kacl_changelog.config.changelog_file_path, "w") as f:
+            f.write(kacl_changelog_content)
+        f.close()
+        click.echo(
+            click.style("Success: ", fg="green")
+            + f"Changelog file {kacl_changelog.config.changelog_file_path} has been updated."
+        )
+    else:
+        # Just print the modified changelog
+        kacl_changelog_content = kacl.dump(kacl_changelog)
+        click.echo(kacl_changelog_content)
+
+
 @cli.command()
 @click.pass_context
 def current(ctx):

{python_kacl-0.7.0 → python_kacl-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-kacl"
-version = "0.7.0"
+version = "0.7.2"
 description = "Python module and CLI tool for validating and modifying Changelogs in \"keep-a-changelog\" format\""
 readme = "README.md"
 requires-python = ">=3.9"

{python_kacl-0.7.0 → python_kacl-0.7.2/python_kacl.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kacl
-Version: 0.7.0
+Version: 0.7.2
 Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
 Author-email: Matthias Schmieder <schmieder.matthias@gmail.com>
 License: MIT
@@ -42,6 +42,8 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [Print the current release version](#print-the-current-release-version)
   - [Print a single release changelog](#print-a-single-release-changelog)
   - [Add an entry to an unreleased section](#add-an-entry-to-an-unreleased-section)
+  - [Stashing Unreleased Changes](#stashing-unreleased-changes)
+    - [Pre-commit Hook Integration](#pre-commit-hook-integration)
   - [Prepare a Changelog for a Release](#prepare-a-changelog-for-a-release)
   - [Changelog Fragments](#changelog-fragments)
     - [Configuration](#configuration)
@@ -121,13 +123,26 @@ docker -v $(pwd):$(pwd) -w $(pwd) mschmieder/kacl-cli:latest verify
 
 The package can also be used as a pre-commit hook. Just add the following to your `.pre-commit-config.yaml`
 
+**Verify Changelog Format**
+
 ```yaml
 - repo: https://gitlab.com/schmieder.matthias/python-kacl
-  rev: 'v0.3.0'
+  rev: 'v0.7.0'  # Use the latest version
   hooks:
     - id: kacl-verify
 ```
 
+**Auto-Stash Unreleased Changes (Prevent Merge Conflicts)**
+
+```yaml
+- repo: https://gitlab.com/schmieder.matthias/python-kacl
+  rev: 'v0.7.0'  # Use the latest version
+  hooks:
+    - id: kacl-stash
+```
+
+The `kacl-stash` hook automatically moves unreleased changes to stash files before each commit, preventing merge conflicts in `CHANGELOG.md`. See [Stashing Unreleased Changes](#stashing-unreleased-changes) for more details.
+
 ## CLI
 
 ```
@@ -143,6 +158,7 @@ Commands:
   get      Returns a given version from the Changelog
   new      Creates a new changelog.
   release  Creates a release for the latest 'unreleased' changes.
+  stash    Moves all unreleased changes from the changelog to the stash.
   verify   Verifies if the changelog is in "keep-a-changelog" format.
 ```
 
@@ -361,6 +377,112 @@ kacl-cli add added 'We just added some new cool stuff' --modify
 kacl-cli add changed 'And changed things a bit' --modify
 ```
 
+## Stashing Unreleased Changes
+
+```
+Usage: kacl-cli stash [OPTIONS]
+
+  Moves all unreleased changes from the changelog to the stash.
+
+Options:
+  -m, --modify  This option will modify the changelog file directly.
+  --help        Show this message and exit.
+```
+
+The `stash` command provides a powerful solution for managing unreleased changes and **preventing merge conflicts** in collaborative development environments. It moves all unreleased changes from `CHANGELOG.md` to a stash file, leaving an empty "Unreleased" section in the main changelog.
+
+**Primary Use Case: Avoiding Merge Conflicts**
+
+When multiple team members work on different branches simultaneously and manually edit `CHANGELOG.md`, merge conflicts are inevitable. The `stash` command solves this problem by:
+
+1. **Moving changes out of the main changelog** into separate stash files
+2. **Preventing conflicts** during merges since the main changelog remains minimal
+3. **Preserving all changes** in stash files that are later consolidated during release
+
+**Usage**
+
+```bash
+# Preview what would be stashed (dry-run)
+kacl-cli stash
+
+# Actually stash the changes and update CHANGELOG.md
+kacl-cli stash --modify
+```
+
+**How It Works**
+
+When you run `kacl-cli stash --modify`:
+
+1. All changes from the "Unreleased" section are extracted
+2. Changes are moved to a stash file in `.kacl_stash/` directory (default location)
+3. Stash files are named based on:
+   - Git branch name (when inside a git repository): `feature-branch.md`
+   - Current date (when outside git): `20230101.md`
+4. The "Unreleased" section in `CHANGELOG.md` is cleared
+5. During `kacl-cli release`, all stashed changes are automatically merged into the release
+
+**Example Workflow**
+
+```bash
+# Developer edits CHANGELOG.md directly
+echo "- Added new feature" >> CHANGELOG.md
+
+# Before committing, stash the changes to avoid conflicts
+kacl-cli stash --modify
+
+# CHANGELOG.md now has an empty Unreleased section
+# Changes are in .kacl_stash/your-branch.md
+
+# When ready to release, all stashed changes are included
+kacl-cli release patch --modify
+```
+
+### Pre-commit Hook Integration
+
+For maximum convenience, you can automate the stashing process using a pre-commit hook. This allows developers to continue editing `CHANGELOG.md` manually while automatically moving changes to the stash before each commit.
+
+**Setup**
+
+Add the `kacl-stash` hook to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://gitlab.com/schmieder.matthias/python-kacl
+    rev: 'v0.7.0'  # Use the latest version
+    hooks:
+      - id: kacl-stash
+```
+
+**How It Works**
+
+1. Developer manually edits `CHANGELOG.md` (traditional workflow)
+2. Pre-commit hook automatically runs `kacl-cli stash -m` before each commit
+3. Changes are moved to stash files
+4. Only the cleaned `CHANGELOG.md` is committed
+5. Multiple branches can work independently without conflicts
+6. During release, all stashed changes are consolidated
+
+**Benefits**
+
+- ✅ **No workflow changes**: Developers continue editing `CHANGELOG.md` normally
+- ✅ **Zero merge conflicts**: Main changelog stays minimal and conflict-free
+- ✅ **Automatic management**: Pre-commit hook handles everything
+- ✅ **Branch isolation**: Each branch has its own stash file
+- ✅ **Seamless integration**: Changes automatically included in releases
+
+**Configuration**
+
+You can customize the stash directory in `.kacl.yml`:
+
+```yaml
+kacl:
+  stash:
+    dir: .kacl_stash  # Custom stash directory
+    always: False     # Set to True to always use stash for 'kacl add'
+```
+
+**Note**: The `stash` command is complementary to [Changelog Fragments](#changelog-fragments). While fragments support the `kacl add` workflow, the `stash` command is specifically designed for teams that prefer manually editing `CHANGELOG.md` but want to avoid merge conflicts.
+
 ## Prepare a Changelog for a Release
 
 ```

{python_kacl-0.7.0 → python_kacl-0.7.2}/tests/test_cli.py

@@ -589,3 +589,154 @@ def test_get_suppress_available_link(tmp_path, snapshot):
         with open(os.path.join(project_root_path, "output.md"), "w") as file:
             file.write(result.output)
         snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
+
+
+@freeze_time("2023-01-01")
+def test_stash_no_pre_existing(tmp_path, snapshot):
+    """Test stashing when there is no pre-existing stash file."""
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-f",
+                "CHANGELOG.md",
+                "stash",
+                "-m",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        assert "Success: Unreleased changes have been moved to" in result.output
+        assert "Success: Changelog file CHANGELOG.md has been updated" in result.output
+
+        # Verify stash directory and file were created
+        stash_dir = os.path.join(project_root_path, ".kacl_stash")
+        assert os.path.exists(stash_dir)
+        assert len(os.listdir(stash_dir)) == 1
+
+        snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
+
+
+@freeze_time("2023-01-01")
+def test_stash_with_pre_existing(tmp_path, snapshot):
+    """Test stashing when there is a pre-existing stash file with changes."""
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes.md")
+    stash_dir_source = os.path.join(resources_dir, "stash")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        # Copy pre-existing stash directory
+        shutil.copytree(
+            stash_dir_source, os.path.join(project_root_path, ".kacl_stash")
+        )
+
+        result = runner.invoke(
+            cli,
+            [
+                "-f",
+                "CHANGELOG.md",
+                "stash",
+                "-m",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        assert "Success: Unreleased changes have been moved to" in result.output
+        assert "Success: Changelog file CHANGELOG.md has been updated" in result.output
+
+        snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
+
+
+@freeze_time("2023-01-01")
+def test_stash_with_link(tmp_path, snapshot):
+    """Test stashing when there is a pre-existing stash file with changes."""
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes_and_link.md")
+    stash_dir_source = os.path.join(resources_dir, "stash")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        # Copy pre-existing stash directory
+        shutil.copytree(
+            stash_dir_source, os.path.join(project_root_path, ".kacl_stash")
+        )
+
+        result = runner.invoke(
+            cli,
+            [
+                "-c",
+                os.path.join(resources_dir, "extension-config.yml"),
+                "-f",
+                "CHANGELOG.md",
+                "stash",
+                "-m",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        assert "Success: Unreleased changes have been moved to" in result.output
+        assert "Success: Changelog file CHANGELOG.md has been updated" in result.output
+
+        snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
+
+
+@freeze_time("2023-01-01")
+def test_stash_no_changes(tmp_path, snapshot):
+    """Test stashing when there are no unreleased changes."""
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_without_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-f",
+                "CHANGELOG.md",
+                "stash",
+                "-m",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        assert "Info: No unreleased changes to stash" in result.output
+
+        # Verify no stash directory was created
+        stash_dir = os.path.join(project_root_path, ".kacl_stash")
+        assert not os.path.exists(stash_dir)
+
+
+@freeze_time("2023-01-01")
+def test_stash_without_modify(tmp_path, snapshot):
+    """Test stash command without --modify flag (dry run)."""
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-f",
+                "CHANGELOG.md",
+                "stash",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        assert "Success: Unreleased changes have been moved to" in result.output
+        # Should output the modified changelog content
+        assert "## Unreleased" in result.output
+        assert "## 1.0.0" in result.output
+
+        snapshot_directory(snapshot=snapshot, directory_path=project_root_path)