reposnap 0.6.5__tar.gz → 0.8.0__tar.gz

{reposnap-0.6.5 → reposnap-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reposnap
-Version: 0.6.5
+Version: 0.8.0
 Summary: Generate a Markdown file with all contents of your project
 Author: agoloborodko
 License-File: LICENSE
@@ -25,6 +25,8 @@ Description-Content-Type: text/markdown
 - **Structure Only Option**: The `--structure-only` flag can be used to generate the Markdown file with just the directory structure, omitting the contents of the files.
 - **Gitignore Support**: Automatically respects `.gitignore` patterns to exclude files and directories.
 - **Include and Exclude Patterns**: Use `--include` and `--exclude` to specify patterns for files and directories to include or exclude.
+- **Content Filtering**: Use `--contains` to filter files based on their content, including only files that contain specific substrings or code patterns.
+- **Changes Only Mode**: Use `-c` or `--changes` to snapshot only uncommitted files (staged, unstaged, untracked, and stashed changes).
 
 ## Installation
 
@@ -49,7 +51,7 @@ pip install -r requirements.lock
 To use `reposnap` from the command line, run it with the following options:
 
 ```bash
-reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]] [-e EXCLUDE [EXCLUDE ...]] paths [paths ...]
+reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]] [-e EXCLUDE [EXCLUDE ...]] [-c] [-S CONTAINS [CONTAINS ...]] [--contains-case] paths [paths ...]
 ```
 
 - `paths`: One or more paths (files or directories) within the repository whose content and structure should be rendered.
@@ -59,6 +61,9 @@ reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]
 - `--debug`: Enable debug-level logging.
 - `-i, --include`: File/folder patterns to include. For example, `-i "*.py"` includes only Python files.
 - `-e, --exclude`: File/folder patterns to exclude. For example, `-e "*.md"` excludes all Markdown files.
+- `-c, --changes`: Use only files that are added/modified/untracked/stashed but not yet committed.
+- `-S, --contains`: Only include files whose contents contain these substrings. Multiple patterns can be specified.
+- `--contains-case`: Make `--contains` case-sensitive (default is case-insensitive).
 
 #### Pattern Matching
 
@@ -71,6 +76,77 @@ reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]
   - `-i "*.py"`: Includes only files ending with `.py`.
   - `-e "*.test.*"`: Excludes files with `.test.` in their names.
 
+#### Content Filtering
+
+The `--contains` (or `-S`) flag allows you to filter files based on their content, including only files that contain specific substrings. This is particularly useful for focusing on files that contain certain code patterns, imports, or keywords.
+
+- **Case Sensitivity**: By default, content matching is case-insensitive. Use the `--contains-case` flag to enable case-sensitive matching.
+- **Multiple Patterns**: You can specify multiple patterns, and files containing **any** of the patterns will be included (OR logic).
+- **Performance**: Large files (>5MB) and binary files are automatically skipped for performance and safety reasons.
+
+**Examples**:
+
+1. **Find files containing specific imports**:
+    ```bash
+    reposnap . -S "import logging"
+    ```
+
+2. **Search for multiple patterns (OR logic)**:
+    ```bash
+    reposnap . -S "TODO" "FIXME" "import requests"
+    ```
+
+3. **Case-sensitive content search**:
+    ```bash
+    reposnap . -S "TODO" --contains-case
+    ```
+
+4. **Combine content filtering with other filters**:
+    ```bash
+    reposnap . -S "class " -i "*.py" --structure-only
+    ```
+
+5. **Find files with specific function calls**:
+    ```bash
+    reposnap . -S "logger.error" "raise Exception"
+    ```
+
+#### Only Snapshot Your Current Work
+
+The `-c` or `--changes` flag allows you to generate documentation for only the files that have been modified but not yet committed. This includes:
+
+- **Staged changes**: Files that have been added to the index with `git add`
+- **Unstaged changes**: Files that have been modified but not yet staged
+- **Untracked files**: New files that haven't been added to Git yet
+- **Stashed changes**: Files that are stored in Git stash entries
+
+This is particularly useful when you want to:
+- Document only your current work-in-progress
+- Create a snapshot of changes before committing
+- Review what files you've been working on
+
+**Examples**:
+
+1. **Generate documentation for only your uncommitted changes**:
+    ```bash
+    reposnap . -c
+    ```
+
+2. **Combine with structure-only for a quick overview**:
+    ```bash
+    reposnap . -c --structure-only
+    ```
+
+3. **Filter uncommitted changes by file type**:
+    ```bash
+    reposnap . -c -i "*.py"
+    ```
+
+4. **Exclude test files from uncommitted changes**:
+    ```bash
+    reposnap . -c -e "*test*"
+    ```
+
 #### Examples
 
 1. **Generate a full project structure with file contents**:
@@ -103,6 +179,24 @@ reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]
     reposnap my_project/ -e "gui"
     ```
 
+6. **Document only your current uncommitted work**:
+
+    ```bash
+    reposnap . -c
+    ```
+
+7. **Find and document files containing specific code patterns**:
+
+    ```bash
+    reposnap . -S "import logging" "logger."
+    ```
+
+8. **Combine content filtering with file type filtering**:
+
+    ```bash
+    reposnap . -S "class " -i "*.py" --structure-only
+    ```
+
 ### Graphical User Interface
 
 `reposnap` also provides a GUI for users who prefer an interactive interface.

{reposnap-0.6.5 → reposnap-0.8.0}/README.md

@@ -12,6 +12,8 @@
 - **Structure Only Option**: The `--structure-only` flag can be used to generate the Markdown file with just the directory structure, omitting the contents of the files.
 - **Gitignore Support**: Automatically respects `.gitignore` patterns to exclude files and directories.
 - **Include and Exclude Patterns**: Use `--include` and `--exclude` to specify patterns for files and directories to include or exclude.
+- **Content Filtering**: Use `--contains` to filter files based on their content, including only files that contain specific substrings or code patterns.
+- **Changes Only Mode**: Use `-c` or `--changes` to snapshot only uncommitted files (staged, unstaged, untracked, and stashed changes).
 
 ## Installation
 
@@ -36,7 +38,7 @@ pip install -r requirements.lock
 To use `reposnap` from the command line, run it with the following options:
 
 ```bash
-reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]] [-e EXCLUDE [EXCLUDE ...]] paths [paths ...]
+reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]] [-e EXCLUDE [EXCLUDE ...]] [-c] [-S CONTAINS [CONTAINS ...]] [--contains-case] paths [paths ...]
 ```
 
 - `paths`: One or more paths (files or directories) within the repository whose content and structure should be rendered.
@@ -46,6 +48,9 @@ reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]
 - `--debug`: Enable debug-level logging.
 - `-i, --include`: File/folder patterns to include. For example, `-i "*.py"` includes only Python files.
 - `-e, --exclude`: File/folder patterns to exclude. For example, `-e "*.md"` excludes all Markdown files.
+- `-c, --changes`: Use only files that are added/modified/untracked/stashed but not yet committed.
+- `-S, --contains`: Only include files whose contents contain these substrings. Multiple patterns can be specified.
+- `--contains-case`: Make `--contains` case-sensitive (default is case-insensitive).
 
 #### Pattern Matching
 
@@ -58,6 +63,77 @@ reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]
   - `-i "*.py"`: Includes only files ending with `.py`.
   - `-e "*.test.*"`: Excludes files with `.test.` in their names.
 
+#### Content Filtering
+
+The `--contains` (or `-S`) flag allows you to filter files based on their content, including only files that contain specific substrings. This is particularly useful for focusing on files that contain certain code patterns, imports, or keywords.
+
+- **Case Sensitivity**: By default, content matching is case-insensitive. Use the `--contains-case` flag to enable case-sensitive matching.
+- **Multiple Patterns**: You can specify multiple patterns, and files containing **any** of the patterns will be included (OR logic).
+- **Performance**: Large files (>5MB) and binary files are automatically skipped for performance and safety reasons.
+
+**Examples**:
+
+1. **Find files containing specific imports**:
+    ```bash
+    reposnap . -S "import logging"
+    ```
+
+2. **Search for multiple patterns (OR logic)**:
+    ```bash
+    reposnap . -S "TODO" "FIXME" "import requests"
+    ```
+
+3. **Case-sensitive content search**:
+    ```bash
+    reposnap . -S "TODO" --contains-case
+    ```
+
+4. **Combine content filtering with other filters**:
+    ```bash
+    reposnap . -S "class " -i "*.py" --structure-only
+    ```
+
+5. **Find files with specific function calls**:
+    ```bash
+    reposnap . -S "logger.error" "raise Exception"
+    ```
+
+#### Only Snapshot Your Current Work
+
+The `-c` or `--changes` flag allows you to generate documentation for only the files that have been modified but not yet committed. This includes:
+
+- **Staged changes**: Files that have been added to the index with `git add`
+- **Unstaged changes**: Files that have been modified but not yet staged
+- **Untracked files**: New files that haven't been added to Git yet
+- **Stashed changes**: Files that are stored in Git stash entries
+
+This is particularly useful when you want to:
+- Document only your current work-in-progress
+- Create a snapshot of changes before committing
+- Review what files you've been working on
+
+**Examples**:
+
+1. **Generate documentation for only your uncommitted changes**:
+    ```bash
+    reposnap . -c
+    ```
+
+2. **Combine with structure-only for a quick overview**:
+    ```bash
+    reposnap . -c --structure-only
+    ```
+
+3. **Filter uncommitted changes by file type**:
+    ```bash
+    reposnap . -c -i "*.py"
+    ```
+
+4. **Exclude test files from uncommitted changes**:
+    ```bash
+    reposnap . -c -e "*test*"
+    ```
+
 #### Examples
 
 1. **Generate a full project structure with file contents**:
@@ -90,6 +166,24 @@ reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] [-i INCLUDE [INCLUDE ...]
     reposnap my_project/ -e "gui"
     ```
 
+6. **Document only your current uncommitted work**:
+
+    ```bash
+    reposnap . -c
+    ```
+
+7. **Find and document files containing specific code patterns**:
+
+    ```bash
+    reposnap . -S "import logging" "logger."
+    ```
+
+8. **Combine content filtering with file type filtering**:
+
+    ```bash
+    reposnap . -S "class " -i "*.py" --structure-only
+    ```
+
 ### Graphical User Interface
 
 `reposnap` also provides a GUI for users who prefer an interactive interface.

{reposnap-0.6.5 → reposnap-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "reposnap"
-version = "0.6.5"
+version = "0.8.0"
 description = "Generate a Markdown file with all contents of your project"
 authors = [
     { name = "agoloborodko" }

{reposnap-0.6.5 → reposnap-0.8.0}/reposnap/controllers/project_controller.py

@@ -15,11 +15,17 @@ class ProjectController:
             self.args = args
             # Treat positional arguments as literal file/directory names.
             input_paths = [
-                Path(p) for p in (args.paths if hasattr(args, "paths") else [args.path])
+                Path(p) for p in (args.paths if hasattr(args, "paths") else [])
             ]
             self.input_paths = []
             for p in input_paths:
-                candidate = (self.root_dir / p).resolve()
+                if p.is_absolute():
+                    # Handle absolute paths - use as-is but verify they're under root_dir
+                    candidate = p.resolve()
+                else:
+                    # Handle relative paths - join with root_dir
+                    candidate = (self.root_dir / p).resolve()
+
                 if candidate.exists():
                     try:
                         rel = candidate.relative_to(self.root_dir)
@@ -31,7 +37,7 @@ class ProjectController:
                         )
                 else:
                     self.logger.warning(
-                        f"Path {p} does not exist relative to repository root {self.root_dir}."
+                        f"Path {p} does not exist or is not under repository root {self.root_dir}."
                     )
             self.output_file: Path = (
                 Path(args.output).resolve()
@@ -47,6 +53,9 @@ class ProjectController:
             self.exclude_patterns: List[str] = (
                 args.exclude if hasattr(args, "exclude") else []
             )
+            self.changes_only: bool = getattr(args, "changes", False)
+            self.contains: List[str] = getattr(args, "contains", [])
+            self.contains_case: bool = getattr(args, "contains_case", False)
         else:
             self.args = None
             self.input_paths = []
@@ -54,6 +63,9 @@ class ProjectController:
             self.structure_only = False
             self.include_patterns = []
             self.exclude_patterns = []
+            self.changes_only = False
+            self.contains = []
+            self.contains_case = False
         self.file_tree: Optional[FileTree] = None
         self.gitignore_patterns: List[str] = []
         if self.root_dir:
@@ -108,14 +120,76 @@ class ProjectController:
             files = [f for f in files if not spec_exc.match_file(f.as_posix())]
         return files
 
+    def _apply_content_filter(self, files: List[Path]) -> List[Path]:
+        """
+        Filter files based on content substring matching.
+
+        Args:
+            files: List of relative file paths to filter
+
+        Returns:
+            Filtered list of files that contain at least one of the patterns
+            specified in self.contains. Returns original list if no patterns
+            are specified.
+
+        Note:
+            Uses case-insensitive matching by default unless self.contains_case
+            is True. Skips binary files and files larger than 5MB for performance.
+        """
+        if not self.contains:
+            return files
+
+        from reposnap.core.content_search import filter_files_by_content
+
+        initial_count = len(files)
+        ignore_case = not self.contains_case
+
+        self.logger.debug(
+            f"Applying content filter with patterns: {self.contains}, "
+            f"ignore_case: {ignore_case}"
+        )
+
+        # Convert relative paths to absolute for content search
+        absolute_paths = [self.root_dir / file_path for file_path in files]
+        filtered_absolute = filter_files_by_content(
+            absolute_paths, self.contains, ignore_case
+        )
+
+        # Convert back to relative paths
+        filtered_files = []
+        for abs_path in filtered_absolute:
+            try:
+                rel_path = abs_path.relative_to(self.root_dir)
+                filtered_files.append(rel_path)
+            except ValueError:
+                continue
+
+        kept_count = len(filtered_files)
+        self.logger.info(
+            f"Applied content filter (kept {kept_count} / {initial_count})"
+        )
+        self.logger.debug(f"Files kept after content filter: {filtered_files}")
+
+        return filtered_files
+
     def collect_file_tree(self) -> None:
-        self.logger.info("Collecting files from Git tracked files if available.")
+        if self.changes_only:
+            self.logger.info("Collecting uncommitted files from Git repository.")
+        else:
+            self.logger.info("Collecting files from Git tracked files if available.")
         try:
             from reposnap.core.git_repo import GitRepo
 
             git_repo = GitRepo(self.root_dir)
-            all_files = git_repo.get_git_files()
-            self.logger.debug(f"Git tracked files: {all_files}")
+            if self.changes_only:
+                all_files = git_repo.get_uncommitted_files()
+                self.logger.info(
+                    "Using only uncommitted files (staged, unstaged, untracked, stashed)."
+                )
+            else:
+                all_files = git_repo.get_git_files()
+                self.logger.info("Using all Git tracked files.")
+            self.logger.debug(f"Git files: {all_files}")
         except Exception as e:
             self.logger.warning(f"Error obtaining Git tracked files: {e}.")
             all_files = []
@@ -135,6 +209,8 @@ class ProjectController:
                         continue
         all_files = self._apply_include_exclude(all_files)
         self.logger.debug(f"All files after applying include/exclude: {all_files}")
+        all_files = self._apply_content_filter(all_files)
+        self.logger.debug(f"All files after applying content filter: {all_files}")
         if self.input_paths:
             trees = []
             for input_path in self.input_paths:

reposnap-0.8.0/reposnap/core/content_search.py

@@ -0,0 +1,104 @@
+# src/reposnap/core/content_search.py
+
+"""
+Private content search helpers for substring matching in files.
+
+This module provides stateless utility functions for searching file contents.
+It is intended for internal use by the project controller and should not be
+imported directly by external consumers.
+"""
+
+import logging
+from pathlib import Path
+from typing import List
+
+
+logger = logging.getLogger(__name__)
+
+# Configuration constants
+MAX_FILE_SIZE = 5 * 1024 * 1024  # 5 MiB
+BINARY_CHECK_SIZE = 1024  # First 1KB to check for binary content
+
+
+def file_matches(path: Path, patterns: List[str], ignore_case: bool = True) -> bool:
+    """
+    Check if a file contains any of the given patterns.
+
+    Args:
+        path: Path to the file to search
+        patterns: List of substring patterns to search for
+        ignore_case: Whether to perform case-insensitive matching (default: True)
+
+    Returns:
+        True if file contains any pattern, False otherwise
+
+    Note:
+        Uses streaming read with utf-8 encoding and error handling for binary files.
+        Returns False if file cannot be read as text or if file is too large/binary.
+    """
+    if not patterns:
+        return True
+
+    if not path.is_file():
+        return False
+
+    # Check file size - skip files larger than MAX_FILE_SIZE
+    try:
+        file_size = path.stat().st_size
+        if file_size > MAX_FILE_SIZE:
+            logger.debug(f"Skipping large file {path} ({file_size} bytes)")
+            return False
+    except OSError as e:
+        logger.debug(f"Could not stat file {path}: {e}")
+        return False
+
+    # Check for binary content in first KB
+    try:
+        with path.open("rb") as f:
+            first_chunk = f.read(BINARY_CHECK_SIZE)
+            if b"\0" in first_chunk:
+                logger.debug(f"Skipping binary file {path}")
+                return False
+    except Exception as e:
+        logger.debug(f"Could not read file {path} for binary check: {e}")
+        return False
+
+    # Pre-compute search patterns (case-normalized if needed)
+    search_patterns = [p.lower() if ignore_case else p for p in patterns]
+
+    try:
+        with path.open("r", encoding="utf-8", errors="ignore") as f:
+            for line in f:
+                search_line = line.lower() if ignore_case else line
+
+                if any(pattern in search_line for pattern in search_patterns):
+                    return True
+        return False
+    except Exception as e:
+        logger.debug(f"Could not read file {path} for content search: {e}")
+        return False
+
+
+def filter_files_by_content(
+    files: List[Path], patterns: List[str], ignore_case: bool = True
+) -> List[Path]:
+    """
+    Filter a list of files to only include those containing the given patterns.
+
+    Args:
+        files: List of file paths to filter
+        patterns: List of substring patterns to search for
+        ignore_case: Whether to perform case-insensitive matching (default: True)
+
+    Returns:
+        Filtered list of files that contain at least one pattern
+    """
+    if not patterns:
+        return files
+
+    matched_files = []
+    for file_path in files:
+        if file_matches(file_path, patterns, ignore_case):
+            matched_files.append(file_path)
+
+    return matched_files

reposnap-0.8.0/reposnap/core/git_repo.py

@@ -0,0 +1,100 @@
+# src/reposnap/core/git_repo.py
+
+import logging
+from pathlib import Path
+from git import Repo, InvalidGitRepositoryError
+from typing import List
+
+
+class GitRepo:
+    def __init__(self, repo_path: Path):
+        self.repo_path: Path = repo_path.resolve()
+        self.logger = logging.getLogger(__name__)
+
+    def get_git_files(self) -> List[Path]:
+        try:
+            repo: Repo = Repo(self.repo_path, search_parent_directories=True)
+            repo_root: Path = Path(repo.working_tree_dir).resolve()
+            git_files: List[str] = repo.git.ls_files().splitlines()
+            self.logger.debug(f"Git files from {repo_root}: {git_files}")
+            git_files_relative: List[Path] = []
+            for f in git_files:
+                absolute_path: Path = (repo_root / f).resolve()
+                try:
+                    relative_path: Path = absolute_path.relative_to(self.repo_path)
+                    git_files_relative.append(relative_path)
+                except ValueError:
+                    # Skip files not under root_dir
+                    continue
+            return git_files_relative
+        except InvalidGitRepositoryError:
+            self.logger.error(f"Invalid Git repository at: {self.repo_path}")
+            return []
+
+    def get_uncommitted_files(self) -> List[Path]:
+        """
+        Return every *working-copy* file that differs from HEAD - staged,
+        unstaged, untracked, plus everything referenced in `git stash list`.
+        Paths are *relative to* self.repo_path.
+        """
+        try:
+            repo: Repo = Repo(self.repo_path, search_parent_directories=True)
+            repo_root: Path = Path(repo.working_tree_dir).resolve()
+            paths: set = set()
+
+            # Staged changes (diff between index and HEAD)
+            for diff in repo.index.diff("HEAD"):
+                paths.add(diff.a_path or diff.b_path)
+
+            # Unstaged changes (diff between working tree and index)
+            for diff in repo.index.diff(None):
+                paths.add(diff.a_path or diff.b_path)
+
+            # Untracked files
+            paths.update(repo.untracked_files)
+
+            # Stash entries - with performance guard
+            try:
+                stash_refs = repo.git.stash("list", "--format=%gd").splitlines()
+                # Limit stash processing to prevent performance issues
+                max_stashes = 10
+                if len(stash_refs) > max_stashes:
+                    self.logger.warning(
+                        f"Large stash stack detected ({len(stash_refs)} entries). "
+                        f"Processing only the first {max_stashes} stashes."
+                    )
+                    stash_refs = stash_refs[:max_stashes]
+
+                for ref in stash_refs:
+                    if ref.strip():  # Skip empty lines
+                        stash_files = repo.git.diff(
+                            "--name-only", f"{ref}^1", ref
+                        ).splitlines()
+                        paths.update(stash_files)
+            except Exception as e:
+                self.logger.debug(f"Error processing stash entries: {e}")
+
+            # Convert to relative paths and filter existing files
+            relative_paths = []
+            for path_str in paths:
+                if path_str:  # Skip empty strings
+                    absolute_path = (repo_root / path_str).resolve()
+                    try:
+                        relative_path = absolute_path.relative_to(self.repo_path)
+                        if absolute_path.is_file():
+                            relative_paths.append(relative_path)
+                    except ValueError:
+                        # Log warning for paths outside repo root
+                        self.logger.warning(
+                            f"Path {path_str} is outside repository root {self.repo_path}. Skipping."
+                        )
+                        continue
+
+            # Return sorted, deduplicated list for deterministic output
+            result = sorted(set(relative_paths))
+            self.logger.debug(f"Uncommitted files from {repo_root}: {result}")
+            return result
+
+        except InvalidGitRepositoryError:
+            self.logger.error(f"Invalid Git repository at: {self.repo_path}")
+            return []

{reposnap-0.6.5 → reposnap-0.8.0}/reposnap/interfaces/cli.py

@@ -40,6 +40,24 @@ def main():
         default=[],
         help="File/folder patterns to exclude.",
     )
+    parser.add_argument(
+        "-c",
+        "--changes",
+        action="store_true",
+        help="Use only files that are added/modified/untracked/stashed but not yet committed.",
+    )
+    parser.add_argument(
+        "-S",
+        "--contains",
+        nargs="+",
+        default=[],
+        help="Only include files whose contents contain these substrings",
+    )
+    parser.add_argument(
+        "--contains-case",
+        action="store_true",
+        help="Make --contains case-sensitive",
+    )
 
     args = parser.parse_args()