[](https://badge.fury.io/py/loomctl)
[](https://opensource.org/licenses/GPL-3.0)
[](https://github.com/tTrmc/loom/actions)
[](https://github.com/tTrmc/loom/commits/main)
[](https://github.com/tTrmc/loom/issues)
<div align="center">
<h3>
A minimal <strong>dotfiles</strong> manager for Linux, backed by Git.
</h3>
<p>
<em>loom</em> simplifies tracking, versioning, and synchronizing your configuration files across machines.
</p>
</div>
## Features
* **Easy setup**: Initialize a local loom repository with a single command.
* **Git-based**: Provides full version history, branching, and remote synchronization.
* **File management**: Add and remove dotfiles with automatic symlinking.
* **Recursive directory support**: Add all dotfiles (optionally recursively) from a directory.
* **Tracked directories**: Only directories you add are watched for new dotfiles.
* **Configurable patterns**: Customize which file types to track with include/exclude patterns.
* **Status overview**: Display untracked, modified, and staged files at a glance.
* **Configuration management**: Built-in commands to manage file patterns and search settings.
* **File watching**: Automatic detection and addition of new configuration files.
* **Diagnostics**: Built-in `diagnose` command for troubleshooting.
* **Shell completion**: Tab-completion for all commands and options.
* **Robust & testable**: Comprehensive test suite with environment isolation.
* **Portable**: Requires only Python 3.9+ and Git.
---
## Installation
### For End Users (Recommended)
**From PyPI:**
```bash
pip install loomctl
```
**Using pipx (isolated environment):**
```bash
# Install pipx if needed
sudo apt install pipx # Debian/Ubuntu
# or
sudo pacman -S python-pipx # Arch Linux
# Install loomctl
pipx install loomctl
```
### For Developers
**Quick setup:**
```bash
git clone https://github.com/tTrmc/loom.git
cd loom
./setup-dev.sh # Sets up virtual environment and installs dependencies
```
**Manual setup:**
```bash
git clone https://github.com/tTrmc/loom.git
cd loom
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,test]"
```
### Verify Installation
```bash
loom --help
```
**Requirements:**
- Python 3.9 or newer
- Git
---
>[!CAUTION]
>**NEVER use public Git repositories with loom.** Your dotfiles often contain:
>- SSH keys and certificates
>- API tokens and passwords
>- Personal file paths and system information
>- Application configurations with sensitive data
>
>**Always use private repositories** or consider excluding sensitive files with loom's pattern configuration.
---
## Quick Start
### Initialize your loom repository
```bash
# Local repository only
loom init
# With private remote repository (recommended)
loom init --remote git@github.com:yourusername/dotfiles-private.git
```
### Add your first dotfile
```bash
# Add a single file
loom add .bashrc
# Add all dotfiles in a directory
loom add .config
# Add and push to remote
loom add .vimrc --push
```
### Sync across machines
```bash
# Pull latest changes
loom pull
# Push your changes
loom push
```
---
## Usage
### Repository Management
**Initialize:**
```bash
loom init # Local only
loom init --remote git@github.com:user/dotfiles-private.git # With remote
```
**Sync:**
```bash
loom pull # Fetch and merge changes
loom push # Push local commits
```
### File Management
**Add files:**
```bash
loom add .bashrc # Single file
loom add .config # Directory (recursive by default)
loom add .config --no-recursive # Top-level files only
loom add .vimrc --push # Add and push
```
**Remove files:**
```bash
loom delete .vimrc # Remove file
loom delete .vimrc --push # Remove and push
```
**Restore files:**
```bash
loom restore .vimrc # Restore single file
loom restore .config # Restore directory
```
### Information Commands
```bash
loom status # Show repository status
loom list-files # List tracked files
loom diagnose # Troubleshoot issues
loom version # Show version
```
### Advanced Features
**File watching:**
```bash
loom watch # Automatically add new dotfiles in tracked directories
```
**Shell completion:**
```bash
loom --install-completion # Enable tab completion
```
### Configuration Management
Manage file patterns and search settings:
```bash
loom config show # Show current configuration
loom config list-patterns # List file patterns
loom config add-pattern "*.py" # Include Python files
loom config add-pattern "*.log" --type exclude # Exclude log files
loom config remove-pattern "*.py" # Remove pattern
loom config set search_settings.recursive false # Disable recursion
loom config reset # Reset to defaults
loom config help # Show detailed help
```
---
## Project Structure
```
loom/
├── src/
│ └── loom/
│ ├── __init__.py
│ ├── cli.py # Typer-based CLI entry point
│ ├── core.py # Core logic for dotfile management
│ └── watcher.py # Watchdog-based directory watcher
├── tests/
│ ├── conftest.py # Shared pytest fixtures
│ ├── test_cli.py # CLI command tests
│ ├── test_cli_config.py # Configuration command tests
│ ├── test_core.py # Core functionality tests
│ └── test_watcher.py # File watching tests
├── pyproject.toml # Project metadata and dependencies
├── README.md # Project documentation
├── LICENSE # GPL-3.0-or-later license
├── CONTRIBUTING.md # Contribution guidelines
└── .gitignore # Files and directories to exclude
```
The `.git` folder is created inside `~/.loom/repo` once you initialize loom.
---
## Configuration
loom uses configurable file patterns to determine which files to track. The configuration is stored in `~/.loom/config.json`.
### Default File Patterns
**Include patterns** (files that will be tracked):
- `.*` - All dotfiles (files starting with `.`)
- `*.conf`, `*.config`, `*.cfg`, `*.ini` - Configuration files
- `*.toml`, `*.yaml`, `*.yml`, `*.json` - Structured config files
**Exclude patterns** (files that will be ignored):
- `.DS_Store`, `.Trash*` - System files
- `.cache`, `.git`, `.svn` - Cache and VCS directories
- `*.log`, `*.tmp` - Temporary files
### Search Settings
- `recursive`: Search subdirectories recursively (default: `true`)
- `case_sensitive`: Case-sensitive pattern matching (default: `false`)
- `follow_symlinks`: Follow symbolic links during search (default: `false`)
### Customizing Configuration
Use the `loom config` commands to customize which files are tracked:
```bash
# Add Python files to tracking
loom config add-pattern "*.py"
# Exclude compiled Python files
loom config add-pattern "*.pyc" --type exclude
# Disable recursive search
loom config set search_settings.recursive false
```
---
## Testing
To run the test suite (requires [pytest](https://pytest.org/)):
```bash
pip install pytest
pytest
```
### Test Coverage
The project includes comprehensive tests with **73 passing tests** covering:
- **CLI commands**: All loom commands and options
- **Core functionality**: File management, Git operations, configuration
- **Configuration management**: Pattern matching, settings, validation
- **File watching**: Automatic detection and tracking of new files
- **Error handling**: Graceful handling of edge cases and failures
- **Environment isolation**: Tests run in isolated temporary environments
### Development Testing
For development, install with test dependencies:
```bash
pip install -e ".[dev,test]" # Install with all dependencies
pytest -v # Run tests with verbose output
pytest --cov=loom # Run tests with coverage report
make test-cov # Run tests with HTML coverage report
```
**Development workflow:**
```bash
make help # Show all available commands
make test # Run tests
make lint # Run code quality checks
make format # Auto-format code
make build # Build distribution packages
```
This will discover and run all tests in the `tests/` directory with proper environment isolation and cleanup.
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute, report bugs, or suggest features.
---
## License
This project is distributed under the **GPL-3.0-or-later** license. See the [LICENSE](LICENSE) file for details.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "loomctl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "dotfiles, git, configuration, linux, symlink, backup, loomctl",
"author": null,
"author_email": "Moustafa Salem <salemmoustafa442@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/27/6c/d94aa584c1967759851fb1ddc7690c272c2f52c5a9ecee682b6451a9c9d5/loomctl-0.3.0.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/loomctl)\n[](https://opensource.org/licenses/GPL-3.0)\n[](https://github.com/tTrmc/loom/actions)\n[](https://github.com/tTrmc/loom/commits/main)\n[](https://github.com/tTrmc/loom/issues)\n\n<div align=\"center\">\n <h3>\n A minimal <strong>dotfiles</strong> manager for Linux, backed by Git.\n </h3>\n <p>\n <em>loom</em> simplifies tracking, versioning, and synchronizing your configuration files across machines.\n </p>\n</div>\n\n## Features\n\n* **Easy setup**: Initialize a local loom 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 & testable**: Comprehensive test suite with environment isolation.\n* **Portable**: Requires only Python 3.9+ and Git.\n\n---\n\n## Installation\n\n### For End Users (Recommended)\n\n**From PyPI:**\n```bash\npip install loomctl\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 loomctl\npipx install loomctl\n```\n\n### For Developers\n\n**Quick setup:**\n```bash\ngit clone https://github.com/tTrmc/loom.git\ncd loom\n./setup-dev.sh # Sets up virtual environment and installs dependencies\n```\n\n**Manual setup:**\n```bash\ngit clone https://github.com/tTrmc/loom.git\ncd loom\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev,test]\"\n```\n\n### Verify Installation\n\n```bash\nloom --help\n```\n\n**Requirements:**\n- Python 3.9 or newer\n- Git\n\n---\n\n>[!CAUTION]\n>**NEVER use public Git repositories with loom.** Your dotfiles often contain:\n>- SSH keys and certificates\n>- API tokens and passwords\n>- Personal file paths and system information\n>- Application configurations with sensitive data\n>\n>**Always use private repositories** or consider excluding sensitive files with loom's pattern configuration.\n\n---\n\n## Quick Start\n\n### Initialize your loom repository\n```bash\n# Local repository only\nloom init\n\n# With private remote repository (recommended)\nloom init --remote git@github.com:yourusername/dotfiles-private.git\n```\n\n### Add your first dotfile\n```bash\n# Add a single file\nloom add .bashrc\n\n# Add all dotfiles in a directory\nloom add .config\n\n# Add and push to remote\nloom add .vimrc --push\n```\n\n### Sync across machines\n```bash\n# Pull latest changes\nloom pull\n\n# Push your changes\nloom push\n```\n\n---\n\n## Usage\n\n### Repository Management\n\n**Initialize:**\n```bash\nloom init # Local only\nloom init --remote git@github.com:user/dotfiles-private.git # With remote\n```\n\n**Sync:**\n```bash\nloom pull # Fetch and merge changes\nloom push # Push local commits\n```\n\n### File Management\n\n**Add files:**\n```bash\nloom add .bashrc # Single file\nloom add .config # Directory (recursive by default)\nloom add .config --no-recursive # Top-level files only\nloom add .vimrc --push # Add and push\n```\n\n**Remove files:**\n```bash\nloom delete .vimrc # Remove file\nloom delete .vimrc --push # Remove and push\n```\n\n**Restore files:**\n```bash\nloom restore .vimrc # Restore single file\nloom restore .config # Restore directory\n```\n\n### Information Commands\n\n```bash\nloom status # Show repository status\nloom list-files # List tracked files\nloom diagnose # Troubleshoot issues\nloom version # Show version\n```\n\n### Advanced Features\n\n**File watching:**\n```bash\nloom watch # Automatically add new dotfiles in tracked directories\n```\n\n**Shell completion:**\n```bash\nloom --install-completion # Enable tab completion\n```\n\n### Configuration Management\n\nManage file patterns and search settings:\n\n```bash\nloom config show # Show current configuration\nloom config list-patterns # List file patterns\nloom config add-pattern \"*.py\" # Include Python files\nloom config add-pattern \"*.log\" --type exclude # Exclude log files\nloom config remove-pattern \"*.py\" # Remove pattern\nloom config set search_settings.recursive false # Disable recursion\nloom config reset # Reset to defaults\nloom config help # Show detailed help\n```\n\n---\n\n## Project Structure\n\n```\nloom/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 loom/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 cli.py # Typer-based CLI entry point\n\u2502 \u251c\u2500\u2500 core.py # Core logic for dotfile management\n\u2502 \u2514\u2500\u2500 watcher.py # Watchdog-based directory watcher\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 conftest.py # Shared pytest fixtures\n\u2502 \u251c\u2500\u2500 test_cli.py # CLI command tests\n\u2502 \u251c\u2500\u2500 test_cli_config.py # Configuration command tests \n\u2502 \u251c\u2500\u2500 test_core.py # Core functionality tests\n\u2502 \u2514\u2500\u2500 test_watcher.py # File watching tests\n\u251c\u2500\u2500 pyproject.toml # Project metadata and dependencies\n\u251c\u2500\u2500 README.md # Project documentation\n\u251c\u2500\u2500 LICENSE # GPL-3.0-or-later license\n\u251c\u2500\u2500 CONTRIBUTING.md # Contribution guidelines\n\u2514\u2500\u2500 .gitignore # Files and directories to exclude\n```\n\nThe `.git` folder is created inside `~/.loom/repo` once you initialize loom.\n\n---\n\n## Configuration\n\nloom uses configurable file patterns to determine which files to track. The configuration is stored in `~/.loom/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 `loom config` commands to customize which files are tracked:\n\n```bash\n# Add Python files to tracking\nloom config add-pattern \"*.py\"\n\n# Exclude compiled Python files \nloom config add-pattern \"*.pyc\" --type exclude\n\n# Disable recursive search\nloom 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 loom 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=loom # 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",
"bugtrack_url": null,
"license": null,
"summary": "loomctl is a minimal, Git-backed dotfiles manager for Linux",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/tTrmc/loom/releases",
"Documentation": "https://github.com/tTrmc/loom#readme",
"Homepage": "https://github.com/tTrmc/loom",
"Issues": "https://github.com/tTrmc/loom/issues",
"Repository": "https://github.com/tTrmc/loom"
},
"split_keywords": [
"dotfiles",
" git",
" configuration",
" linux",
" symlink",
" backup",
" loomctl"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9e4fdfb73a7faa45a3b63b7de6089aa54d2102a6bf8b9b062bd1d359a0c4384b",
"md5": "2d8a18b417b46ef5711dcae6695d0010",
"sha256": "f0f86e85ae81c4f26e7ed6ff9d6a71a11a66a5630e9ad1ae4f04b7a9def7e27c"
},
"downloads": -1,
"filename": "loomctl-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d8a18b417b46ef5711dcae6695d0010",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 37615,
"upload_time": "2025-07-09T02:29:02",
"upload_time_iso_8601": "2025-07-09T02:29:02.504050Z",
"url": "https://files.pythonhosted.org/packages/9e/4f/dfb73a7faa45a3b63b7de6089aa54d2102a6bf8b9b062bd1d359a0c4384b/loomctl-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "276cd94aa584c1967759851fb1ddc7690c272c2f52c5a9ecee682b6451a9c9d5",
"md5": "d068ca8b25521bf26f2de6137aa2378b",
"sha256": "1624de3cb94defa51f2e85a44495b4d338c6faa1b115275d288dc1b80b4f81d6"
},
"downloads": -1,
"filename": "loomctl-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "d068ca8b25521bf26f2de6137aa2378b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 57739,
"upload_time": "2025-07-09T02:29:04",
"upload_time_iso_8601": "2025-07-09T02:29:04.554273Z",
"url": "https://files.pythonhosted.org/packages/27/6c/d94aa584c1967759851fb1ddc7690c272c2f52c5a9ecee682b6451a9c9d5/loomctl-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 02:29:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tTrmc",
"github_project": "loom",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "loomctl"
}
JSON
