Metadata-Version: 2.1
Name: wbck
Version: 2.2.0
Summary: a command line utility to perform workspace backup
Home-page: https://github.com/argoyal/wbck.git
Author: Arpit Goyal
Author-email: arpitgoyal.iitkgp@outlook.com
License: UNKNOWN
Description: # Workspace Backup and Restoration Tool (wbck)
        
        ![Workspace Backup and Restoration Tool](https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSJwvW-RmC7SNL2jCyhiW7vJHTEE_3XXj6RDH8QASwliQ&s)
        
        ## Introduction
        
        Workspace Backup and Restoration Tool (wbck) is a utility designed to ease machine migrations and workspace setup without the fear of data loss. It backs up and restores your code folders, documents, and any other paths — each to the source that fits best (git remote, S3, or local disk).
        
        Whether you're transitioning to a new machine or setting up a development environment elsewhere, wbck ensures your workspace is replicated exactly where it was, minimizing downtime and ensuring continuity in your workflow.
        
        A *workspace* is all the data associated with a specific project or company context. You can define as many workspaces as you need and switch between them with a single command.
        
        ## Features
        
        - **Per-path backup sources** — each folder in your workspace can back up to git, S3, or local storage independently.
        - **Git-aware backup** — pushes unpushed commits to the remote, and falls back to a zip archive for repos with no push access or untracked changes.
        - **Exact restoration** — each folder is restored to its configured path relative to the workspace root, preserving your directory structure.
        - **Resume-safe restore** — already-restored paths are skipped on re-runs, so a failed restore can be continued from where it left off.
        - **Workspace archival** — disabled workspaces are compressed into a single full archive for long-term storage.
        - **Dry-run mode** — validate all paths and surface per-file issues without performing any backup.
        - **Workspace contexts** — switch between multiple workspace configurations without specifying a config path on every command, similar to `kubectl config use-context`.
        - **Targeted operations** — back up or restore a single folder by name without touching the rest of the workspace.
        - **Config sync** — reconcile `paths_to_include` with the folders actually on disk: auto-register new folders and cloned repos, detect moves and added git remotes, and prompt before dropping missing entries.
        
        ## Installation
        
        ```bash
        pip install wbck
        ```
        
        ```bash
        wbck --help
        usage: wbck [-h] [--version] {create,backup,restore,sync,cache} ...
        
        Application to backup and restore my workspace data using config files
        
        Commands:
          create    creates a new workspace
          backup    backup your workspace
          restore   restore your workspace
          sync      reconcile workspace configs with the folders on disk
          cache     manage workspace contexts
        ```
        
        ## Configuration
        
        Create a config file (`<workspace>_config.json`) in a configs directory. Here is a complete example:
        
        ```json
        {
          "name": "my",
          "enabled": 1,
          "workspace_path": "/Users/arpit",
          "default_source": "s3",
          "paths_to_include": [
            {
              "folder_name": "portfolio-website",
              "folder_path": "codes/portfolio-website",
              "backup_source": ["git"],
              "backup_location": "git@github.com:argoyal/portfolio-website.git",
              "enabled": 1
            },
            {
              "folder_name": "documents",
              "folder_path": "documents",
              "backup_source": ["s3"],
              "enabled": 1
            },
            {
              "folder_name": "notes",
              "folder_path": "documents/notes",
              "backup_source": ["local"],
              "enabled": 1
            }
          ],
          "paths_to_exclude": [".venv", "node_modules", "build", "dist"],
          "source_credentials": {
            "s3": {
              "root_path": "my-backup-bucket",
              "aws_key": "",
              "aws_secret": "",
              "aws_profile": "myaws"
            },
            "local": {
              "root_path": "/Volumes/ExternalDrive/backups"
            },
            "git": {
              "auth_method": "ssh"
            }
          }
        }
        ```
        
        ### Config reference
        
        | Field | Description |
        |---|---|
        | `name` | Workspace identifier (e.g. `my`, `work`, `acme`) |
        | `enabled` | `1` = active workspace, `0` = archived (backup creates a single full-workspace zip) |
        | `workspace_path` | Absolute path to the directory that contains the workspace folder |
        | `default_source` | Fallback source (`s3` or `local`) used when a git push fails or for workspace archival |
        | `paths_to_exclude` | Folder/file names to skip when zipping (applied globally) |
        
        ### `paths_to_include` entries
        
        | Field | Description |
        |---|---|
        | `folder_name` | Display name and prefix used for backup file naming |
        | `folder_path` | Path to the folder **relative to** `<workspace_path>/<name>` |
        | `backup_source` | List of sources: `"git"`, `"s3"`, `"local"` |
        | `backup_location` | Git remote URL (required when `backup_source` includes `"git"`) |
        | `enabled` | `0` skips this path during backup and restore |
        | `pin_source` | Optional. `1` stops `wbck sync` from ever changing this entry's `backup_source` (e.g. keep a third-party clone on S3 despite its git remote) |
        
        ### `source_credentials`
        
        **S3:**
        
        | Field | Description |
        |---|---|
        | `root_path` | S3 bucket name |
        | `aws_profile` | AWS CLI profile name (preferred over key/secret) |
        | `aws_key` / `aws_secret` | AWS credentials (used if no profile is set) |
        
        **Local:**
        
        | Field | Description |
        |---|---|
        | `root_path` | Absolute path to the local backup directory |
        
        **Git:**
        
        | Field | Description |
        |---|---|
        | `auth_method` | `"ssh"` or `"https"` |
        
        ## Usage
        
        ### 1. Workspace Contexts
        
        Point wbck at a folder containing all your config files once, then switch between workspaces by name — no need to pass `--config-path` on every command.
        
        ```bash
        # Set the config folder
        wbck cache set --config-folder $HOME/.configs/
        # Config folder set to: /home/user/.configs/
        # Available configs: my, work
        # Switch with: wbck cache use <name>
        
        # List available workspaces (* = active)
        wbck cache show
        # Config folder: /home/user/.configs/
        #
        #   * my
        #     work
        
        # Switch active workspace
        wbck cache use work
        
        # Clear the context cache
        wbck cache clear
        ```
        
        You can always override the active context for a single command:
        
        ```bash
        wbck backup --config-path /path/to/specific_config.json
        ```
        
        ### 2. Backup
        
        ```bash
        # Backup the active workspace
        wbck backup
        
        # Backup a specific workspace by name
        wbck backup my
        
        # Backup all workspaces in the config folder
        wbck backup --all
        
        # Backup a single folder only
        wbck backup --folder-name documents
        
        # Validate paths without performing the backup
        wbck backup --dry-run
        ```
        
        **How git backup works:** wbck pushes any unpushed commits to the configured remote. If the repo has uncommitted changes or the remote is not writable, it commits everything to a local `local-dump` branch and falls back to a zip upload via `default_source`.
        
        **Dry-run** zips every file in each path to surface encoding or permission issues without uploading anything.
        
        ### 3. Restore
        
        ```bash
        # Restore the active workspace
        wbck restore
        
        # Restore a specific workspace by name
        wbck restore my
        
        # Restore all workspaces in the config folder
        wbck restore --all
        
        # Restore a single folder only
        wbck restore --folder-name documents
        
        # Keep the backup on the remote after restoring
        wbck restore --keep-remote-data
        
        # Force restore a disabled (archived) workspace
        wbck restore --force
        ```
        
        **Resume safety:** if a restore run is interrupted, already-restored paths are automatically skipped on the next run, so you can re-run `wbck restore` to pick up from the failure point.
        
        **`--force`** restores from the full-workspace archive created when `enabled` is set to `0` in the config.
        
        ### 4. Sync Configs with the Filesystem
        
        `wbck sync` diffs each workspace's `paths_to_include` against the folders actually on disk and reconciles the config. A folder is considered a candidate when it is a direct child of a directory that already contains managed entries, so sync learns the depth of your layout from the config itself.
        
        ```bash
        # Reconcile every workspace in the config folder (interactive)
        wbck sync
        
        # Reconcile a single workspace by name
        wbck sync my
        
        # Preview without writing anything
        wbck sync --dry-run
        
        # Apply additions/updates/moves without prompting
        wbck sync --yes
        
        # Register/refresh a single folder; the owning workspace is inferred
        # from the path (intended for shell hooks after mkdir / git clone)
        wbck sync --path ~/my/codes/new-repo --yes
        ```
        
        What sync detects:
        
        - **New folder** — registered with the workspace's `default_source`; if it is a git repo with an `origin` remote it is registered as `git` with `backup_location` set.
        - **Remote added later** — a registered non-git folder that gains an `origin` remote can be switched to `git` (covers the `mkdir` → work → `git remote add` flow). In a full sync this always prompts per entry — `git` / `both` (git plus the current source) / `keep once` / `pin` — and choosing `pin` writes `"pin_source": 1` into the entry so sync never proposes the flip again. Hook mode (`--path`) applies the flip automatically unless the entry is pinned.
        - **Move** — a missing entry whose `backup_location` matches the remote of a new folder has its `folder_path` rewritten instead of being removed and re-added.
        - **Missing folder** — always prompts per entry (`remove` / `disable` / `skip`), even with `--yes`, since a missing folder may simply not be restored yet.
        
        Entries whose `folder_path` points outside the workspace tree (e.g. `../Library/...`) are never touched.
        
        ### 5. Create a New Workspace
        
        ```bash
        wbck create --name myworkspace --workspace-path $HOME/ --config-folder $HOME/.configs/
        ```
        
        This creates the workspace directory at `<workspace-path>/<name>` and writes a starter config file to `<config-folder>/<name>_config.json`.
        
        ## Contributing
        
        Contributions are welcome! Feel free to submit bug reports, feature requests, or pull requests on [GitHub](https://github.com/argoyal/wbck).
        
        ## License
        
        This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
        
        ---
        
        **Disclaimer:** This project is provided as-is, without warranty of any kind, express or implied. Use at your own risk.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
