dotz 0.3.0__tar.gz

dotz-0.3.0/CHANGELOG.md

@@ -0,0 +1,175 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note**: This project was renamed from "dotkeep" to "dotz" starting with version 0.4.0.
+> Historical entries below may reference the old "dotkeep" command name.
+
+## [Unreleased]
+
+- **BREAKING**: Project renamed from "dotkeep" to "dotz"
+- Command changed from `dotkeep` to `dotz`  
+- Configuration directory changed from `~/.dotkeep` to `~/.dotz`
+- Package name changed from `dotkeepctl` to `dotz`
+
+- Future features will be listed here
+
+## [0.3.0] - 2025-07-05
+
+### Professional release with comprehensive improvements and modern packaging
+
+### Added
+
+- Comprehensive test suite with 73+ passing tests
+- Environment isolation for robust testing
+- Configuration management system with `dotkeep config` commands
+- File pattern customization (include/exclude patterns)
+- Search settings configuration (recursive, case-sensitive, follow-symlinks)
+- Improved error handling and diagnostics
+- Modern Python packaging with `pyproject.toml`
+- GitHub Actions CI/CD pipeline
+- Professional documentation (CONTRIBUTING.md, PUBLISHING.md)
+- Development tooling (Makefile, setup-dev.sh)
+
+### Changed
+
+- Refactored path management for better testability
+- Updated license field in pyproject.toml to modern SPDX string format
+- Enhanced fixtures for test isolation
+- Improved documentation with configuration examples
+- Professional CLI output (removed unprofessional emojis, kept ✓ marks)
+- Complete rewrite for robustness and maintainability
+
+### Fixed
+
+- Test pollution issues between test runs
+- Path resolution in different environments
+- Configuration persistence and cleanup
+
+## [0.2.0] - 2025-07-05
+
+### Highlights
+
+#### **Recursive Directory Support**
+
+- Add all dotfiles in a directory and its subdirectories with `dotkeep add <dir>`
+- Use `--no-recursive` to restrict to top-level dotfiles only
+
+#### **Tracked Directories & Watcher**
+
+- Only explicitly added directories are monitored for new dotfiles
+- `dotkeep watch` automatically adds new dotfiles created in tracked directories
+
+#### **Diagnostics**
+
+- New `dotkeep diagnose` command checks for common setup and git issues, providing actionable guidance
+
+#### **Enhanced Git Integration**
+
+- Improved error messages for common git issues (e.g., divergent branches, missing upstream, rejected pushes)
+- Upstream branch is set automatically on first push if needed
+
+#### **Improved CLI Experience**
+
+- `--quiet` flag suppresses output for scripting and automation
+- `--push` flag available for `add`, `delete`, and `restore` to immediately push changes
+- `dotkeep version` displays the current version
+- `dotkeep --install-completion` enables shell tab-completion for all commands and options
+
+#### **Commit Efficiency**
+
+- Adding multiple dotfiles in a directory now results in a single commit, improving repository clarity
+
+### Improvements & Fixes
+
+- Robust handling of symlinks and prevention of watcher loops
+- Tracked directories are automatically removed from tracking when all dotfiles inside are deleted
+- Consistent, user-friendly CLI output
+- Expanded and improved test suite for CLI and core logic
+
+### Requirements
+
+- Python 3.8+
+- Git
+
+### Installation
+
+```bash
+git clone https://github.com/tTrmc/dotkeep.git
+cd dotkeep
+pip install -e .
+```
+
+### Getting Started
+
+```bash
+dotkeep init
+dotkeep add .bashrc
+dotkeep status
+dotkeep push
+```
+
+See the README for full usage instructions and advanced features.
+
+## [0.1.0] - First Public Release
+
+### dotkeep is a minimal, Git-backed dotfiles manager for Linux
+
+This is the first public release.
+
+### Features
+
+- **Easy setup:**  
+  Initialize your dotfiles repo with `dotkeep init`.  
+  The Git repository is stored in `~/.dotkeep/repo`.
+
+- **Git-based versioning:**  
+  All changes are tracked with Git.  
+  Supports local history, branching, and remote sync.
+
+- **Add and remove dotfiles:**  
+  - `dotkeep add <file>`: Copies a file into the repo, commits it, and symlinks it from your home directory.
+  - `dotkeep delete <file>`: Removes the symlink and the file from the repo and Git.
+
+- **Symlink management:**  
+  Automatically replaces managed files in `$HOME` with symlinks to the repo.
+
+- **Status overview:**  
+  `dotkeep status` shows untracked, modified, and staged files in your dotkeep repo.
+
+- **Remote sync:**  
+  - `dotkeep push`: Push all local commits to your remote.
+  - `dotkeep pull`: Pull and merge changes from your remote.
+
+- **Restore files:**  
+  `dotkeep restore <file>`: Re-create the symlink for a managed file if it's missing.
+
+- **List tracked files:**  
+  `dotkeep list-files`: See all files currently managed by dotkeep.
+
+### Requirements (v0.1.0)
+
+- Python 3.8+
+- Git
+
+### Installation (v0.1.0)
+
+```bash
+git clone https://github.com/tTrmc/dotkeep.git
+cd dotkeep
+pip install -e .
+```
+
+### Getting Started (v0.1.0)
+
+```bash
+dotkeep init
+dotkeep add .bashrc
+dotkeep status
+dotkeep push
+```
+
+See the README for full usage instructions.

dotz-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,363 @@
+# Contributing to dotz
+
+Thank you for your interest in contributing to dotz! I welcome all pull requests, bug reports, and feature suggestions.
+
+## Table of Contents
+
+* [Getting Started](#getting-started)
+* [Development Setup](#development-setup)
+* [Development Tools](#development-tools)
+* [Code Style](#code-style)
+* [Testing](#testing)
+* [Commit Guidelines](#commit-guidelines)
+* [Pull Requests](#pull-requests)
+* [Reporting Issues](#reporting-issues)
+* [Feature Requests](#feature-requests)
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+
+   ```bash
+   git clone https://github.com/yourusername/dotz.git
+   cd dotz
+   ```
+
+3. **Set up the development environment**:
+
+   ```bash
+   ./setup-dev.sh  # This sets up virtual environment and installs dependencies
+   ```
+
+   Or manually:
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   pip install -e ".[dev,test]"
+   ```
+
+4. **Create a new branch** for your changes:
+
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+5. **Make your changes** locally in this new branch
+6. **Test your changes** thoroughly
+7. **Submit a pull request**
+
+## Development Setup
+
+### Prerequisites
+
+* Python 3.9 or newer
+* Git
+* Virtual environment (recommended)
+
+### Quick Setup
+
+```bash
+git clone https://github.com/yourusername/dotz.git
+cd dotz
+./setup-dev.sh
+```
+
+This will:
+
+* Create a virtual environment
+* Install development dependencies
+* Set up pre-commit hooks (if available)
+* Run initial tests to verify setup
+
+## Development Tools
+
+This project uses modern Python development tools:
+
+* **pytest**: Testing framework with comprehensive coverage
+* **black**: Code formatting for consistent style
+* **isort**: Import sorting and organization
+* **flake8**: Linting for code quality
+* **mypy**: Static type checking
+* **GitHub Actions**: Automated CI/CD pipeline
+
+### Running Development Commands
+
+```bash
+make help          # Show all available commands
+make test          # Run the complete test suite
+make lint          # Check code style and quality
+make format        # Auto-format code with black and isort
+make type-check    # Run mypy type checking
+make build         # Build distribution packages
+make clean         # Clean build artifacts
+```
+
+Run all quality checks:
+
+```bash
+make test lint type-check
+```
+
+## Code Style
+
+### Python Code Guidelines
+
+* Follow [PEP 8](https://peps.python.org/pep-0008/) guidelines
+* Use type hints for function parameters and return values
+* Write docstrings for public functions and classes
+* Keep functions focused and reasonably sized
+* Use descriptive variable and function names
+
+### Formatting
+
+Code is automatically formatted using **black** and **isort**:
+
+```bash
+make format  # Auto-format all code
+```
+
+### Import Organization
+
+* Standard library imports first
+* Third-party imports second
+* Local/project imports last
+* Use absolute imports when possible
+
+Example:
+
+```python
+import os
+import sys
+from pathlib import Path
+
+import typer
+from git import Repo
+
+from dotz.core import DotzCore
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run with coverage report
+pytest --cov=dotz
+
+# Run specific test file
+pytest tests/test_core.py
+
+# Run specific test
+pytest tests/test_core.py::test_init_repo
+```
+
+### Writing Tests
+
+When adding new features or fixing bugs:
+
+* **Add tests** for new functionality
+* **Follow existing patterns** in the test suite
+* **Use descriptive test names** that explain what is being tested
+* **Test both success and failure scenarios**
+* **Ensure tests are isolated** and don't depend on external state
+* **Mock external dependencies** when appropriate
+
+Test file structure:
+
+```python
+import pytest
+from unittest.mock import Mock, patch
+
+from dotz.core import DotzCore
+
+
+class TestFeatureName:
+    def test_successful_operation(self):
+        # Test the happy path
+        pass
+    
+    def test_handles_error_condition(self):
+        # Test error handling
+        pass
+```
+
+### Test Environment
+
+* Tests run in isolated temporary directories
+* No interference with your actual dotz configuration
+* Automatic cleanup after test completion
+
+## Commit Guidelines
+
+### Commit Message Format
+
+Use clear, descriptive commit messages:
+
+* **Use imperative mood**: "Add feature" not "Added feature"
+* **Be specific**: Explain what changed and why
+* **Keep first line under 72 characters**
+* **Add detail in body if needed**
+
+Good examples:
+
+```text
+Add support for encrypted backup storage
+
+Fix symlink validation for broken links
+
+Update documentation for new config options
+
+Refactor file pattern matching for better performance
+```
+
+### Commit Organization
+
+* **One logical change per commit**
+* **Group related changes together**
+* **Separate formatting changes from logic changes**
+* **Include tests with the feature they test**
+
+## Pull Requests
+
+### Before Submitting
+
+1. **Ensure all tests pass**:
+
+   ```bash
+   make test
+   ```
+
+2. **Check code quality**:
+
+   ```bash
+   make lint
+   ```
+
+3. **Format your code**:
+
+   ```bash
+   make format
+   ```
+
+4. **Update documentation** if needed
+
+### Submitting Your PR
+
+1. **Push your branch** to your fork:
+
+   ```bash
+   git push -u origin feature/my-new-feature
+   ```
+
+2. **Open a pull request** on GitHub with:
+
+   * Clear description of changes
+   * Link to related issues (if any)
+   * Screenshots or examples (if relevant)
+   * Testing instructions (if needed)
+
+### PR Review Process
+
+* I'll review PRs as soon as possible
+* May request changes or ask questions
+* Once approved, I'll merge the changes
+* Your contribution will be acknowledged
+
+## Reporting Issues
+
+### Bug Reports
+
+When reporting bugs, please include:
+
+* **Clear description** of the problem
+* **Steps to reproduce** the issue
+* **Expected vs actual behavior**
+* **Environment information**:
+  * Operating system and version
+  * Python version (`python --version`)
+  * dotz version (`dotz version`)
+  * Relevant configuration details
+* **Error messages or logs** (if any)
+* **Additional context** that might be helpful
+
+### Issue Templates
+
+Use the provided issue templates when available:
+
+* **Bug Report**: For reporting problems
+* **Feature Request**: For suggesting new features
+* **Documentation**: For documentation improvements
+
+## Feature Requests
+
+When suggesting new features:
+
+* **Describe the use case**: What problem does this solve?
+* **Provide examples**: How would you use this feature?
+* **Consider alternatives**: Are there existing ways to achieve this?
+* **Think about implementation**: Any ideas on how it could work?
+
+### Feature Discussion
+
+* Features are discussed in GitHub issues
+* Community input is welcome
+* Implementation complexity is considered
+* Backward compatibility is important
+
+## Development Guidelines
+
+### Project Goals
+
+Keep these principles in mind:
+
+* **Simplicity**: dotz should be easy to use and understand
+* **Reliability**: Robust error handling and comprehensive testing
+* **Performance**: Efficient operations, especially for large configurations
+* **Compatibility**: Support for different Linux distributions and Python versions
+* **Security**: Safe handling of sensitive configuration files
+
+### Code Organization
+
+* **Keep modules focused**: Each module should have a clear purpose
+* **Minimize dependencies**: Only add dependencies when necessary
+* **Document interfaces**: Clear function and class documentation
+* **Handle errors gracefully**: Provide helpful error messages
+
+## Getting Help
+
+### Resources
+
+* **README.md**: Project overview and basic usage
+* **Issues**: Search existing issues for similar problems
+* **Code**: Read the source code for implementation details
+* **Tests**: Look at tests for usage examples
+
+### Communication
+
+* **GitHub Issues**: Primary communication channel
+* **Pull Request discussions**: For code-specific questions
+* **Email**: For security issues only (see SECURITY.md)
+
+### Response Times
+
+* I aim to respond to issues and PRs within a few days
+* Complex changes may take longer to review
+* Feel free to ping if you haven't heard back in a week
+
+## Recognition
+
+Contributors are acknowledged in:
+
+* **README.md acknowledgments section**
+* **Git commit history**
+* **Release notes** (for significant contributions)
+
+Thank you for helping make dotz better!