{"id":29288649,"url":"https://github.com/ttrmc/dotkeep","last_synced_at":"2025-07-06T03:08:25.826Z","repository":{"id":300799123,"uuid":"999309257","full_name":"tTrmc/dotkeep","owner":"tTrmc","description":"dotkeep is a minimal, Git-backed dotfiles manager for Linux. It tracks, versions, and syncs your configuration files using a Git repository, while keeping your home directory clean via symlinks. Designed for developers who want simple, reliable, and scriptable dotfile management across machines.","archived":false,"fork":false,"pushed_at":"2025-06-30T23:47:41.000Z","size":85,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-01T00:32:24.408Z","etag":null,"topics":["automation","cli","collaborate","configuration-management","devops","dotfiles","git","linux","python","symlinks","sysadmin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tTrmc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-10T04:14:37.000Z","updated_at":"2025-06-30T23:47:44.000Z","dependencies_parsed_at":"2025-06-23T17:56:03.370Z","dependency_job_id":null,"html_url":"https://github.com/tTrmc/dotkeep","commit_stats":null,"previous_names":["ttrmc/dotkeep"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tTrmc/dotkeep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tTrmc%2Fdotkeep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tTrmc%2Fdotkeep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tTrmc%2Fdotkeep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tTrmc%2Fdotkeep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tTrmc","download_url":"https://codeload.github.com/tTrmc/dotkeep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tTrmc%2Fdotkeep/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263841681,"owners_count":23518490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","collaborate","configuration-management","devops","dotfiles","git","linux","python","symlinks","sysadmin"],"created_at":"2025-07-06T03:08:25.154Z","updated_at":"2025-07-06T03:08:25.812Z","avatar_url":"https://github.com/tTrmc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI version](https://badge.fury.io/py/dotkeep.svg)](https://badge.fury.io/py/dotkeep)\n[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://opensource.org/licenses/GPL-3.0)\n[![CI](https://github.com/tTrmc/dotkeep/workflows/CI/badge.svg)](https://github.com/tTrmc/dotkeep/actions)\n[![Last Commit](https://img.shields.io/github/last-commit/tTrmc/dotkeep.svg)](https://github.com/tTrmc/dotkeep/commits/main)\n[![GitHub issues](https://img.shields.io/github/issues/tTrmc/dotkeep.svg)](https://github.com/tTrmc/dotkeep/issues)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"300\" src=\"dotlogo.png\" alt=\"dotkeep\"\u003e\n  \u003ch3\u003e\n    A minimal \u003cstrong\u003edotfiles\u003c/strong\u003e manager for Linux, backed by Git.\n  \u003c/h3\u003e\n  \u003cp\u003e\n    \u003cem\u003edotkeep\u003c/em\u003e simplifies tracking, versioning, and synchronizing your configuration files across machines.\n  \u003c/p\u003e\n\u003c/div\u003e\n\n## Features\n\n* **Easy setup**: Initialize a local dotkeep repository with a single command.\n* **Git-based**: Provides full version history, branching, and remote synchronization.\n* **File management**: Add and remove dotfiles with automatic symlinking.\n* **Recursive directory support**: Add all dotfiles (optionally recursively) from a directory.\n* **Tracked directories**: Only directories you add are watched for new dotfiles.\n* **Configurable patterns**: Customize which file types to track with include/exclude patterns.\n* **Status overview**: Display untracked, modified, and staged files at a glance.\n* **Configuration management**: Built-in commands to manage file patterns and search settings.\n* **File watching**: Automatic detection and addition of new configuration files.\n* **Diagnostics**: Built-in `diagnose` command for troubleshooting.\n* **Shell completion**: Tab-completion for all commands and options.\n* **Robust \u0026 testable**: Comprehensive test suite with environment isolation.\n* **Portable**: Requires only Python 3.8+ and Git.\n\n---\n\n## Installation\n\n### For End Users (Recommended)\n\n**From PyPI:**\n```bash\npip install dotkeep\n```\n\n**Using pipx (isolated environment):**\n```bash\n# Install pipx if needed\nsudo apt install pipx           # Debian/Ubuntu\n# or\nsudo pacman -S python-pipx      # Arch Linux\n\n# Install dotkeep\npipx install dotkeep\n```\n\n### For Developers\n\n**Quick setup:**\n```bash\ngit clone https://github.com/tTrmc/dotkeep.git\ncd dotkeep\n./setup-dev.sh  # Sets up virtual environment and installs dependencies\n```\n\n**Manual setup:**\n```bash\ngit clone https://github.com/tTrmc/dotkeep.git\ncd dotkeep\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev,test]\"\n```\n\n### Verify Installation\n\n```bash\ndotkeep --help\n```\n\n**Requirements:**\n- Python 3.8 or newer\n- Git\n\n---\n\n\u003e[!CAUTION]\n\u003e**NEVER use public Git repositories with dotkeep.** Your dotfiles often contain:\n\u003e- SSH keys and certificates\n\u003e- API tokens and passwords\n\u003e- Personal file paths and system information\n\u003e- Application configurations with sensitive data\n\u003e\n\u003e**Always use private repositories** or consider excluding sensitive files with dotkeep's pattern configuration.\n\n---\n\n## Quick Start\n\n### Initialize your dotkeep repository\n```bash\n# Local repository only\ndotkeep init\n\n# With private remote repository (recommended)\ndotkeep init --remote git@github.com:yourusername/dotfiles-private.git\n```\n\n### Add your first dotfile\n```bash\n# Add a single file\ndotkeep add .bashrc\n\n# Add all dotfiles in a directory\ndotkeep add .config\n\n# Add and push to remote\ndotkeep add .vimrc --push\n```\n\n### Sync across machines\n```bash\n# Pull latest changes\ndotkeep pull\n\n# Push your changes\ndotkeep push\n```\n\n---\n\n## Usage\n\n### Repository Management\n\n**Initialize:**\n```bash\ndotkeep init                                                    # Local only\ndotkeep init --remote git@github.com:user/dotfiles-private.git # With remote\n```\n\n**Sync:**\n```bash\ndotkeep pull    # Fetch and merge changes\ndotkeep push    # Push local commits\n```\n\n### File Management\n\n**Add files:**\n```bash\ndotkeep add .bashrc              # Single file\ndotkeep add .config              # Directory (recursive by default)\ndotkeep add .config --no-recursive  # Top-level files only\ndotkeep add .vimrc --push        # Add and push\n```\n\n**Remove files:**\n```bash\ndotkeep delete .vimrc            # Remove file\ndotkeep delete .vimrc --push     # Remove and push\n```\n\n**Restore files:**\n```bash\ndotkeep restore .vimrc           # Restore single file\ndotkeep restore .config          # Restore directory\n```\n\n### Information Commands\n\n```bash\ndotkeep status        # Show repository status\ndotkeep list-files    # List tracked files\ndotkeep diagnose      # Troubleshoot issues\ndotkeep version       # Show version\n```\n\n### Advanced Features\n\n**File watching:**\n```bash\ndotkeep watch    # Automatically add new dotfiles in tracked directories\n```\n\n**Shell completion:**\n```bash\ndotkeep --install-completion    # Enable tab completion\n```\n\n### Configuration Management\n\nManage file patterns and search settings:\n\n```bash\ndotkeep config show              # Show current configuration\ndotkeep config list-patterns     # List file patterns\ndotkeep config add-pattern \"*.py\"           # Include Python files\ndotkeep config add-pattern \"*.log\" --type exclude  # Exclude log files\ndotkeep config remove-pattern \"*.py\"        # Remove pattern\ndotkeep config set search_settings.recursive false  # Disable recursion\ndotkeep config reset             # Reset to defaults\ndotkeep config help              # Show detailed help\n```\n\n---\n\n## Project Structure\n\n```\ndotkeep/\n├── src/\n│   └── dotkeep/\n│       ├── __init__.py\n│       ├── cli.py          # Typer-based CLI entry point\n│       ├── core.py         # Core logic for dotfile management\n│       └── watcher.py      # Watchdog-based directory watcher\n├── tests/\n│   ├── conftest.py         # Shared pytest fixtures\n│   ├── test_cli.py         # CLI command tests\n│   ├── test_cli_config.py  # Configuration command tests  \n│   ├── test_core.py        # Core functionality tests\n│   └── test_watcher.py     # File watching tests\n├── pyproject.toml          # Project metadata and dependencies\n├── README.md               # Project documentation\n├── LICENSE                 # GPL-3.0-or-later license\n├── CONTRIBUTING.md         # Contribution guidelines\n└── .gitignore              # Files and directories to exclude\n```\n\nThe `.git` folder is created inside `~/.dotkeep/repo` once you initialize dotkeep.\n\n---\n\n## Configuration\n\ndotkeep uses configurable file patterns to determine which files to track. The configuration is stored in `~/.dotkeep/config.json`.\n\n### Default File Patterns\n\n**Include patterns** (files that will be tracked):\n- `.*` - All dotfiles (files starting with `.`)\n- `*.conf`, `*.config`, `*.cfg`, `*.ini` - Configuration files\n- `*.toml`, `*.yaml`, `*.yml`, `*.json` - Structured config files\n\n**Exclude patterns** (files that will be ignored):\n- `.DS_Store`, `.Trash*` - System files\n- `.cache`, `.git`, `.svn` - Cache and VCS directories  \n- `*.log`, `*.tmp` - Temporary files\n\n### Search Settings\n\n- `recursive`: Search subdirectories recursively (default: `true`)\n- `case_sensitive`: Case-sensitive pattern matching (default: `false`)\n- `follow_symlinks`: Follow symbolic links during search (default: `false`)\n\n### Customizing Configuration\n\nUse the `dotkeep config` commands to customize which files are tracked:\n\n```bash\n# Add Python files to tracking\ndotkeep config add-pattern \"*.py\"\n\n# Exclude compiled Python files  \ndotkeep config add-pattern \"*.pyc\" --type exclude\n\n# Disable recursive search\ndotkeep config set search_settings.recursive false\n```\n\n---\n\n## Testing\n\nTo run the test suite (requires [pytest](https://pytest.org/)):\n\n```bash\npip install pytest\npytest\n```\n\n### Test Coverage\n\nThe project includes comprehensive tests with **73 passing tests** covering:\n\n- **CLI commands**: All dotkeep commands and options\n- **Core functionality**: File management, Git operations, configuration\n- **Configuration management**: Pattern matching, settings, validation  \n- **File watching**: Automatic detection and tracking of new files\n- **Error handling**: Graceful handling of edge cases and failures\n- **Environment isolation**: Tests run in isolated temporary environments\n\n### Development Testing\n\nFor development, install with test dependencies:\n\n```bash\npip install -e \".[dev,test]\"  # Install with all dependencies\npytest -v                     # Run tests with verbose output\npytest --cov=dotkeep          # Run tests with coverage report\nmake test-cov                 # Run tests with HTML coverage report\n```\n\n**Development workflow:**\n\n```bash\nmake help          # Show all available commands\nmake test          # Run tests\nmake lint          # Run code quality checks\nmake format        # Auto-format code\nmake build         # Build distribution packages\n```\n\nThis will discover and run all tests in the `tests/` directory with proper environment isolation and cleanup.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute, report bugs, or suggest features.\n\n---\n\n## License\n\nThis project is distributed under the **GPL-3.0-or-later** license. See the [LICENSE](LICENSE) file for details.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttrmc%2Fdotkeep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fttrmc%2Fdotkeep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttrmc%2Fdotkeep/lists"}