Skip to main content
This page lists faults in Jig that you can run into without reading its source code. Each entry says what you will see, what it can cost you, and what to do instead.
What this page describes. Jig as it stands today — the code the next release is cut from. It is not a report about one installed version, so your copy may behave differently. The changelog is where each release records what changed.
This is not the page for “something went wrong”. If a command refused, a setting did not take, or your agent ignored Jig, start with Troubleshooting — those are problems with an answer today. An entry below stays here until the fault is actually fixed, and it is removed in the same change that fixes it. The page is not a list of everything Jig could do better, and it is not a copy of Jig’s to-do list. Work already under way is left out.

​
Removing a task worktree deletes ignored files inside it, without asking

A task can be given a worktree of its own: a second working copy of your project, in a folder beside it, so that two agent sessions do not edit the same files. When the task is done, Jig’s housekeeping removes that folder, and you can remove one yourself with git worktree remove. Git protects a worktree from removal when it holds changes it is tracking, and when it holds files it has never seen. Files your project ignores are the exception: git deletes those without a word and reports success. Jig’s cleanup asks git the same question, and ignored files are not part of the answer — so a worktree full of ignored work looks empty to it. What this can cost you is anything that lives in an ignored folder and exists nowhere else:
  • a .env file, or local settings you never copied anywhere
  • a local database, uploaded files, or test data you generated by hand
  • a separate Git repository you created or cloned inside an ignored folder — it goes with the rest, and its own commits go with it, including any you never pushed
What to do instead. Before a task worktree goes away, look inside it for work that exists only there:
Every line starting with !! is ignored, and every one of them will be deleted. Copy out what you want to keep. If an ignored folder holds a repository of its own, commit and push from inside that folder first — the project around it knows nothing about its history.
A worktree with uncommitted changes is never removed automatically. If you want one kept while you sort out what is inside it, leave a change in it, or ask your agent to “keep the worktree for this task”.

​
jig task ship pushes a branch with no commits, then fails

jig task ship hands finished work over: it commits what has been staged, pushes the branch, and opens the pull request. When nothing has been staged, the first step does nothing and says so — and the rest of the run carries on regardless:
The branch arrives on the server carrying no work, and the run then stops on the pull request, with a message from GitHub rather than from Jig:
The sentence that explains it is the first one, nothing staged; no commit, and it goes by as information rather than as a refusal — so the error you are left looking at is about pull requests, while the actual problem is that nothing was saved. This happens only when the branch has no commits of its own yet. If an earlier run already committed the work, an empty staging area is normal and everything proceeds. What to do instead. Nothing is lost — but nothing was shipped either, and the work is still sitting in your project unsaved. Ask your agent to stage it and ship again:
Send to your agent
The empty branch may stay on the server. It is harmless, and the real commit goes to the same place once it exists.

​
A task that has already started cannot be moved into a worktree

You can ask for a worktree when a task starts. You cannot ask for one afterwards:
The refusal is about starting a task twice, and it is raised before the request for a worktree is looked at — so there is no way to say “this task has begun, now give it a place of its own”. You meet this exactly when it would help most: something else has come up, and the task you started is in the way. What to do instead. Move the other work, not this one. A task can have a worktree from the moment it starts, so give the new task one:
Send to your agent
If it really has to be this task that moves, that is Git’s job rather than Jig’s, and it is worth doing with your agent while you watch: the branch has to be checked out in the new folder and let go of by the old one.

​
An interrupted command leaves temporary files behind

When Jig rewrites one of its own files, it writes the new version beside the old one and then renames it into place, so that a command stopped halfway can never leave you with half a file. What it can leave you with is the spare copy. Press Ctrl-C, close the terminal, or let the machine sleep at the wrong moment, and the spare stays where it was written. Nothing removes it afterwards. They are easy to recognise: the name of a real file, then .tmp, then a number. A few are named .new, .join or .restore instead, and one of those is a folder rather than a file.
Most of them land in folders your project ignores and you will never meet them. The ones you do meet sit next to files you care about, and your project reports them as new files it has not seen before. That costs you twice: one can be committed by accident along with real work, and Jig counts it as part of what you changed — so checks that would normally run only what your change can affect may run everything instead, and take much longer for no reason. What to do instead. Delete them. Nothing ever reads them back; the number in the name belonged to the command that died. Look before you delete:
Check that the list holds nothing but names like these, then delete them — one of them may be a folder, so remove it as one. Or simply hand the whole thing over:
Send to your agent
Do this when no Jig command is running. A file that looks like a leftover may be the copy a live command is about to rename into place.