# verctrl
Lightweight version control CLI tool with smart file detection and PyQt6 GUI
## Overview
verctrl is a simple yet powerful version control tool designed for quick file backups with intelligent file detection. It provides both command-line and GUI interfaces for managing file versions.
## Features
- **Smart File Detection**: Automatically detect files based on various strategies
- **PyQt6 GUI**: Modern graphical interface for file selection
- **Gitignore Support**: Respects .gitignore patterns
- **Multiple Naming Schemes**: Version numbers, timestamps, or simple naming
- **Automatic Cleanup**: Configurable history retention
- **Statistics Dashboard**: Track your backups and files
- **Cross-platform**: Works on Windows, macOS, and Linux
## Installation
### Requirements
- Python 3.7+
- PyQt6 (optional, for GUI features)
- lucide-py (optional, for better icons)
### Install Dependencies
```bash
# Core functionality only
pip install verctrl
# With GUI support
pip install PyQt6
# With enhanced icons
pip install lucide-py
```
## Quick Start
### 1. Initialize Configuration
```bash
verctrl --init
```
This creates a `verctrl.json` configuration file in your current directory.
### 2. Select Files
#### Using GUI (Recommended)
```bash
verctrl --select
```
This launches a modern file browser with:
- Tree view of your project
- Smart detection strategies
- Search and filter capabilities
- Visual file type indicators
#### Using Smart Add (CLI)
```bash
# Add source files (respects .gitignore)
verctrl --smart-add smart
# Add Python files only
verctrl --smart-add python
# Add recently modified files
verctrl --smart-add recent --days 7
# Add web-related files
verctrl --smart-add web
# Add all non-excluded files
verctrl --smart-add all
```
### 3. Create Backup
```bash
verctrl --new
```
This creates backups of all tracked files according to your configuration.
### 4. List Backups
```bash
verctrl --list
```
Shows all existing backups with size and modification date.
### 5. Restore Backup
```bash
verctrl --restore filename-v1.txt
```
Restores a specific backup to its original location.
## Configuration
The `verctrl.json` file contains:
```json
{
"files": [
"src/main.py",
"config.yaml",
"README.md"
],
"backup_dir": ".verctrl_backups",
"naming_scheme": "version",
"keep_history": 5,
"create_new_file": false
}
```
### Configuration Options
| Option | Description | Default |
|--------|-------------|---------|
| `files` | List of files to track | `[]` |
| `backup_dir` | Directory for backups | `.verctrl_backups` |
| `naming_scheme` | `version`, `timestamp`, or `simple` | `version` |
| `keep_history` | Number of backups to keep | `5` |
| `create_new_file` | Create empty file after backup | `false` |
### Naming Schemes
- **version**: `file-v1.txt`, `file-v2.txt`, `file-v3.txt`
- **timestamp**: `file-20240101-143022.txt`
- **simple**: `file-old.txt` (overwrites previous backup)
## Smart Detection Strategies
### smart (Recommended)
Detects source code files while respecting .gitignore patterns. Excludes:
- Version control directories (.git, .svn)
- Dependencies (node_modules, venv)
- Build artifacts (dist, build)
- IDE files (.idea, .vscode)
- Binary files
### source
All source code files regardless of .gitignore:
- Programming languages (.py, .js, .java, .cpp, etc.)
- Web files (.html, .css, .scss)
- Configuration (.json, .yaml, .toml)
- Documentation (.md, .rst, .txt)
### recent
Files modified within specified days:
```bash
verctrl --smart-add recent --days 7
```
### python
Python files only (.py)
### web
Web-related files:
- HTML, CSS, SCSS, SASS, LESS
- JavaScript, TypeScript
- Vue, Svelte components
### all
All files except default exclusions
## Command Reference
### Initialize
```bash
verctrl --init
```
Creates default configuration file.
### File Selection
```bash
# GUI selector
verctrl --select
# Smart add with strategy
verctrl --smart-add STRATEGY [--days N]
```
### Backup Operations
```bash
# Create new backup
verctrl --new
# List all backups
verctrl --list
# Restore specific backup
verctrl --restore FILENAME
```
### Information
```bash
# Show statistics
verctrl --stats
# Use custom config file
verctrl --config path/to/config.json
```
## Statistics
The `--stats` command shows:
- Number of tracked files
- Existing vs missing files
- Total size of tracked files
- File type distribution
- Backup count and size
- Oldest and newest backups
- Configuration summary
Example output:
```
============================================================
Statistics
============================================================
Tracked Files: 15
Existing: 14
Missing: 1
Total Size: 2.45 MB
Top File Types:
.py: 8
.json: 3
.md: 2
.yaml: 1
.txt: 1
Backup Directory: .verctrl_backups
Total Backups: 42
Total Size: 12.3 MB
Oldest: 2024-01-15 10:30:00
Newest: 2024-01-20 14:22:15
Configuration:
Naming Scheme: version
Keep History: 5
Create New File: False
============================================================
```
## Default Exclusions
verctrl automatically excludes:
### Version Control
- .git, .svn, .hg, .bzr
### Dependencies
- node_modules, bower_components, vendor
- venv, .venv, env, .env
### Python
- __pycache__, *.pyc, *.pyo
- *.egg-info, dist, build
### IDE
- .idea, .vscode, .vs
- *.swp, *.swo, *~
### OS
- .DS_Store, Thumbs.db, desktop.ini
### Build Artifacts
- *.o, *.so, *.dll, *.exe
### Temporary
- tmp, temp, .tmp, .cache
- *.log, logs
- *.bak, *.backup, *.old
## Gitignore Support
verctrl respects .gitignore patterns in your project root:
```gitignore
# Example .gitignore
node_modules/
*.log
.env
dist/
```
Files matching these patterns will be excluded from smart detection.
## GUI Features
The PyQt6 GUI provides:
### File Tree
- Hierarchical view of your project
- File type icons
- Size and modification date
- Checkbox selection
### Smart Detection Panel
- Strategy selector
- Days parameter for recent files
- One-click application
### Search and Filter
- Real-time search
- Filter by name or extension
### Bulk Operations
- Select all / Deselect all
- Expand all / Collapse all
### Visual Indicators
- Color-coded file types
- Size formatting
- Previously tracked files highlighted
## Use Cases
### Project Development
Track source files while excluding dependencies:
```bash
verctrl --init
verctrl --smart-add smart
verctrl --new
```
### Configuration Management
Track config files only:
```bash
verctrl --init
# Manually edit verctrl.json to add config files
verctrl --new
```
### Document Versioning
Track recently modified documents:
```bash
verctrl --init
verctrl --smart-add recent --days 7
verctrl --new
```
### Web Development
Track web project files:
```bash
verctrl --init
verctrl --smart-add web
verctrl --new
```
## Best Practices
1. **Use Smart Detection**: Start with `--smart-add smart` for most projects
2. **Review Selection**: Use `--select` GUI to review auto-detected files
3. **Regular Backups**: Run `verctrl --new` before major changes
4. **Check Statistics**: Use `--stats` to monitor backup growth
5. **Adjust History**: Set `keep_history` based on your needs
6. **Custom Config**: Use `--config` for different project profiles
## Troubleshooting
### PyQt6 Not Found
```bash
pip install PyQt6
```
### Permission Denied
Ensure you have write permissions for:
- Configuration file location
- Backup directory
- Tracked files
### Missing Files Warning
Files listed in config but not found on disk will show warnings. Update config with:
```bash
verctrl --select
```
### Large Backup Size
Reduce `keep_history` or exclude large files:
```json
{
"keep_history": 3
}
```
## Advanced Usage
### Multiple Configurations
```bash
# Development config
verctrl --config dev.json --new
# Production config
verctrl --config prod.json --new
```
## Comparison with Git
| Feature | verctrl | Git |
|---------|---------|-----|
| Setup | Single command | Multiple commands |
| Learning Curve | Minimal | Moderate to steep |
| File Selection | GUI + Smart detection | Manual staging |
| Backup Speed | Fast | Fast |
| History | Configurable limit | Unlimited |
| Collaboration | No | Yes |
| Branching | No | Yes |
| Best For | Quick backups, solo work | Team projects, complex history |
## License
MIT License - See LICENSE file for details
Raw data
{
"_id": null,
"home_page": "https://github.com/ren/verctrl",
"name": "verctrl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "version-control, backup, cli, gui, pyqt6",
"author": "REN",
"author_email": "REN <totallynotbedlessnoob@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/03/e8/f0e68a17c4bce856a81d7254c80c04f23c2e98fed18802ce2bb5c97b109d/verctrl-1.0.0.tar.gz",
"platform": null,
"description": "# verctrl\r\n\r\nLightweight version control CLI tool with smart file detection and PyQt6 GUI\r\n\r\n## Overview\r\n\r\nverctrl is a simple yet powerful version control tool designed for quick file backups with intelligent file detection. It provides both command-line and GUI interfaces for managing file versions.\r\n\r\n## Features\r\n\r\n- **Smart File Detection**: Automatically detect files based on various strategies\r\n- **PyQt6 GUI**: Modern graphical interface for file selection\r\n- **Gitignore Support**: Respects .gitignore patterns\r\n- **Multiple Naming Schemes**: Version numbers, timestamps, or simple naming\r\n- **Automatic Cleanup**: Configurable history retention\r\n- **Statistics Dashboard**: Track your backups and files\r\n- **Cross-platform**: Works on Windows, macOS, and Linux\r\n\r\n## Installation\r\n\r\n### Requirements\r\n\r\n- Python 3.7+\r\n- PyQt6 (optional, for GUI features)\r\n- lucide-py (optional, for better icons)\r\n\r\n### Install Dependencies\r\n\r\n```bash\r\n# Core functionality only\r\npip install verctrl\r\n\r\n# With GUI support\r\npip install PyQt6\r\n\r\n# With enhanced icons\r\npip install lucide-py\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Initialize Configuration\r\n\r\n```bash\r\nverctrl --init\r\n```\r\n\r\nThis creates a `verctrl.json` configuration file in your current directory.\r\n\r\n### 2. Select Files\r\n\r\n#### Using GUI (Recommended)\r\n\r\n```bash\r\nverctrl --select\r\n```\r\n\r\nThis launches a modern file browser with:\r\n- Tree view of your project\r\n- Smart detection strategies\r\n- Search and filter capabilities\r\n- Visual file type indicators\r\n\r\n#### Using Smart Add (CLI)\r\n\r\n```bash\r\n# Add source files (respects .gitignore)\r\nverctrl --smart-add smart\r\n\r\n# Add Python files only\r\nverctrl --smart-add python\r\n\r\n# Add recently modified files\r\nverctrl --smart-add recent --days 7\r\n\r\n# Add web-related files\r\nverctrl --smart-add web\r\n\r\n# Add all non-excluded files\r\nverctrl --smart-add all\r\n```\r\n\r\n### 3. Create Backup\r\n\r\n```bash\r\nverctrl --new\r\n```\r\n\r\nThis creates backups of all tracked files according to your configuration.\r\n\r\n### 4. List Backups\r\n\r\n```bash\r\nverctrl --list\r\n```\r\n\r\nShows all existing backups with size and modification date.\r\n\r\n### 5. Restore Backup\r\n\r\n```bash\r\nverctrl --restore filename-v1.txt\r\n```\r\n\r\nRestores a specific backup to its original location.\r\n\r\n## Configuration\r\n\r\nThe `verctrl.json` file contains:\r\n\r\n```json\r\n{\r\n \"files\": [\r\n \"src/main.py\",\r\n \"config.yaml\",\r\n \"README.md\"\r\n ],\r\n \"backup_dir\": \".verctrl_backups\",\r\n \"naming_scheme\": \"version\",\r\n \"keep_history\": 5,\r\n \"create_new_file\": false\r\n}\r\n```\r\n\r\n### Configuration Options\r\n\r\n| Option | Description | Default |\r\n|--------|-------------|---------|\r\n| `files` | List of files to track | `[]` |\r\n| `backup_dir` | Directory for backups | `.verctrl_backups` |\r\n| `naming_scheme` | `version`, `timestamp`, or `simple` | `version` |\r\n| `keep_history` | Number of backups to keep | `5` |\r\n| `create_new_file` | Create empty file after backup | `false` |\r\n\r\n### Naming Schemes\r\n\r\n- **version**: `file-v1.txt`, `file-v2.txt`, `file-v3.txt`\r\n- **timestamp**: `file-20240101-143022.txt`\r\n- **simple**: `file-old.txt` (overwrites previous backup)\r\n\r\n## Smart Detection Strategies\r\n\r\n### smart (Recommended)\r\n\r\nDetects source code files while respecting .gitignore patterns. Excludes:\r\n- Version control directories (.git, .svn)\r\n- Dependencies (node_modules, venv)\r\n- Build artifacts (dist, build)\r\n- IDE files (.idea, .vscode)\r\n- Binary files\r\n\r\n### source\r\n\r\nAll source code files regardless of .gitignore:\r\n- Programming languages (.py, .js, .java, .cpp, etc.)\r\n- Web files (.html, .css, .scss)\r\n- Configuration (.json, .yaml, .toml)\r\n- Documentation (.md, .rst, .txt)\r\n\r\n### recent\r\n\r\nFiles modified within specified days:\r\n\r\n```bash\r\nverctrl --smart-add recent --days 7\r\n```\r\n\r\n### python\r\n\r\nPython files only (.py)\r\n\r\n### web\r\n\r\nWeb-related files:\r\n- HTML, CSS, SCSS, SASS, LESS\r\n- JavaScript, TypeScript\r\n- Vue, Svelte components\r\n\r\n### all\r\n\r\nAll files except default exclusions\r\n\r\n## Command Reference\r\n\r\n### Initialize\r\n\r\n```bash\r\nverctrl --init\r\n```\r\n\r\nCreates default configuration file.\r\n\r\n### File Selection\r\n\r\n```bash\r\n# GUI selector\r\nverctrl --select\r\n\r\n# Smart add with strategy\r\nverctrl --smart-add STRATEGY [--days N]\r\n```\r\n\r\n### Backup Operations\r\n\r\n```bash\r\n# Create new backup\r\nverctrl --new\r\n\r\n# List all backups\r\nverctrl --list\r\n\r\n# Restore specific backup\r\nverctrl --restore FILENAME\r\n```\r\n\r\n### Information\r\n\r\n```bash\r\n# Show statistics\r\nverctrl --stats\r\n\r\n# Use custom config file\r\nverctrl --config path/to/config.json\r\n```\r\n\r\n## Statistics\r\n\r\nThe `--stats` command shows:\r\n\r\n- Number of tracked files\r\n- Existing vs missing files\r\n- Total size of tracked files\r\n- File type distribution\r\n- Backup count and size\r\n- Oldest and newest backups\r\n- Configuration summary\r\n\r\nExample output:\r\n\r\n```\r\n============================================================\r\nStatistics\r\n============================================================\r\n\r\nTracked Files: 15\r\n Existing: 14\r\n Missing: 1\r\n Total Size: 2.45 MB\r\n\r\n Top File Types:\r\n .py: 8\r\n .json: 3\r\n .md: 2\r\n .yaml: 1\r\n .txt: 1\r\n\r\nBackup Directory: .verctrl_backups\r\n Total Backups: 42\r\n Total Size: 12.3 MB\r\n Oldest: 2024-01-15 10:30:00\r\n Newest: 2024-01-20 14:22:15\r\n\r\nConfiguration:\r\n Naming Scheme: version\r\n Keep History: 5\r\n Create New File: False\r\n\r\n============================================================\r\n```\r\n\r\n## Default Exclusions\r\n\r\nverctrl automatically excludes:\r\n\r\n### Version Control\r\n- .git, .svn, .hg, .bzr\r\n\r\n### Dependencies\r\n- node_modules, bower_components, vendor\r\n- venv, .venv, env, .env\r\n\r\n### Python\r\n- __pycache__, *.pyc, *.pyo\r\n- *.egg-info, dist, build\r\n\r\n### IDE\r\n- .idea, .vscode, .vs\r\n- *.swp, *.swo, *~\r\n\r\n### OS\r\n- .DS_Store, Thumbs.db, desktop.ini\r\n\r\n### Build Artifacts\r\n- *.o, *.so, *.dll, *.exe\r\n\r\n### Temporary\r\n- tmp, temp, .tmp, .cache\r\n- *.log, logs\r\n- *.bak, *.backup, *.old\r\n\r\n## Gitignore Support\r\n\r\nverctrl respects .gitignore patterns in your project root:\r\n\r\n```gitignore\r\n# Example .gitignore\r\nnode_modules/\r\n*.log\r\n.env\r\ndist/\r\n```\r\n\r\nFiles matching these patterns will be excluded from smart detection.\r\n\r\n## GUI Features\r\n\r\nThe PyQt6 GUI provides:\r\n\r\n### File Tree\r\n- Hierarchical view of your project\r\n- File type icons\r\n- Size and modification date\r\n- Checkbox selection\r\n\r\n### Smart Detection Panel\r\n- Strategy selector\r\n- Days parameter for recent files\r\n- One-click application\r\n\r\n### Search and Filter\r\n- Real-time search\r\n- Filter by name or extension\r\n\r\n### Bulk Operations\r\n- Select all / Deselect all\r\n- Expand all / Collapse all\r\n\r\n### Visual Indicators\r\n- Color-coded file types\r\n- Size formatting\r\n- Previously tracked files highlighted\r\n\r\n## Use Cases\r\n\r\n### Project Development\r\n\r\nTrack source files while excluding dependencies:\r\n\r\n```bash\r\nverctrl --init\r\nverctrl --smart-add smart\r\nverctrl --new\r\n```\r\n\r\n### Configuration Management\r\n\r\nTrack config files only:\r\n\r\n```bash\r\nverctrl --init\r\n# Manually edit verctrl.json to add config files\r\nverctrl --new\r\n```\r\n\r\n### Document Versioning\r\n\r\nTrack recently modified documents:\r\n\r\n```bash\r\nverctrl --init\r\nverctrl --smart-add recent --days 7\r\nverctrl --new\r\n```\r\n\r\n### Web Development\r\n\r\nTrack web project files:\r\n\r\n```bash\r\nverctrl --init\r\nverctrl --smart-add web\r\nverctrl --new\r\n```\r\n\r\n## Best Practices\r\n\r\n1. **Use Smart Detection**: Start with `--smart-add smart` for most projects\r\n2. **Review Selection**: Use `--select` GUI to review auto-detected files\r\n3. **Regular Backups**: Run `verctrl --new` before major changes\r\n4. **Check Statistics**: Use `--stats` to monitor backup growth\r\n5. **Adjust History**: Set `keep_history` based on your needs\r\n6. **Custom Config**: Use `--config` for different project profiles\r\n\r\n## Troubleshooting\r\n\r\n### PyQt6 Not Found\r\n\r\n```bash\r\npip install PyQt6\r\n```\r\n\r\n### Permission Denied\r\n\r\nEnsure you have write permissions for:\r\n- Configuration file location\r\n- Backup directory\r\n- Tracked files\r\n\r\n### Missing Files Warning\r\n\r\nFiles listed in config but not found on disk will show warnings. Update config with:\r\n\r\n```bash\r\nverctrl --select\r\n```\r\n\r\n### Large Backup Size\r\n\r\nReduce `keep_history` or exclude large files:\r\n\r\n```json\r\n{\r\n \"keep_history\": 3\r\n}\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Multiple Configurations\r\n\r\n```bash\r\n# Development config\r\nverctrl --config dev.json --new\r\n\r\n# Production config\r\nverctrl --config prod.json --new\r\n```\r\n\r\n## Comparison with Git\r\n\r\n| Feature | verctrl | Git |\r\n|---------|---------|-----|\r\n| Setup | Single command | Multiple commands |\r\n| Learning Curve | Minimal | Moderate to steep |\r\n| File Selection | GUI + Smart detection | Manual staging |\r\n| Backup Speed | Fast | Fast |\r\n| History | Configurable limit | Unlimited |\r\n| Collaboration | No | Yes |\r\n| Branching | No | Yes |\r\n| Best For | Quick backups, solo work | Team projects, complex history |\r\n\r\n## License\r\n\r\nMIT License - See LICENSE file for details\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightweight version control CLI tool with smart file detection and PyQt6 GUI",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/ren/verctrl",
"Issues": "https://github.com/ren/verctrl/issues",
"Repository": "https://github.com/ren/verctrl"
},
"split_keywords": [
"version-control",
" backup",
" cli",
" gui",
" pyqt6"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9c8142baa476f61b85bf346f092b40a6be1bf0dd686ed25c397d3fcb69213a3d",
"md5": "7bce23b2fa677b1372379d443e640912",
"sha256": "ed78ff70718dae799c1e2adc20821ab85ee185469049225b03299812be8f186a"
},
"downloads": -1,
"filename": "verctrl-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7bce23b2fa677b1372379d443e640912",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18664,
"upload_time": "2025-10-20T11:25:41",
"upload_time_iso_8601": "2025-10-20T11:25:41.214162Z",
"url": "https://files.pythonhosted.org/packages/9c/81/42baa476f61b85bf346f092b40a6be1bf0dd686ed25c397d3fcb69213a3d/verctrl-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "03e8f0e68a17c4bce856a81d7254c80c04f23c2e98fed18802ce2bb5c97b109d",
"md5": "cc9280826c2761c6851c06a4b9532f9f",
"sha256": "f2e3ecb5536397939649786738eb938fd9956e2f42324e6387d3acce0d9bbec7"
},
"downloads": -1,
"filename": "verctrl-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "cc9280826c2761c6851c06a4b9532f9f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18599,
"upload_time": "2025-10-20T11:25:43",
"upload_time_iso_8601": "2025-10-20T11:25:43.499027Z",
"url": "https://files.pythonhosted.org/packages/03/e8/f0e68a17c4bce856a81d7254c80c04f23c2e98fed18802ce2bb5c97b109d/verctrl-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 11:25:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ren",
"github_project": "verctrl",
"github_not_found": true,
"lcname": "verctrl"
}
JSON
