Use file modification times for dirty working directory timestamps

When setuptools-scm encounters a dirty working directory, it now uses
the latest modification time of changed files instead of falling back
to the current timestamp. This provides more meaningful version
timestamps during local development.

Changes:
- Added get_dirty_tag_date() method to Git and Mercurial working directory classes
- Enhanced timestamp logic in parsing functions to prioritize file mtimes
- Updated documentation to explain new timestamp behavior
- Maintains backward compatibility with clean repository behavior

The logic flow is now:
1. Try to get node_date from HEAD commit
2. If that fails AND working directory is dirty, use latest file mtime
3. Only fall back to datetime.now() as last resort

Author: RonnyPfannschmidt

docs/usage.md

@@ -294,71 +294,68 @@ be kept in version control. It's strongly recommended to be put into gitignore.
 `setuptools-scm` implements a [file_finders] entry point
 which returns all files tracked by your SCM.
 This eliminates the need for a manually constructed `MANIFEST.in` in most cases where this
-would be required when not using `setuptools-scm`, namely:
+would be required when not using `setuptools-scm`.
 
-* To ensure all relevant files are packaged when running the `sdist` command.
-  * When using [include_package_data] to include package data as part of the `build` or `bdist_wheel`.
+[file_finders]: https://setuptools.pypa.io/en/stable/userguide/extension.html
 
 #### How it works
 
-The file finder integration works through setuptools' plugin system:
-
-1. **Entry Point Registration**: setuptools-scm registers itself as a file finder via the `setuptools.file_finders` entry point
-2. **Automatic Discovery**: When setuptools builds a source distribution, it automatically calls setuptools-scm to get the list of files
-3. **SCM Integration**: setuptools-scm queries your SCM (Git, Mercurial) to get all tracked files
-4. **File Inclusion**: All SCM-tracked files are automatically included in the sdist
+1. **Automatic Discovery**: When building source distributions (`python -m build --sdist`), setuptools automatically calls the `setuptools-scm` file finder
+2. **SCM Integration**: The file finder queries your SCM (Git/Mercurial) for all tracked files
+3. **Inclusion**: All tracked files are automatically included in the sdist
 
 #### Controlling file inclusion
 
-**Using MANIFEST.in**: You can still use `MANIFEST.in` to override the automatic behavior:
+**To exclude unwanted files:**
 
-- **Exclude files**: Use `global-exclude` or `exclude` to remove files that are SCM-tracked but shouldn't be in the package
-- **Include additional files**: Use `include` to add files that aren't SCM-tracked
+1. **Use `MANIFEST.in`** to exclude specific files/patterns:
+   ```
+   exclude development.txt
+   recursive-exclude tests *.pyc
+   ```
 
-```text title="MANIFEST.in"
-# Exclude development files
-exclude *.nix
-exclude .pre-commit-config.yaml
-global-exclude *.pyc
+2. **Configure Git archive** (for Git repositories):
+   ```bash
+   # Add to .gitattributes
+   tests/ export-ignore
+   *.md export-ignore
+   ```
 
-# Include additional files not in SCM
-include data/special-file.dat
-```
+3. **Use `.hgignore`** or **Mercurial archive configuration** (for Mercurial repositories)
 
-**Example of what gets included automatically**:
+#### Troubleshooting
 
-- All files tracked by Git/Mercurial in your repository
-- Includes source code, data files, documentation, etc.
-- Excludes untracked files and files ignored by your SCM
+**Problem: Unwanted files in my package**
+- ✅ **Solution**: Add exclusions to `MANIFEST.in`
+- ✅ **Alternative**: Use Git/Mercurial archive configuration
 
-#### Troubleshooting
+**Problem: Missing files in package**
+- ✅ **Check**: Are the files tracked in your SCM?
+- ✅ **Solution**: `git add` missing files or override with `MANIFEST.in`
 
-**Too many files in your sdist?**
+**Problem: File finder not working**
+- ✅ **Check**: Is setuptools-scm installed in your build environment?
+- ✅ **Check**: Are you in a valid SCM repository?
 
-1. Check what's being included: `python -m setuptools_scm ls`
-2. Use `MANIFEST.in` to exclude unwanted files:
-   ```text
-   exclude development-file.txt
-   global-exclude *.log
-   prune unnecessary-directory/
-   ```
+### Timestamps for Local Development Versions
 
-**Files missing from your sdist?**
+!!! info "Improved Timestamp Behavior"
 
-1. Ensure files are tracked by your SCM: `git add` or `hg add`
-2. For non-SCM files, add them via `MANIFEST.in`:
-   ```text
-   include important-file.txt
-   recursive-include data *.json
-   ```
+    When your working directory has uncommitted changes (dirty), setuptools-scm now uses the **actual modification time of changed files** instead of the current time for local version schemes like `node-and-date`.
+
+    **Before**: Dirty working directories always used current time (`now`)
+    **Now**: Uses the latest modification time of changed files, falling back to current time only if no changed files are found
+
+    This provides more stable and meaningful timestamps that reflect when you actually made changes to your code.
 
-**Disable automatic file finding** (not recommended):
+**How it works:**
 
-If you need to completely disable setuptools-scm's file finder (not recommended), you would need to uninstall setuptools-scm from your build environment and handle versioning differently.
+1. **Clean repository**: Uses commit timestamp from SCM
+2. **Dirty repository**: Uses latest modification time of changed files
+3. **Fallback**: Uses current time if no modification times can be determined
 
-`MANIFEST.in` may still be used: anything defined there overrides the hook.
-This is mostly useful to exclude files tracked in your SCM from packages,
-although in principle it can be used to explicitly include non-tracked files too.
+**Benefits:**
 
-[file_finders]: https://setuptools.pypa.io/en/latest/userguide/extension.html#adding-support-for-revision-control-systems
-[include_package_data]: https://setuptools.readthedocs.io/en/latest/setuptools.html#including-data-files
+- More stable builds during development
+- Timestamps reflect actual change times
+- Better for reproducible development workflows

src/setuptools_scm/git.py

@@ -144,6 +144,45 @@ def parse_timestamp(timestamp_text: str) -> date | None:
             error_msg="logging the iso date for head failed",
         )
 
+    def get_dirty_tag_date(self) -> date | None:
+        """Get the latest modification time of changed files in the working directory.
+
+        Returns the date of the most recently modified file that has changes,
+        or None if no files are changed or if an error occurs.
+        """
+        if not self.is_dirty():
+            return None
+
+        try:
+            # Get list of changed files
+            changed_files_res = run_git(["diff", "--name-only"], self.path)
+            if changed_files_res.returncode != 0:
+                return None
+
+            changed_files = changed_files_res.stdout.strip().split("\n")
+            if not changed_files or changed_files == [""]:
+                return None
+
+            latest_mtime = 0.0
+            for filepath in changed_files:
+                full_path = self.path / filepath
+                try:
+                    file_stat = full_path.stat()
+                    latest_mtime = max(latest_mtime, file_stat.st_mtime)
+                except OSError:
+                    # File might not exist or be accessible, skip it
+                    continue
+
+            if latest_mtime > 0:
+                # Convert to UTC date
+                dt = datetime.fromtimestamp(latest_mtime, timezone.utc)
+                return dt.date()
+
+        except Exception as e:
+            log.debug("Failed to get dirty tag date: %s", e)
+
+        return None
+
     def is_shallow(self) -> bool:
         return self.path.joinpath(".git/shallow").is_file()
 
@@ -277,7 +316,20 @@ def _git_parse_inner(
             tag=tag, distance=distance, dirty=dirty, node=node, config=config
         )
     branch = wd.get_branch()
-    node_date = wd.get_head_date() or datetime.now(timezone.utc).date()
+    node_date = wd.get_head_date()
+
+    # If we can't get node_date from HEAD (e.g., no commits yet),
+    # and the working directory is dirty, try to use the latest
+    # modification time of changed files instead of current time
+    if node_date is None and wd.is_dirty():
+        dirty_date = wd.get_dirty_tag_date()
+        if dirty_date is not None:
+            node_date = dirty_date
+
+    # Final fallback to current time
+    if node_date is None:
+        node_date = datetime.now(timezone.utc).date()
+
     return dataclasses.replace(version, branch=branch, node_date=node_date)
 
 

src/setuptools_scm/hg.py

@@ -52,7 +52,17 @@ def get_meta(self, config: Configuration) -> ScmVersion | None:
             check=True,
         ).stdout.split("\n")
         dirty = bool(int(dirty_str))
-        node_date = datetime.date.fromisoformat(dirty_date if dirty else node_date_str)
+
+        # For dirty working directories, try to use the latest file modification time
+        # before falling back to the hg id date
+        if dirty:
+            file_mod_date = self.get_dirty_tag_date()
+            if file_mod_date is not None:
+                node_date = file_mod_date
+            else:
+                node_date = datetime.date.fromisoformat(dirty_date)
+        else:
+            node_date = datetime.date.fromisoformat(node_date_str)
 
         if node == "0" * len(node):
             log.debug("initial node %s", self.path)
@@ -144,6 +154,55 @@ def check_changes_since_tag(self, tag: str | None) -> bool:
 
         return bool(self.hg_log(revset, "."))
 
+    def get_dirty_tag_date(self) -> datetime.date | None:
+        """Get the latest modification time of changed files in the working directory.
+
+        Returns the date of the most recently modified file that has changes,
+        or None if no files are changed or if an error occurs.
+        """
+        try:
+            # Check if working directory is dirty first
+            res = _run([HG_COMMAND, "id", "-T", "{dirty}"], cwd=self.path)
+            if res.returncode != 0 or not bool(res.stdout):
+                return None
+
+            # Get list of changed files using hg status
+            status_res = _run([HG_COMMAND, "status", "-m", "-a", "-r"], cwd=self.path)
+            if status_res.returncode != 0:
+                return None
+
+            changed_files = []
+            for line in status_res.stdout.strip().split("\n"):
+                if line and len(line) > 2:
+                    # Format is "M filename" or "A filename" etc.
+                    filepath = line[2:]  # Skip status char and space
+                    changed_files.append(filepath)
+
+            if not changed_files:
+                return None
+
+            latest_mtime = 0.0
+            for filepath in changed_files:
+                full_path = self.path / filepath
+                try:
+                    file_stat = full_path.stat()
+                    latest_mtime = max(latest_mtime, file_stat.st_mtime)
+                except OSError:
+                    # File might not exist or be accessible, skip it
+                    continue
+
+            if latest_mtime > 0:
+                # Convert to UTC date
+                dt = datetime.datetime.fromtimestamp(
+                    latest_mtime, datetime.timezone.utc
+                )
+                return dt.date()
+
+        except Exception as e:
+            log.debug("Failed to get dirty tag date: %s", e)
+
+        return None
+
 
 def parse(root: _t.PathT, config: Configuration) -> ScmVersion | None:
     _require_command(HG_COMMAND)

src/setuptools_scm/hg_git.py

@@ -47,6 +47,58 @@ def get_head_date(self) -> date | None:
             [HG_COMMAND, "log", "-r", ".", "-T", "{shortdate(date)}"], cwd=self.path
         ).parse_success(parse=date.fromisoformat, error_msg="head date err")
 
+    def get_dirty_tag_date(self) -> date | None:
+        """Get the latest modification time of changed files in the working directory.
+
+        Returns the date of the most recently modified file that has changes,
+        or None if no files are changed or if an error occurs.
+        """
+        if not self.is_dirty():
+            return None
+
+        try:
+            from datetime import datetime
+            from datetime import timezone
+
+            # Get list of changed files using hg status
+            status_res = _run([HG_COMMAND, "status", "-m", "-a", "-r"], cwd=self.path)
+            if status_res.returncode != 0:
+                return None
+
+            changed_files = []
+            for line in status_res.stdout.strip().split("\n"):
+                if line and len(line) > 2:
+                    # Format is "M filename" or "A filename" etc.
+                    filepath = line[2:]  # Skip status char and space
+                    changed_files.append(filepath)
+
+            if not changed_files:
+                return None
+
+            latest_mtime = 0.0
+            for filepath in changed_files:
+                full_path = self.path / filepath
+                try:
+                    file_stat = full_path.stat()
+                    latest_mtime = max(latest_mtime, file_stat.st_mtime)
+                except OSError:
+                    # File might not exist or be accessible, skip it
+                    continue
+
+            if latest_mtime > 0:
+                # Convert to UTC date
+                dt = datetime.fromtimestamp(latest_mtime, timezone.utc)
+                return dt.date()
+
+        except Exception as e:
+            # Use the parent's log module
+            import logging
+
+            log = logging.getLogger(__name__)
+            log.debug("Failed to get dirty tag date: %s", e)
+
+        return None
+
     def is_shallow(self) -> bool:
         return False