# versctrl
Lightweight version control CLI tool with smart file detection and PyQt6 GUI
## Overview
versctrl 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)
### Method 1: Install from PyPI (Recommended)
```bash
# Install versctrl globally
pip install versctrl
# With GUI support
pip install versctrl[gui]
# With all optional features
pip install versctrl[all]
```
After installation, `versctrl` will be available globally in your terminal from any directory.
### Verify Installation
```bash
# Check if versctrl is accessible
versctrl --help
# Check version
versctrl --version
```
### Setting Up PATH (If Needed)
If `versctrl` is not recognized after installation, you may need to add Python's Scripts directory to your PATH:
#### Windows
```powershell
# Find Python Scripts directory
python -m site --user-site
# Add to PATH (PowerShell - Admin)
$pythonScripts = python -c "import site; print(site.USER_BASE + '\\Scripts')"
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$pythonScripts", "User")
# Restart your terminal
```
Or manually:
1. Open "Environment Variables" settings
2. Edit "Path" under User variables
3. Add: `C:\Users\YourUsername\AppData\Local\Programs\Python\Python3X\Scripts`
4. Click OK and restart terminal
#### macOS/Linux
```bash
# Find Python Scripts directory
python3 -m site --user-base
# Add to PATH (add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# Reload shell configuration
source ~/.bashrc
# For zsh users
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
#### Verify PATH Setup
```bash
# Check if versctrl is in PATH
which versctrl # macOS/Linux
where versctrl # Windows
# Should output something like:
# /home/username/.local/bin/versctrl
# or C:\Users\Username\AppData\Local\Programs\Python\Python3X\Scripts\versctrl.exe
```
### Optional Dependencies
```bash
# Install GUI support separately
pip install PyQt6
# Install enhanced icons
pip install lucide-py
# Install all optional dependencies
pip install PyQt6 lucide-py
```
### Upgrading
```bash
# Upgrade to latest version
pip install --upgrade versctrl
# Upgrade with all features
pip install --upgrade versctrl[all]
```
### Uninstallation
```bash
pip uninstall versctrl
```
## Quick Start
### 1. Initialize Configuration
```bash
# Navigate to your project directory
cd /path/to/your/project
# Initialize versctrl
versctrl --init
```
This creates a `versctrl.json` configuration file in your current directory.
### 2. Select Files
#### Using GUI (Recommended)
```bash
versctrl --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)
versctrl --smart-add smart
# Add Python files only
versctrl --smart-add python
# Add recently modified files
versctrl --smart-add recent --days 7
# Add web-related files
versctrl --smart-add web
# Add all non-excluded files
versctrl --smart-add all
```
### 3. Create Backup
```bash
versctrl --new
```
This creates backups of all tracked files according to your configuration.
### 4. List Backups
```bash
versctrl --list
```
Shows all existing backups with size and modification date.
### 5. Restore Backup
```bash
versctrl --restore filename-v1.txt
```
Restores a specific backup to its original location.
## Global Usage
Once installed, you can use `versctrl` from anywhere:
```bash
# Backup your documents
cd ~/Documents/important-project
versctrl --init
versctrl --smart-add smart
versctrl --new
# Backup your code
cd ~/Code/my-app
versctrl --init
versctrl --select
versctrl --new
# Use different configs for different projects
cd ~/project1
versctrl --config project1.json --new
cd ~/project2
versctrl --config project2.json --new
```
## Configuration
The `versctrl.json` file contains:
```json
{
"files": [
"src/main.py",
"config.yaml",
"README.md"
],
"backup_dir": ".versctrl_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 | `.versctrl_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
versctrl --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
versctrl --init
```
Creates default configuration file.
### File Selection
```bash
# GUI selector
versctrl --select
# Smart add with strategy
versctrl --smart-add STRATEGY [--days N]
```
### Backup Operations
```bash
# Create new backup
versctrl --new
# List all backups
versctrl --list
# Restore specific backup
versctrl --restore FILENAME
```
### Information
```bash
# Show statistics
versctrl --stats
# Show version
versctrl --version
# Show help
versctrl --help
# Use custom config file
versctrl --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: .versctrl_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
versctrl 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
versctrl 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
cd /path/to/project
versctrl --init
versctrl --smart-add smart
versctrl --new
```
### Configuration Management
Track config files only:
```bash
cd /path/to/configs
versctrl --init
# Manually edit versctrl.json to add config files
versctrl --new
```
### Document Versioning
Track recently modified documents:
```bash
cd ~/Documents/thesis
versctrl --init
versctrl --smart-add recent --days 7
versctrl --new
```
### Web Development
Track web project files:
```bash
cd ~/Sites/my-website
versctrl --init
versctrl --smart-add web
versctrl --new
```
### Multiple Projects
Manage backups across different projects:
```bash
# Setup project 1
cd ~/project1
versctrl --init
versctrl --smart-add smart
versctrl --new
# Setup project 2
cd ~/project2
versctrl --init
versctrl --smart-add python
versctrl --new
# Later, create backups from anywhere
cd ~/project1 && versctrl --new
cd ~/project2 && versctrl --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 `versctrl --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
7. **Per-Project Setup**: Initialize versctrl in each project directory
8. **Backup Before Updates**: Create backups before major refactoring
## Troubleshooting
### Command Not Found
If `versctrl` is not recognized:
```bash
# Check if pip installed it correctly
pip show versctrl
# Check Python Scripts directory
python -m site --user-base
# Try running with python -m
python -m versctrl --help
```
Then add the Scripts directory to your PATH (see installation section).
### PyQt6 Not Found
```bash
pip install PyQt6
```
### Permission Denied
Ensure you have write permissions for:
- Configuration file location
- Backup directory
- Tracked files
On Unix systems:
```bash
chmod +x ~/.local/bin/versctrl
```
### Missing Files Warning
Files listed in config but not found on disk will show warnings. Update config with:
```bash
versctrl --select
```
### Large Backup Size
Reduce `keep_history` or exclude large files:
```json
{
"keep_history": 3
}
```
### Import Errors
If you get import errors:
```bash
# Reinstall with all dependencies
pip uninstall versctrl
pip install versctrl[all]
```
## Advanced Usage
### Multiple Configurations
```bash
# Development config
versctrl --config dev.json --new
# Production config
versctrl --config prod.json --new
# Testing config
versctrl --config test.json --new
```
### Automation with Scripts
#### Bash Script (Linux/macOS)
```bash
#!/bin/bash
# backup-all.sh
projects=(
"$HOME/Code/project1"
"$HOME/Code/project2"
"$HOME/Documents/thesis"
)
for project in "${projects[@]}"; do
echo "Backing up $project..."
cd "$project" && versctrl --new
done
```
#### PowerShell Script (Windows)
```powershell
# backup-all.ps1
$projects = @(
"$env:USERPROFILE\Code\project1",
"$env:USERPROFILE\Code\project2",
"$env:USERPROFILE\Documents\thesis"
)
foreach ($project in $projects) {
Write-Host "Backing up $project..."
Set-Location $project
versctrl --new
}
```
### Scheduled Backups
#### Linux/macOS (cron)
```bash
# Edit crontab
crontab -e
# Add daily backup at 6 PM
0 18 * * * cd /path/to/project && /home/user/.local/bin/versctrl --new
# Add hourly backup during work hours
0 9-17 * * 1-5 cd /path/to/project && /home/user/.local/bin/versctrl --new
```
#### Windows (Task Scheduler)
1. Open Task Scheduler
2. Create Basic Task
3. Set trigger (daily, weekly, etc.)
4. Action: Start a program
5. Program: `versctrl`
6. Arguments: `--new`
7. Start in: `C:\path\to\project`
## Comparison with Git
| Feature | versctrl | 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 |
| Merge Conflicts | No | Yes |
| Global Install | Yes | 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/v7ren/verctrl",
"name": "versctrl",
"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/cc/d0/5a92bc23e04931037dc9bb9a2e9f5e6dea29c75e1e22ef97a7827a7f16d4/versctrl-1.0.2.tar.gz",
"platform": null,
"description": "\r\n# versctrl\r\n\r\nLightweight version control CLI tool with smart file detection and PyQt6 GUI\r\n\r\n## Overview\r\n\r\nversctrl 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### Method 1: Install from PyPI (Recommended)\r\n\r\n```bash\r\n# Install versctrl globally\r\npip install versctrl\r\n\r\n# With GUI support\r\npip install versctrl[gui]\r\n\r\n# With all optional features\r\npip install versctrl[all]\r\n```\r\n\r\nAfter installation, `versctrl` will be available globally in your terminal from any directory.\r\n\r\n\r\n### Verify Installation\r\n\r\n```bash\r\n# Check if versctrl is accessible\r\nversctrl --help\r\n\r\n# Check version\r\nversctrl --version\r\n```\r\n\r\n### Setting Up PATH (If Needed)\r\n\r\nIf `versctrl` is not recognized after installation, you may need to add Python's Scripts directory to your PATH:\r\n\r\n#### Windows\r\n\r\n```powershell\r\n# Find Python Scripts directory\r\npython -m site --user-site\r\n\r\n# Add to PATH (PowerShell - Admin)\r\n$pythonScripts = python -c \"import site; print(site.USER_BASE + '\\\\Scripts')\"\r\n[Environment]::SetEnvironmentVariable(\"Path\", $env:Path + \";$pythonScripts\", \"User\")\r\n\r\n# Restart your terminal\r\n```\r\n\r\nOr manually:\r\n1. Open \"Environment Variables\" settings\r\n2. Edit \"Path\" under User variables\r\n3. Add: `C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python3X\\Scripts`\r\n4. Click OK and restart terminal\r\n\r\n#### macOS/Linux\r\n\r\n```bash\r\n# Find Python Scripts directory\r\npython3 -m site --user-base\r\n\r\n# Add to PATH (add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile)\r\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\r\n\r\n# Reload shell configuration\r\nsource ~/.bashrc\r\n\r\n# For zsh users\r\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc\r\nsource ~/.zshrc\r\n```\r\n\r\n#### Verify PATH Setup\r\n\r\n```bash\r\n# Check if versctrl is in PATH\r\nwhich versctrl # macOS/Linux\r\nwhere versctrl # Windows\r\n\r\n# Should output something like:\r\n# /home/username/.local/bin/versctrl\r\n# or C:\\Users\\Username\\AppData\\Local\\Programs\\Python\\Python3X\\Scripts\\versctrl.exe\r\n```\r\n\r\n### Optional Dependencies\r\n\r\n```bash\r\n# Install GUI support separately\r\npip install PyQt6\r\n\r\n# Install enhanced icons\r\npip install lucide-py\r\n\r\n# Install all optional dependencies\r\npip install PyQt6 lucide-py\r\n```\r\n\r\n### Upgrading\r\n\r\n```bash\r\n# Upgrade to latest version\r\npip install --upgrade versctrl\r\n\r\n# Upgrade with all features\r\npip install --upgrade versctrl[all]\r\n```\r\n\r\n### Uninstallation\r\n\r\n```bash\r\npip uninstall versctrl\r\n```\r\n\r\n## Quick Start\r\n\r\n### 1. Initialize Configuration\r\n\r\n```bash\r\n# Navigate to your project directory\r\ncd /path/to/your/project\r\n\r\n# Initialize versctrl\r\nversctrl --init\r\n```\r\n\r\nThis creates a `versctrl.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\nversctrl --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\nversctrl --smart-add smart\r\n\r\n# Add Python files only\r\nversctrl --smart-add python\r\n\r\n# Add recently modified files\r\nversctrl --smart-add recent --days 7\r\n\r\n# Add web-related files\r\nversctrl --smart-add web\r\n\r\n# Add all non-excluded files\r\nversctrl --smart-add all\r\n```\r\n\r\n### 3. Create Backup\r\n\r\n```bash\r\nversctrl --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\nversctrl --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\nversctrl --restore filename-v1.txt\r\n```\r\n\r\nRestores a specific backup to its original location.\r\n\r\n## Global Usage\r\n\r\nOnce installed, you can use `versctrl` from anywhere:\r\n\r\n```bash\r\n# Backup your documents\r\ncd ~/Documents/important-project\r\nversctrl --init\r\nversctrl --smart-add smart\r\nversctrl --new\r\n\r\n# Backup your code\r\ncd ~/Code/my-app\r\nversctrl --init\r\nversctrl --select\r\nversctrl --new\r\n\r\n# Use different configs for different projects\r\ncd ~/project1\r\nversctrl --config project1.json --new\r\n\r\ncd ~/project2\r\nversctrl --config project2.json --new\r\n```\r\n\r\n## Configuration\r\n\r\nThe `versctrl.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\": \".versctrl_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 | `.versctrl_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\nversctrl --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\nversctrl --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\nversctrl --select\r\n\r\n# Smart add with strategy\r\nversctrl --smart-add STRATEGY [--days N]\r\n```\r\n\r\n### Backup Operations\r\n\r\n```bash\r\n# Create new backup\r\nversctrl --new\r\n\r\n# List all backups\r\nversctrl --list\r\n\r\n# Restore specific backup\r\nversctrl --restore FILENAME\r\n```\r\n\r\n### Information\r\n\r\n```bash\r\n# Show statistics\r\nversctrl --stats\r\n\r\n# Show version\r\nversctrl --version\r\n\r\n# Show help\r\nversctrl --help\r\n\r\n# Use custom config file\r\nversctrl --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: .versctrl_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\nversctrl 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\nversctrl 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\ncd /path/to/project\r\nversctrl --init\r\nversctrl --smart-add smart\r\nversctrl --new\r\n```\r\n\r\n### Configuration Management\r\n\r\nTrack config files only:\r\n\r\n```bash\r\ncd /path/to/configs\r\nversctrl --init\r\n# Manually edit versctrl.json to add config files\r\nversctrl --new\r\n```\r\n\r\n### Document Versioning\r\n\r\nTrack recently modified documents:\r\n\r\n```bash\r\ncd ~/Documents/thesis\r\nversctrl --init\r\nversctrl --smart-add recent --days 7\r\nversctrl --new\r\n```\r\n\r\n### Web Development\r\n\r\nTrack web project files:\r\n\r\n```bash\r\ncd ~/Sites/my-website\r\nversctrl --init\r\nversctrl --smart-add web\r\nversctrl --new\r\n```\r\n\r\n### Multiple Projects\r\n\r\nManage backups across different projects:\r\n\r\n```bash\r\n# Setup project 1\r\ncd ~/project1\r\nversctrl --init\r\nversctrl --smart-add smart\r\nversctrl --new\r\n\r\n# Setup project 2\r\ncd ~/project2\r\nversctrl --init\r\nversctrl --smart-add python\r\nversctrl --new\r\n\r\n# Later, create backups from anywhere\r\ncd ~/project1 && versctrl --new\r\ncd ~/project2 && versctrl --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 `versctrl --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\n7. **Per-Project Setup**: Initialize versctrl in each project directory\r\n8. **Backup Before Updates**: Create backups before major refactoring\r\n\r\n## Troubleshooting\r\n\r\n### Command Not Found\r\n\r\nIf `versctrl` is not recognized:\r\n\r\n```bash\r\n# Check if pip installed it correctly\r\npip show versctrl\r\n\r\n# Check Python Scripts directory\r\npython -m site --user-base\r\n\r\n# Try running with python -m\r\npython -m versctrl --help\r\n```\r\n\r\nThen add the Scripts directory to your PATH (see installation section).\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\nOn Unix systems:\r\n```bash\r\nchmod +x ~/.local/bin/versctrl\r\n```\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\nversctrl --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### Import Errors\r\n\r\nIf you get import errors:\r\n\r\n```bash\r\n# Reinstall with all dependencies\r\npip uninstall versctrl\r\npip install versctrl[all]\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Multiple Configurations\r\n\r\n```bash\r\n# Development config\r\nversctrl --config dev.json --new\r\n\r\n# Production config\r\nversctrl --config prod.json --new\r\n\r\n# Testing config\r\nversctrl --config test.json --new\r\n```\r\n\r\n### Automation with Scripts\r\n\r\n#### Bash Script (Linux/macOS)\r\n\r\n```bash\r\n#!/bin/bash\r\n# backup-all.sh\r\n\r\nprojects=(\r\n \"$HOME/Code/project1\"\r\n \"$HOME/Code/project2\"\r\n \"$HOME/Documents/thesis\"\r\n)\r\n\r\nfor project in \"${projects[@]}\"; do\r\n echo \"Backing up $project...\"\r\n cd \"$project\" && versctrl --new\r\ndone\r\n```\r\n\r\n#### PowerShell Script (Windows)\r\n\r\n```powershell\r\n# backup-all.ps1\r\n\r\n$projects = @(\r\n \"$env:USERPROFILE\\Code\\project1\",\r\n \"$env:USERPROFILE\\Code\\project2\",\r\n \"$env:USERPROFILE\\Documents\\thesis\"\r\n)\r\n\r\nforeach ($project in $projects) {\r\n Write-Host \"Backing up $project...\"\r\n Set-Location $project\r\n versctrl --new\r\n}\r\n```\r\n\r\n### Scheduled Backups\r\n\r\n#### Linux/macOS (cron)\r\n\r\n```bash\r\n# Edit crontab\r\ncrontab -e\r\n\r\n# Add daily backup at 6 PM\r\n0 18 * * * cd /path/to/project && /home/user/.local/bin/versctrl --new\r\n\r\n# Add hourly backup during work hours\r\n0 9-17 * * 1-5 cd /path/to/project && /home/user/.local/bin/versctrl --new\r\n```\r\n\r\n#### Windows (Task Scheduler)\r\n\r\n1. Open Task Scheduler\r\n2. Create Basic Task\r\n3. Set trigger (daily, weekly, etc.)\r\n4. Action: Start a program\r\n5. Program: `versctrl`\r\n6. Arguments: `--new`\r\n7. Start in: `C:\\path\\to\\project`\r\n\r\n## Comparison with Git\r\n\r\n| Feature | versctrl | 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| Merge Conflicts | No | Yes |\r\n| Global Install | Yes | Yes |\r\n| Best For | Quick backups, solo work | Team projects, complex history |\r\n\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.2",
"project_urls": {
"Homepage": "https://github.com/v7ren/verctrl",
"Issues": "https://github.com/v7ren/verctrl/issues",
"Repository": "https://github.com/v7ren/verctrl"
},
"split_keywords": [
"version-control",
" backup",
" cli",
" gui",
" pyqt6"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "72705eea74c97687f5a37d6291c3df494a74d510801384b043869457a0a245b0",
"md5": "95312f82ce78398dfb123ecf75dd552d",
"sha256": "e176ff4b3cfcc171e17a9dc58f811d4bf8a78df45b0f82294376c948986897b0"
},
"downloads": -1,
"filename": "versctrl-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95312f82ce78398dfb123ecf75dd552d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19159,
"upload_time": "2025-10-20T16:43:47",
"upload_time_iso_8601": "2025-10-20T16:43:47.695105Z",
"url": "https://files.pythonhosted.org/packages/72/70/5eea74c97687f5a37d6291c3df494a74d510801384b043869457a0a245b0/versctrl-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ccd05a92bc23e04931037dc9bb9a2e9f5e6dea29c75e1e22ef97a7827a7f16d4",
"md5": "32eda35c6610495f498c5bb695702ba2",
"sha256": "53d73e0ffbf8d59cc3df202b07c7beadca8798ff998986b9d0b6739494354a05"
},
"downloads": -1,
"filename": "versctrl-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "32eda35c6610495f498c5bb695702ba2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19740,
"upload_time": "2025-10-20T16:43:48",
"upload_time_iso_8601": "2025-10-20T16:43:48.600312Z",
"url": "https://files.pythonhosted.org/packages/cc/d0/5a92bc23e04931037dc9bb9a2e9f5e6dea29c75e1e22ef97a7827a7f16d4/versctrl-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 16:43:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "v7ren",
"github_project": "verctrl",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "versctrl"
}
JSON
