shiggles 0.3.0

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

Shiggles

Shiggles is a small command-line 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

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).
• Stdlib only. 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.

From PyPI (after publish):

pip install shiggles

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

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)
  scripts/
    shig-server.py    Minimal HTTP remote for local testing
  tests/
    test_scenarios.py Scenario walkthrough and unit 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.