What does -- mean in git usage?

Question

To delete a file one can:

git rm path/to/file

When I want to unstage a deleted file in git, I have to:

git reset -- path/to/file
git checkout -- path/to/file

I don't quite understand why the -- is necessary and how the command differs from:

git reset path/to/file
git checkout path/to/file

other that the latter wouldn't work.

What's the rationale behind --?

The fatal error states:

Use '--' to separate paths from revisions

yet I still don't quite understand the difference.

score 6 · Accepted Answer · answered May 26 '16 at 15:27

git command some-path and git command -- some-path are equivalent in all cases except when some-path could be interpreted as a commit reference. The most common case is a branch that has the same name as a file.

For example, imagine your repository has a file named master in its root. Then git checkout master would checkout the branch master. But git checkout -- master would check out the file master of the current HEAD and replace the local master file with the version of that revision.

score 0 · Answer 2 · answered May 26 '16 at 15:16

0

As the error states, it would not be possible to know if path/to/file is a file path or a tree-ish, so it is always parsed as a tree-ish, and arguments after -- are parsed as paths.

answered May 26 '16 at 15:16

wRAR

24,218
4
82
96

I guess I don't quite understand what tree structure could expect here? To me, I either provide a path or a branch. How could there be trees? – k0pernikus May 26 '16 at 15:17
It's not a branch but tree-ish, so it can be a tag, some other ref or anything else. – wRAR May 26 '16 at 15:21
And how would a tag cause confusion with the syntax without `--`? Could you please add an example? – k0pernikus May 26 '16 at 15:22
1

If you have a file named `bar` and a branch named `bar`, how would `git` know which to remove? – tripleee May 26 '16 at 15:24
@tripleee Thanks. That simple phrasing made the distionction so much clearer. – k0pernikus May 26 '16 at 15:25

What does -- mean in git usage?

2 Answers2