shiggles 0.4.0

For git and shiggles. A simple content-addressed VCS.

Shiggles

Shiggles is a simple version control tool for people who want named saves, a simple history, and team sync without learning git.

It is designed for artists, designers, and small teams working on a shared project folder. You snapshot work with plain messages, switch context with tabs, and push or pull from a shared folder or HTTP URL.

Repository: github.com/drLemis/shiggles

Quick start

Desktop (easiest on Windows): run install.ps1, double-click the Shiggles shortcut, open your project folder, click Save.

Terminal:

pip install shiggles
cd your-project
shig start
shig save "first version"

Desktop UI (v0.4)

Prefer buttons? Run shig ui or double-click the Shiggles desktop shortcut (created by install.ps1 on Windows).

The UI is a thin layer over the same engine as the CLI — no duplicated logic. Everything you do in the UI runs the same commands against the same .shig/ folder.

Menu	What it covers
File	Open folder, exit
Project	Save, undo, download, upload
Tabs	New tab, remove tab, bring into another tab
Auto	Restore file versions, enable/disable snapshots
View	Timeline, refresh
Help	Full command reference, about

The dashboard auto-refreshes every few seconds so new and changed files show up without restarting the app. Dialogs use plain language (not raw shig ... hints).

On Linux you may need the system python3-tk package: sudo apt install python3-tk (Debian/Ubuntu).

Alias entry point: shig-ui (same as shig ui).

Features

• Watches a project folder and stores content-addressed snapshots on save.
• Named saves with author and time on each tab.
• Tabs for parallel work (main plus side piles like hotfix).
• bring lands your current tab into another tab (usually main).
• upload and download sync the current tab via shared folder or HTTP URL.
• Hard-stop collisions: conflicting files are parked in .shig/collisions/ with next-step help.
• load restores an older save and makes it current.
• undo discards unsaved edits and reloads the last save.
• timeline append-only log of operations (including remote history after sync).
• Per-file auto snapshots on save (local crash recovery; never uploads).
• Tab completion installed automatically on first shig command.
• Stdlib only for core + UI. No git dependency.

How It Works

When you run shig start, Shiggles creates a .shig/ folder next to your project files. Each shig save "message" stores a snapshot of tracked files on the current tab.

Tabs keep separate histories. main is the default shared line. shig tab foobar forks from your current tab and switches you to a side pile.

Team sync copies commit objects, tab refs, tab metadata, and timeline.log to a remote. After download, files and history match what was uploaded from the other machine.

Requirements

• Python 3.9 or newer
• Windows, macOS, or Linux

Optional for HTTP remotes: any host that can serve PUT/GET (or scripts/shig-server.py for local testing).

Installation

Windows (recommended):

.\install.ps1

Restart your terminal, then shig help or open the Shiggles desktop shortcut.

From PyPI:

pip install shiggles
pip install shiggles[auto]   # optional faster file watcher (watchdog)

Developers:

pip install -e ".[dev]"

Usage

1. Open a terminal in your project folder.
2. Run shig start.
3. Run shig save "first version".
4. Use shig changes and shig history to see what changed.
5. Use shig upload <path-or-url> when you want to share with the team.

Basic solo workflow:

shig start
shig save "first version"
shig changes
shig history

Tabs

• main - default tab, the shared project line
• foobar - your side pile for interrupted work

shig tab foobar       # create and switch
shig save "WIP window fix"
shig tab main         # switch back
shig tab foobar       # resume; files as you left them

Team sync

Shared folder (NAS, network path, USB):

shig download \\NAS\projects\my-game
shig save "updated level"
shig upload

HTTP URL (optional token in .shig/config.json):

shig upload http://backup.example.com/shiggles/my-project
shig download

The remote is remembered in .shig/config.json after the first use.

If someone else saved while you were working, shig save nudges you to download first. Skip with shig save --yes "message".

Bring (landing your tab on main)

shig tab foobar
shig save "fixed shoot.cs"
shig bring main

If someone else changed the same file on main, Shiggles stops and prints next steps. Fix on main, not another bring.

Restoring older work

• shig load "message" - put files back to a matching save (becomes current)
• shig undo - discard unsaved changes and reload the last save on this tab

Crash recovery (auto snapshots)

After shig start, per-file auto snapshots are on by default. A background watcher (one per user, all repos) saves recent versions of each file locally when saves finish writing. Auto data never uploads.

shig auto                    # list auto-saved files
shig auto project.psd        # roll this file back 1 step
shig auto project.psd 2      # roll back 2 steps
shig save "recovered"        # promote fix to a named save

Disable for this repo: shig auto off. Re-enable: shig auto on. Disable everywhere: shig auto off --all.

Login autostart is installed on first shig start so snapshots continue after reboot (for registered repos).

Limits: folder must be a Shiggles repo (shig start once). For non-Shiggles folders or visible backup copies elsewhere, use AutoBackup.

Optional faster watcher: pip install shiggles[auto] (watchdog).

Commands

Command	What it does
shig start	Set up this folder
shig save "..."	Snapshot current tab
shig save --yes "..."	Save even if remote is ahead
shig load "..."	Put files back to a save (becomes current)
shig changes	What is different since last save
shig history	Saves on current tab
shig tab [name]	List, switch, or create tabs
shig untab <name>	Remove a tab (history kept)
shig bring <tab>	Land current tab into another
shig download [path|url]	Pull current tab from remote
shig upload [path|url]	Push current tab to remote
shig undo	Discard unsaved changes; back to last save
shig timeline	Operation log
shig auto	List per-file auto snapshots (local)
shig auto <file> [n]	Roll file back n auto steps
shig auto off	Disable auto for this repo
shig auto on	Enable auto for this repo
shig auto off --all	Disable auto everywhere
shig ui [folder]	Open desktop UI (tkinter)
shig help	Command reference

Tab completion installs automatically. Press Tab after shig in the terminal.

Ignore files

Edit .shignore (created on shig start). Same idea as .gitignore. Build output, .shig/, and junk stay out of snapshots.

Project structure

shiggles/
  shiggles/           Python package (commands, store, remote sync, ui)
  scripts/
    shig-server.py    Minimal HTTP remote for local testing
  tests/
    test_scenarios.py Scenario walkthrough and unit tests
    test_api.py         UI adapter tests (no tkinter display)
    test_complete.py    Tab completion tests
  install.ps1         Windows installer
  LICENSE             NWSL-1.0

On-disk repo layout:

.shignore
.shig/
  objects/
  refs/tabs/
  tabs/
  collisions/
  HEAD
  config.json
  timeline.log
  auto/
    versions/          # per-file auto snapshot index (local only)

HTTP dev server

python scripts/shig-server.py ./remote-store -p 8765
shig upload http://127.0.0.1:8765

Use the full URL including http://. A bare 127.0.0.1:8765 is not recognized as HTTP.

Tests

python tests/test_scenarios.py              # narrated walkthrough
python tests/test_scenarios.py --keep       # keep files in tests/_sandbox/
python tests/test_scenarios.py --clean      # wipe sandbox
python -m unittest discover -s tests -v     # unit tests

Publish to PyPI

pip install build twine
python -m build
twine upload dist/*

Notes

• Shiggles is a simple VCS helper, not a replacement for full backups, cloud sync, or git power workflows.
• Collisions never overwrite your working files; compare copies under .shig/collisions/.
• See ROADMAP.md for philosophy, collision policy, and deferred features.

License

This software is licensed under the NWSL.

Copyright (c) 2026 drLemis.