confsync/app/README.md

ConfSync - Intelligent Developer Configuration Sync CLI

A powerful CLI tool that automatically detects, catalogs, and syncs developer configuration files across different tools and machines.

Features

• Auto-detect Config Files: Automatically discover configuration files from popular developer tools like VS Code, Vim, Neovim, Git, Zsh, Fish, Tmux, and more
• Build Unified Manifest: Create structured YAML manifests that catalog all detected configurations
• Validate Configurations: Check configs for conflicts, errors, and inconsistencies before syncing
• Cross-Machine Sync: Synchronize configurations using encrypted storage with Git backend
• Intelligent Merge: Multiple merge strategies that preserve local overrides
• Change History & Rollback: Track changes and enable rollback to previous states

Installation

From PyPI (Coming Soon)

pip install confsync

From Source

git clone https://github.com/yourusername/confsync.git
cd confsync
pip install -e .

Quick Start

1. Detect Configuration Files

Scan your system for configuration files:

confsync detect all

Filter by category:

confsync detect editor     # VS Code, Vim, Neovim, etc.
confsync detect terminal   # Zsh, Fish, Tmux, etc.
confsync detect git        # .gitconfig, .gitignore, etc.
confsync detect shell     # Bash, sh profiles, etc.

2. Create a Manifest

Initialize a configuration manifest:

confsync manifest init -o my_configs.yaml

View manifest contents:

confsync manifest show -p my_configs.yaml

Export manifest with configs:

confsync manifest export -p my_configs.yaml -o backup.zip

3. Validate Configurations

Validate all detected configurations:

confsync validate all

Validate a specific file:

confsync validate file ~/.vimrc

Generate a validation report:

confsync validate report -p my_configs.yaml -o validation_report.txt

4. Synchronize Configurations

Push configurations to a remote repository:

confsync sync push -r https://github.com/username/configs.git -m "Update shell configs"

Pull configurations from a remote repository:

confsync sync pull -r https://github.com/username/configs.git

Encrypt configurations before syncing:

confsync sync push -r https://github.com/username/configs.git --encrypt

5. Merge Configurations

Merge two configuration files:

confsync merge file ~/.vimrc ~/.vimrc.remote -o ~/.vimrc.merged

Preview merge result:

confsync merge preview ~/.vimrc ~/.vimrc.remote

List available merge strategies:

confsync merge strategies

6. View History

View configuration change history:

confsync history list -l 10

Show details of a specific commit:

confsync history show abc1234

Rollback to a previous state:

confsync history rollback abc1234 --dry-run  # Preview first
confsync history rollback abc1234            # Apply rollback

Configuration Detection

ConfSync can detect configurations for the following tools:

Editors

• VS Code (settings.json, keybindings.json)
• Vim (.vimrc, vimrc, .vim/)
• Neovim (init.vim, init.lua, .config/nvim/)

Terminal

• Zsh (.zshrc, .zshenv, .zprofile, .oh-my-zsh/)
• Fish (config.fish, fishfile, .config/fish/)
• Tmux (.tmux.conf, .tmux.conf.local)

Shell

• Bash (.bashrc, .bash_profile, .bash_logout)
• Generic Shell (.profile, .shrc, .exports, .aliases)

Git

• Git Config (.gitconfig, .gitattributes, .gitignore)
• XDG Config (~/.config/git/)

Other

• SSH (~/.ssh/config, ~/.ssh/known_hosts)
• Docker (~/.docker/config.json, ~/.docker/daemon.json)

Merge Strategies

ConfSync supports multiple merge strategies:

Strategy	Description	Use Case
keep_local	Keep local changes, ignore remote	Preserve local overrides
keep_remote	Keep remote changes, ignore local	Overwrite with remote
keep_common	Keep only common lines	Find shared configuration
three_way	Standard three-way merge	When both sides have changes
union	Combine both, remove duplicates	Union of all settings

Environment Variables

Variable	Description
CONFSYNC_HOME	Custom config directory for confsync
CONFSYNC_KEY_FILE	Path to encryption key file
CONFSYNC_REPO	Default sync repository URL
CONFSYNC_VERBOSE	Enable verbose output

Configuration Files

• confsync.yaml - Main configuration file for tool settings
• manifest.yaml - Auto-generated manifest of detected configs
• .confsyncignore - Patterns to exclude from detection
• confsync.toml - User preferences and merge rules

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.