Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
"""The clone walk never sees upstream deletions; remove only files that still match the synced hash."""
from __future__ import annotations
import hashlib
import os
import shutil
import subprocess
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
SYNC = REPO_ROOT / "docker" / "unsloth_sync_notebooks.sh"
behavioural = pytest.mark.skipif(
any(shutil.which(tool) is None for tool in ("bash", "git", "sha256sum")),
reason = "needs bash, git and sha256sum",
)
def _sha256(path: Path) -> str:
return hashlib.sha256(path.read_bytes()).hexdigest()
def _git(cwd: Path, *args: str) -> None:
subprocess.run(
["git", *args],
cwd = cwd,
check = True,
capture_output = True,
env = dict(
os.environ,
GIT_AUTHOR_NAME = "t",
GIT_AUTHOR_EMAIL = "t@e",
GIT_COMMITTER_NAME = "t",
GIT_COMMITTER_EMAIL = "t@e",
),
)
FILES = {
"nb/keep.ipynb": "keep-v1",
"nb/doomed.ipynb": "doomed-v1",
"nb/edited.ipynb": "edited-v1",
}
def _setup(tmp_path: Path):
remote = tmp_path / "remote"
(remote / "nb").mkdir(parents = True)
for rel, body in FILES.items():
(remote / rel).write_text(body, encoding = "utf-8")
_git(remote, "init", "-q", "-b", "main")
_git(remote, "add", "-A")
_git(remote, "commit", "-qm", "one")
template = tmp_path / "template"
(template / "nb").mkdir(parents = True)
dest = tmp_path / "dest"
(dest / "nb").mkdir(parents = True)
lines = []
for rel, body in FILES.items():
(template / rel).write_text(body, encoding = "utf-8")
(dest / rel).write_text(body, encoding = "utf-8")
lines.append(f"{_sha256(dest / rel)} {rel}")
(dest / ".unsloth_sync_state").write_text("\n".join(lines) + "\n", encoding = "utf-8")
return remote, template, dest
def _advance(remote: Path):
"""Upstream drops two notebooks and changes the third."""
(remote / "nb" / "doomed.ipynb").unlink()
(remote / "nb" / "edited.ipynb").unlink()
(remote / "nb" / "keep.ipynb").write_text("keep-v2", encoding = "utf-8")
_git(remote, "add", "-A")
_git(remote, "commit", "-qm", "two")
def _refresh(tmp_path: Path, remote: Path, template: Path, dest: Path, **extra):
return subprocess.run(
["bash", str(SYNC)],
capture_output = True,
text = True,
timeout = 300,
env = dict(
os.environ,
UNSLOTH_NB_REFRESH_CHILD = "1",
UNSLOTH_NOTEBOOKS_TEMPLATE = str(template),
UNSLOTH_NOTEBOOKS_DIR = str(dest),
UNSLOTH_NOTEBOOKS_REPO = str(remote),
UNSLOTH_SKIP_NOTEBOOK_VIEW = "1",
UNSLOTH_KEEP_COLAB_INTRO = "1",
**extra,
),
)
def _state(dest: Path) -> dict:
path = dest / ".unsloth_sync_state"
out = {}
if path.is_file():
for line in path.read_text(encoding = "utf-8").splitlines():
parts = line.split(" ", 1)
if len(parts) == 2:
out[parts[1]] = parts[0]
return out
@behavioural
def test_a_pristine_notebook_deleted_upstream_is_removed(tmp_path: Path):
remote, template, dest = _setup(tmp_path)
_advance(remote)
(dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")
run = _refresh(tmp_path, remote, template, dest)
assert run.returncode == 0, run.stdout + run.stderr
assert not (
dest / "nb" / "doomed.ipynb"
).exists(), "the notebook upstream deleted is still on disk, so the view keeps listing it"
assert (dest / "nb" / "edited.ipynb").read_text(
encoding = "utf-8"
) == "MY OWN WORK", "a file that no longer hashes to what we wrote is the user's, edited or not"
assert (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8") == "keep-v2"
state = _state(dest)
assert "nb/doomed.ipynb" not in state
assert state["nb/keep.ipynb"] == _sha256(dest / "nb" / "keep.ipynb")
assert "1 removed upstream" in run.stdout, run.stdout
@behavioural
def test_the_removal_can_be_turned_off(tmp_path: Path):
"""Non-vacuity as well as the opt-out: with the switch on, the same run leaves it."""
remote, template, dest = _setup(tmp_path)
_advance(remote)
run = _refresh(tmp_path, remote, template, dest, UNSLOTH_KEEP_REMOVED_NOTEBOOKS = "1")
assert run.returncode == 0, run.stdout + run.stderr
assert (dest / "nb" / "doomed.ipynb").exists()
assert "0 removed upstream" in run.stdout, run.stdout
@behavioural
def test_a_case_only_rename_does_not_delete_the_file_just_published(tmp_path: Path):
"""The clone is case-sensitive while the destination may be a macOS or Windows bind
mount, so the old path would resolve to the file the refresh has just written."""
remote, template, dest = _setup(tmp_path)
_git(remote, "mv", "nb/doomed.ipynb", "nb/Doomed.ipynb")
_git(remote, "commit", "-qm", "rename case only")
run = _refresh(tmp_path, remote, template, dest)
assert run.returncode == 0, run.stdout + run.stderr
assert (dest / "nb" / "Doomed.ipynb").exists()
assert "0 removed upstream" in run.stdout, run.stdout
@behavioural
def test_nothing_is_removed_when_upstream_removed_nothing(tmp_path: Path):
remote, template, dest = _setup(tmp_path)
(remote / "nb" / "keep.ipynb").write_text("keep-v2", encoding = "utf-8")
_git(remote, "add", "-A")
_git(remote, "commit", "-qm", "two")
run = _refresh(tmp_path, remote, template, dest)
assert run.returncode == 0, run.stdout + run.stderr
for rel in FILES:
assert (dest / rel).exists(), rel
assert "0 removed upstream" in run.stdout, run.stdout
def _refuse_rm(tmp_path: Path, target: Path) -> Path:
"""Stubs rm earlier on PATH to fail for one path, as a writable single-file bind mount does with
EBUSY; the publish already works around that case for rename."""
bindir = tmp_path / "bin"
bindir.mkdir(exist_ok = True)
stub = bindir / "rm"
stub.write_text(
"#!/bin/sh\n"
'for a in "$@"; do\n'
f' [ "$a" = "{target}" ] && exit 1\n'
"done\n"
'exec /bin/rm "$@"\n',
encoding = "utf-8",
)
stub.chmod(0o755)
return bindir
@behavioural
def test_a_removal_that_cannot_be_unlinked_keeps_its_record_and_retries(tmp_path: Path):
"""A removal that fails must keep its record and retry: dropping it leaves the stale copy read
as user-owned forever, and failed stays zero so the sync marker is stamped."""
remote, template, dest = _setup(tmp_path)
_advance(remote)
(dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")
doomed = dest / "nb" / "doomed.ipynb"
bindir = _refuse_rm(tmp_path, doomed)
run = _refresh(
tmp_path, remote, template, dest, PATH = f"{bindir}{os.pathsep}{os.environ['PATH']}"
)
assert run.returncode == 0, run.stdout + run.stderr
assert doomed.exists(), "precondition: the stub refused the unlink"
assert _state(dest).get("nb/doomed.ipynb") == _sha256(
doomed
), "the file stayed but its record was dropped, so it is now unmanaged"
assert "0 removed upstream" in run.stdout, run.stdout
assert not (
dest / ".unsloth_sync_commit"
).is_file(), "the commit was stamped over a failure, so the next start exits before retrying"
run2 = _refresh(tmp_path, remote, template, dest)
assert run2.returncode == 0, run2.stdout + run2.stderr
assert not doomed.exists()
assert "nb/doomed.ipynb" not in _state(dest)
assert "1 removed upstream" in run2.stdout, run2.stdout
@behavioural
def test_the_successful_removal_still_stamps_the_commit(tmp_path: Path):
"""Non-vacuity for the assertion above: without the stub the same run records it,
so the marker check is testing the failure and not the environment."""
remote, template, dest = _setup(tmp_path)
_advance(remote)
(dest / "nb" / "edited.ipynb").write_text("MY OWN WORK", encoding = "utf-8")
run = _refresh(tmp_path, remote, template, dest)
assert run.returncode == 0, run.stdout + run.stderr
assert (dest / ".unsloth_sync_commit").is_file()
assert "1 removed upstream" in run.stdout, run.stdout
def _refuse_mv_to(tmp_path: Path, target: Path) -> Path:
"""Stubs mv earlier on PATH to fail for one destination, as a full or read-only /workspace does
when the state file is published; other moves pass through."""
bindir = tmp_path / "bin"
bindir.mkdir(exist_ok = True)
stub = bindir / "mv"
stub.write_text(
"#!/bin/sh\n"
'for a in "$@"; do\n'
f' [ "$a" = "{target}" ] && exit 1\n'
"done\n"
'exec /bin/mv "$@"\n',
encoding = "utf-8",
)
stub.chmod(0o755)
return bindir
@behavioural
def test_a_state_that_cannot_be_published_holds_the_sync_marker(tmp_path: Path):
"""Stamping the commit after a failed state publish wedges the tree, as stale hashes read every
notebook as user-edited; the state failure must hold the marker like failed does."""
remote, template, dest = _setup(tmp_path)
_advance(remote)
before = _state(dest)
bindir = _refuse_mv_to(tmp_path, dest / ".unsloth_sync_state")
run = _refresh(
tmp_path, remote, template, dest, PATH = f"{bindir}{os.pathsep}{os.environ['PATH']}"
)
assert run.returncode == 0, run.stdout + run.stderr
assert _state(dest) == before, "precondition: the stub refused the state publish"
assert not (
dest / ".unsloth_sync_commit"
).is_file(), "the commit was stamped over an unpublished state, so the tree is wedged"
@behavioural
def test_the_state_temp_file_is_published_by_a_same_directory_rename(tmp_path: Path):
"""The state temp file must sit beside the state file so publishing it is an atomic rename;
notebooks publish first, so a standalone state publish failure leaves disk ahead of state."""
source = SYNC.read_text(encoding = "utf-8")
assert 'TMPSTATE="$STATE.tmp"' in source, (
"the refresh state temp file left $DEST, so publishing it is a cross-device "
"copy that can fail after the notebooks have already landed"
)
stray = [
line.strip()
for line in source.splitlines()
if "mktemp" in line and "TMPSTATE=" in line and "||" not in line
]
assert not stray, f"the refresh state must not be staged outside $DEST: {stray}"
@behavioural
def test_a_published_state_still_stamps_the_commit(tmp_path: Path):
"""Non-vacuity for the assertion above: the identical run without the stub records
the marker, so that check is testing the failure and not the environment."""
remote, template, dest = _setup(tmp_path)
_advance(remote)
run = _refresh(tmp_path, remote, template, dest)
assert run.returncode == 0, run.stdout + run.stderr
assert (dest / ".unsloth_sync_commit").is_file()
@behavioural
def test_an_unwritable_dest_publishes_nothing_and_recovers(tmp_path: Path):
"""With DEST unwritable but its notebook subdirs writable (the container shape), staging in /tmp
would publish bytes it cannot record; the refresh must bail before publishing."""
remote, template, dest = _setup(tmp_path)
_advance(remote)
before_state = _state(dest)
before_bytes = (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8")
(dest / "nb").chmod(0o755)
dest.chmod(0o555) # root writable by nobody; the subdir still is
try:
run = _refresh(tmp_path, remote, template, dest)
assert run.returncode == 0, run.stdout + run.stderr
assert (dest / "nb" / "keep.ipynb").read_text(
encoding = "utf-8"
) == before_bytes, "notebooks were published with no way to record them"
assert _state(dest) == before_state
assert not (
dest / ".unsloth_sync_commit"
).is_file(), "the marker was stamped over a refresh that could not record itself"
finally:
dest.chmod(0o755)
run2 = _refresh(tmp_path, remote, template, dest)
assert run2.returncode == 0, run2.stdout + run2.stderr
assert (dest / "nb" / "keep.ipynb").read_text(encoding = "utf-8") == "keep-v2"
assert _state(dest).get("nb/keep.ipynb") == _sha256(dest / "nb" / "keep.ipynb")
assert (dest / ".unsloth_sync_commit").is_file()
@behavioural
def test_a_stale_state_temp_file_does_not_block_the_refresh_forever(tmp_path: Path):
"""A stale $STATE.tmp left by a run under another uid must not block the refresh forever;
unlinking it needs write on DEST, which the real bail case lacks, so the guard holds."""
remote, template, dest = _setup(tmp_path)
_advance(remote)
stale = dest / ".unsloth_sync_state.tmp"
stale.write_text("LEFTOVER FROM A KILLED RUN\n", encoding = "utf-8")
stale.chmod(0o444) # cannot be truncated by this uid; can still be unlinked
assert not os.access(stale, os.W_OK), "precondition: the leftover is not truncatable"
run = _refresh(tmp_path, remote, template, dest)
assert run.returncode == 0, run.stdout + run.stderr
assert (dest / "nb" / "keep.ipynb").read_text(
encoding = "utf-8"
) == "keep-v2", "a stale temp file the uid cannot truncate blocked the refresh"
assert _state(dest).get("nb/keep.ipynb") == _sha256(dest / "nb" / "keep.ipynb")
assert (dest / ".unsloth_sync_commit").is_file()