How does `git stash` treat untracked files?

Question

How does git stash treat untracked files?

Git official doc (link) defines git-stash as

git-stash - Stash the changes in a dirty working directory away

But to me (a beginner of git), it is not very obvious what is the exact definition of "dirty working directory". Are untracked files included?

To be more precise, I notice that in a "dirty" working directory, we can have three types of dirty states:

1. changes made to a file before it has been run git add (changes are in index)
2. changes made to a file after it has been run git add (changes are not in index but the file is tracked aka "Changes to be committed")
3. changes made to a file that git add has never been run (the file is untracked)

When we run git stash, what would happen to #1, #2, and #3?

Answer 1

What I think they've meant is that actual changes are only changes in files that git is tracking.

In a way that makes sence within git, since if you have a file that is untracked then it ain't a change, it is nothing until you track it. You can even switch beetween branches freely with untracked changes.

From the outside of git however that would be wrong because it is an actual change within the local repository, but since we're talking git features then the view from within git is the correct one, even though it may seem a little non-didatic.

This may look like a matter of opinion, but since change is a keyword within git it must have a single meaning.

The longer description solves it:

The command saves your local modifications away and reverts the working directory to match the HEAD commit.

Answer 2

I am trying to provide my own answer here.

I am new to git. But to me, the one-line describing the command should be revised to this

git-stash - Stash away the tracked changes in a dirty working directory
            (untracked changes are ignored)

In other words, git stash (without the option -u) would stash #1 and #2 but not #3. And if #1 and #2 are happening to the same file, then #2 will take precedence over #1.

With the option -u, git stash -u can include also the untracked files. See this SO article (link) for more details.

Experiment

The following experiment shows how git stash (with -u) handles the three cases (a based case, file t1.txt in history) is also included.

Set up four different states

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ echo "Hello" > t1.txt ; git add t1.txt ; git commit -m "Add t1.txt"
[f2 7367b85] Add t1.txt
 1 file changed, 1 insertion(+)
 create mode 100644 tmp/t1.txt

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ echo "Hello in Index" > t1.txt ; git add t1.txt

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ echo "Hello in Working Directory (tracked)" > t1.txt

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ echo "Bonjour in Working Directory (untracked)" > t2.txt

Examine the four states

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ git status
On branch f2
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   t1.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   t1.txt

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        t2.txt

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ git diff --cached t1.txt
diff --git a/tmp/t1.txt b/tmp/t1.txt
index e965047..a863c48 100644
--- a/tmp/t1.txt
+++ b/tmp/t1.txt
@@ -1 +1 @@
-Hello
+Hello in Index

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ git diff t1.txt
diff --git a/tmp/t1.txt b/tmp/t1.txt
index a863c48..a0c6962 100644
--- a/tmp/t1.txt
+++ b/tmp/t1.txt
@@ -1 +1 @@
-Hello in Index
+Hello in Working Directory (tracked)

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ cat t2.txt
Bonjour in Working Directory (untracked)

Now perform the stash

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ git stash
Saved working directory and index state WIP on f2: 7367b85 Add t1.txt

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ git status
On branch f2
Untracked files:
  (use "git add <file>..." to include in what will be committed)

        t2.txt

nothing added to commit but untracked files present (use "git add" to track)

Note that t2.txt was not handled by git stash

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ git stash show
 tmp/t1.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

If you lost t2.txt; git stash won't be able to restore it for you

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ rm t2.txt

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ git stash pop
On branch f2
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   t1.txt

no changes added to commit (use "git add" and/or "git commit -a")
Dropped refs/stash@{0} (6a004ffe723ae18d9d5a314c0f5460622b27e300)

Index vs Tracked (Changes not staged for commit)

By the way, note also that what happened to the state of

#1 "Hello in Index" (of t1.txt in index before `git stash`)
#2 "Hello in Working Directory (tracked)" (of t1.txt in worktree before `git stash`)

#1 was also lost after a pair of git stash and git stash pop operations. What was retained was #2. In other words, the working directory state has taken precedence in the stash operation.

MINGW64 ~/proj/tmp/sandbox/tmp (f2)
$ cat t1.txt
Hello in Working Directory (tracked)

Answer 3

How does git stash treat untracked files?

Before Git 2.16.x/2.17, potentially badly!
"git stash -- <pathspec>" incorrectly blew away untracked files in the directory that matched the pathspec, which has been corrected.

See commit bba067d (06 Jan 2018) by Thomas Gummerer (tgummerer).
Helped-by: Junio C Hamano (gitster).
^{(Merged by Junio C Hamano -- gitster -- in commit 087d1a8, 23 Jan 2018)}

stash: don't delete untracked files that match pathspec

See Git Glossary pathspec)

Currently when 'git stash push -- <pathspec>' is used, untracked files that match the pathspec will be deleted, even though they do not end up in a stash anywhere.

This is because the original commit introducing the pathspec feature in git stash push (df6bba0 ("stash: teach 'push' (and 'create_stash') to honor pathspec", 2017-02-28, Git v2.13.0-rc0)) used the sequence of:

git reset <pathspec> && git ls-files --modified <pathspec> | 
  git checkout-index && git clean <pathspec>

The intention was to emulate what 'git reset --hard -- <pathspec>' would do.
The call to 'git clean' was supposed to clean up the files that were unstaged by 'git reset'.
This would work fine if the pathspec doesn't match any files that were untracked before 'git stash push -- <pathspec>'.
However if <pathspec> matches a file that was untracked before invoking the 'stash' command, all untracked files matching the pathspec would inadvertently be deleted as well, even though they wouldn't end up in the stash, and are therefore lost.

This behaviour was never what was intended, only blobs that also end up in the stash should be reset to their state in HEAD, previously untracked files should be left alone.

To achieve this:

• first match what's in the index and what's in the working tree by adding all changes to the index,
• ask diff-index what changed between HEAD and the current index, and
• then apply that patch in reverse to get rid of the changes, which includes removal of added files and resurrection of removed files.