What exactly does git checkout branch -- . do?

Question

I would like to understand this command in an easier way, I did some tests but I’m not quite sure of the conclusion. I have two branches, the master branch and the new branch, and I did the test described below.

Directory in the last Brach master commit:

Arquivo    Conteúdo
a.txt      Arquivo a.txt do branch master
b.txt      Arquivo b.txt do branch master

Directory in the last commit of the new branch:

Arquivo    Conteúdo
a.txt      Arquivo a.txt do branch novo
c.txt      Arquivo c.txt do branch novo

Git status:

$ git status
On branch master
nothing to commit, working directory clean

Running the command

$ git checkout novo -- .

The directory became:

Arquivo    Conteúdo
a.txt      Arquivo a.txt do branch novo
b.txt      Arquivo b.txt do branch master
c.txt      Arquivo c.txt do branch novo

Git status:

$ git status
On branch master
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
    modified:   a.txt
    new file:   c.txt

It seems to me that he is taking all the files from the new branch, copying and pasting on top of the working directory, over-writing all the files with the same name. That’s right, can I count on that behavior? It’s like git over-write a file with a different name?

Note that the git checkout command has different behavior depending on the parameters. I am specifically asking for the version of the command that has some file as parameter. In the command I mentioned, the dot is specifying the current directory (which in this case contains all the files) and makes a difference in the behavior of the command. Notice the two git status that the command does not change branch like checkout without "-- .".

Answer 1

The git checkout branch can be used in the following situations:

1 - Change branch. When git changes branch, all changes that were applied to the branch will be replaced by changes to the branch that was checked out.

When creating a git repository, the repository already starts with a branch called a master. Imagine that right now you create a master.txt file and commit that file. Then you create a new branch called a new branch, this new branch will at this point have the same content as the master branch. Therefore, when you execute the command git checkout nova-branch, no difference will be noticed.

Imagine now that you create a new file called new-branch.txt and commit that file. At this point there will be two files: master.txt and the new-branch.txt. When you execute the command git checkout master, your Working directory will return to the state where the master branch is pointing, that is, the new.txt file will disappear, because in the master branch that file does not exist.

Imagine now that you create a file called new-file.txt and don’t committee that file. In the current directory are present the new-files.txt and master.txt. Then you run the command git checkout nova-branch. Working directory will return to the state the new-branch is pointing to, i.e., the new-branch.txt file will appear. However, the new.txt file will continue to appear, because this file was not commited, so it is not part of the master branch. It is in what is called Working copy, which are the files that have been modified, created or deleted but that have not been committed. These files will continue in Working copy even if you change branch. That way, if you want, you can commit those files in the branch you want.

The examples I gave were about creating files, but of course the same applies if changes are made to the file.

2 - Git checkout can be used to create a new branch as well. If the command is executed this way: git checkout -b nome-branch. The branch will be created and then checkout will be done.

3 - Git checkout can be used to create a remote branch locally. If you clone a repository, only the master branch will be created locally. If you want to work on top of another branch, just run the command git checkout nova-branch, and the branch will be created locally.

A cool command you can test is this: git log --all --decorate --oneline --graph.

The command git log will display the commit history. Placing the --decorate you will see which commit each branch is pointing to. The --oneline will show only one line for each commit to make it easier to view. The --graph will show at which points branches forked and at which points merges were made. The --all will display the commit for all branches. No --all only the HEAD commits will be shown, which in this case are the commits of the current branch.

In addition to switching branches, git checkout can be used to bring a particular file back to its staged area state. A staged area is the files that are ready to be committed. In other words, it is the files that execute the command git add. If there is no version of the file in staged area, it will be returned to your version of the last commit. Let’s imagine the following scenario:

1. echo algum texto > a.txt
2. git add a.txt
3. git commit -m 'adicionando a'
4. echo alterando texto de a > a.txt

At this point, we do not want to commit the change made in a.txt. We want to undo the change. In this case, we can use the command git checkout a.txt. Changes made to the file will be discarded. This command can also be used in the following ways:

1. For more than one file: git checkout a.txt b.txt
2. To a directory: git checkout teste

We can, however, check out the file on another branch.

In the example you gave what happened was the following: When executing the command git checkout novo -- . All files in the current directory that are in the new branch have been checked out. In this case, the files that exist in the master branch and exist in the new branch will be replaced by the version that is in the new branch. Files that only exist in the new branch will be added to the master branch.

The behavior is similar if you are checkout the files on the same branch. Let’s imagine the following scenario:

1. The master branch has the following commit files: a.txt and b.txt.
2. You then remove the b.txt file, change a.txt and create c.txt
3. You then execute the command git checkout .

See that the behavior will be the same. The a.txt file returns to the state of the last commit in the new branch, the b.txt file reappears, and the c.txt file continues to appear, but as untracked.

The difference between these cases are:

1. git checkout . - The current directory files will be returned to their versions in the staged area. If there is no version in the staged area, it will be returned to its versions in the last commit in the branch.
2. git checkout nome-branch . - The directory files will be returned to the latest commit version of the desired branch.

In case a new file is created and this file is not committed, when the git checkout ., that file won’t go away. That’s because git doesn’t know about that file, because it hasn’t been versioned yet. It will continue in Working copy as an untracked file.

Similarly, if a file only exists on the master branch and does not exist on another branch, when executing the command git checkout outra-branch, that file won’t go away, because in the other branch git doesn’t know about that file, so it won’t do anything with the same.

For clarification purposes, the "." means that the current directory will be used and not all the files. If you are in the root directory coincidentally all files will be used. But if you enter a directory and run the command with "." you will be checked out of all the files in that last directory.

It has like git over-write a different name file?

No. git will only write over-files with the same name.

If the command is used git mv git will know that the file has been renamed. If the file is renamed without this command, git will identify that the file with the old name has been removed and that the file with the new name has been created. Still, after executing the git add for both operations, git will be able to identify that there was a name. If the file is renamed into a particular branch, when merging with another branch that is with the file with the old name, git will know that it is the same file and try to merge. However, the same does not apply if the git checkout. git will not be able to checkout a file on another branch if the file is not named the same. Example:

1. echo primeira linha > a.txt
2. git add a.txt
3. git commit -m 'adicionando arquivo a.txt'
4. git checkout novo
5. git merge master
6. git mv a.txt novoNome.txt
7. git commit -m 'alterando nome de a para novoNome'
8. git checkout master

At that point, if the command is executed git checkout novo d.txt, git will not find this file in the new branch. If the command is executed git checkout novo novoNome.txt, the subsequent file will be brought to the master branch but will not replace the old d.txt.