Git keeps committed changes around long enough for users to recover changes they have accidentally deleted. It does so by not garbage collecting any committed but no longer referenced objects for a certain period of time, by default 30 days.
But Git does not keep track of uncommitted changes in the working tree and not even the index (the staging area). Because Magit makes it so convenient to modify uncommitted changes, it also makes it easy to shoot yourself in the foot in the process.
For that reason Magit provides a global mode that saves tracked files to work-in-progress references after or before certain actions. (At present untracked files are never saved and for technical reasons nothing is saved before the first commit has been created).
Two separate work-in-progress references are used to track the state
of the index and of the working tree: refs/wip/index/<branchref> and
refs/wip/wtree/<branchref>, where <branchref> is the full ref of the
current branch, e.g., refs/heads/master. When the HEAD is detached
then HEAD is used in place of <branchref>.
Checking out another branch (or detaching HEAD) causes the use of
different wip refs for subsequent changes.
When this mode is enabled, then uncommitted changes are committed to dedicated work-in-progress refs whenever appropriate (i.e., when dataloss would be a possibility otherwise).
Setting this variable directly does not take effect; either use the Custom interface to do so or call the respective mode function.
To view the log for a branch and its wip refs use the commands
magit-wip-log and magit-wip-log-current. You should use --graph when
using these commands.
This command shows the log for a branch and its wip refs. With a negative prefix argument only the worktree wip ref is shown.
The absolute numeric value of the prefix argument controls how many
"branches" of each wip ref are shown. This is only relevant if the
value of magit-wip-merge-branch is nil.
This command shows the log for the current branch and its wip refs. With a negative prefix argument only the worktree wip ref is shown.
The absolute numeric value of the prefix argument controls how many
"branches" of each wip ref are shown. This is only relevant if the
value of magit-wip-merge-branch is nil.
magit-reset-worktree) ¶This command resets the working tree to some commit read from the
user and defaulting to the commit at point, while keeping the HEAD
and index as-is.
This can be used to restore files to the state committed to a wip ref. Note that this will discard any unstaged changes that might have existed before invoking this command (but of course only after committing that to the working tree wip ref).
Note that even if you enable magit-wip-mode this won’t give you
perfect protection. The most likely scenario for losing changes
despite the use of magit-wip-mode is making a change outside Emacs and
then destroying it also outside Emacs. In some such a scenario,
Magit, being an Emacs package, didn’t get the opportunity to keep you
from shooting yourself in the foot.
When you are unsure whether Magit did commit a change to the wip refs, then you can explicitly request that all changes to all tracked files are being committed.
This command commits all changes to all tracked files to the index and working tree work-in-progress refs. Like the modes described above, it does not commit untracked files, but it does check all tracked files for changes. Use this command when you suspect that the modes might have overlooked a change made outside Emacs/Magit.
The namespace used for work-in-progress refs. It has to end with
a slash. The wip refs are named <namespace>index/<branchref> and
<namespace>wtree/<branchref>. When snapshots are created while
the HEAD is detached then HEAD is used in place of <branchref>.
Mode-line lighter for magit-wip--mode.
This option controls whether the current branch is merged into the wip refs after a new commit was created on the branch.
If non-nil and the current branch has new commits, then it is
merged into the wip ref before creating a new wip commit. This
makes it easier to inspect wip history and the wip commits are
never garbage collected.
If nil and the current branch has new commits, then the wip ref
is reset to the tip of the branch before creating a new wip
commit. With this setting wip commits are eventually garbage
collected.
If immediately, then use git-commit-post-finish-hook to
create the merge commit. This is discouraged because it can
lead to a race condition, e.g., during rebases.
When magit-wip-merge-branch is t, then the history looks like this:
*--*--*--*--*--* refs/wip/index/refs/heads/master / / / A-----B-----C refs/heads/master
When magit-wip-merge-branch is nil, then creating a commit on the real
branch and then making a change causes the wip refs to be recreated to
fork from the new commit. But the old commits on the wip refs are not
lost. They are still available from the reflog. To make it easier to
see when the fork point of a wip ref was changed, an additional commit
with the message "restart autosaving" is created on it (xxO commits
below are such boundary commits).
Starting with
BI0---BI1 refs/wip/index/refs/heads/master
/
A---B refs/heads/master
\
BW0---BW1 refs/wip/wtree/refs/heads/master
and committing the staged changes and editing and saving a file would result in
BI0---BI1 refs/wip/index/refs/heads/master
/
A---B---C refs/heads/master
\ \
\ CW0---CW1 refs/wip/wtree/refs/heads/master
\
BW0---BW1 refs/wip/wtree/refs/heads/master@{2}
The fork-point of the index wip ref is not changed until some change is being staged. Likewise just checking out a branch or creating a commit does not change the fork-point of the working tree wip ref. The fork-points are not adjusted until there actually is a change that should be committed to the respective wip ref.