Git doesn't store files. Git stores commits.
Branches don't have files; branches have commits.
When you push from one Git to another, you don't push files. You push commits.
This might seem like a lot of repetition, but that's the point: you need to keep in your head that Git deals in commits. So: what exactly is a commit?
Well, internally, it consists of two parts:
There's a snapshot. This has files! Yay, finally we have some files. 😀
There is something peculiar about these files, though. They're not ordinary files. You can't work with them. They're frozen for all time, and compressed, and turned into a format that only Git can read. You can't access them or change them. They're no good for anything except archival. So we're going to need a way to get them out of Git, which we'll get to in a moment.
And, there's some metadata in each commit, such as the name and email address of the user who makes the commit.
This is what your git config --global user.name
is for. You should not set this to the empty string, and you should not set your email address to the empty string either. Git doesn't actually verify that what you set here is valid, but as good practice it's a good idea to use something real.
Every commit gets a unique hash ID at the time it gets created. From then on, that hash ID means that commit, and no other; that hash ID is forever reserved for that commit. You generally won't deal directly with hash IDs, except for certain occasions where you might use git log
and then cut-and-paste one into a git revert
or git reset
command, once you get to that point. But remember that the hash ID is how Git knows which commit is which. Branch names like master
or testbranch
serve to remember one hash ID (the hash ID that a name remembers changes over time).
To create a new branch, you ask Git to make a new branch, using some existing commit hash ID. The default hash ID is the current commit. There is always a current commit,1 and almost always a current branch name.2 When you use git checkout master
, you're asking Git to select the branch master
and therefore the last commit in that branch.
When you ask Git to create the new branch name testbranch
using git checkout -b testbranch
, you're asking Git to make the new name hold the same commit hash ID, and select that name as the current branch, and therefore that commit hash ID as the current commit. So Git doesn't change commits, but it does change branch names. Both branch names identify the same commit.
Now, let's get on to how you work with files, instead of a whole commit.
1There is an exception or two to this rule, including in a new totally-empty repository where there are no commits, but we won't deal with that here.
2The case when there's no current branch is what Git calls a detached HEAD. We won't deal with that here either.
Dealing with files
Fundamentally, each Git commit is read-only and totally unchangeable and its files are in a useless format. To make Git useful we must have it extract those files and turn them back into the computer's everyday format.
This is what git checkout
(or git switch
in Git 2.23 and later) does: you select a branch name, such as master
, and thereby a specific commit hash ID, and you ask Git to please copy the commit's files to a work area.
This work area, where files have their ordinary everyday form, is your working tree or work-tree. The two names refer to the same thing. Note that Git itself does not use this work-tree, other than to fill it in from a commit. This work-tree is for you to use.
You now use it. One of the things you can do with it is create new files. Another thing you can do is open up some existing file in an editor, edit it, and write the file back. Last, you can remove files entirely. All of these actions happen only in your work-tree. The changes you have made to your work-tree are not in any commit.
You will eventually have to put them into some commit(s). To do this you will need to use the command git commit
. You might assume that this would look at your work-tree and use the files that are there to make the new commit. That would be sensible but that is not what Git does.
Instead, Git builds a new commit from a third copy of each file. This third copy is found in Git's index.3 If you have modified a file in the work-tree, or added a new one, you must use git add
to copy the updated or new work-tree file into the index.
3Technically, the index contains a reference to the file's content, rather than an actual copy. However, until you start exploring git ls-files --stage
and git update-index
, you can just think of the index as holding a copy of the file.
Making a new commit from the index
To make the new commit, you run:
git commit
(or maybe git commit -m <message>
: if you leave out the -m
, your Git will open an editor for you to type in the message). This creates a new snapshot with metadata based on your git config
settings and what you set as your log message, explaining why you made this commit.
Git makes this new commit from the files that are in the index, with whatever data they have in as stored in the index. So the new commit you just made will now match the index. The new commit is now the current commit, and Git writes the new commit's hash ID—which is unique to this commit—into the current branch name.
Note how the initial git checkout
filled in Git's index from the commit being checked out, and how this new git commit
made the commit from whatever was in Git's index. So as a sort of general rule—with exceptions, again—the index tends to match the commit right after a git checkout
or git switch
, and also to match the commit right after a git commit
.4
So it's your changes to your work-tree in between that make things happen, but once you have changed your work-tree, you must use git add
to copy the updated files back into the index. Any new files need to be git add
-ed, which seems clear enough to new users of Git, but changes to existing files need to be git add
-ed as well, which is a bit of a surprise.5
4The exceptions to this rule get very complicated. See Checkout another branch when there are uncommitted changes on the current branch.
5Git does offer git commit -a
, which tells Git: for all files that are already in the index, do a git add
on them as needed, then do the git commit
. This is almost the equivalent of running git add -u
before committing, except for certain weird corner cases that can only be explained by noting that Git also allows for additional temporary index files, and this kind of git commit
uses them.
The index is also called the staging area: about git status
The term index and staging area both refer to the same thing. While you can't see the index directly,6 you can have Git tell you about the index / staging area.
Remember, there are three active copies of every file: the one in the current commit—this one is frozen for all time—plus the one in the index plus the one in your work-tree. The git status
command helps you out with these three copies by doing two separate comparisons.
The first comparison compares every file in the current commit with every file in the index. When those two files match, git status
says nothing. When they are different, git status
says that this file is staged for commit.
The second comparison compares every file in the index with every file in your work-tree. When those two files match, git status
says nothing. When they are different, git status
says that this file is not staged for commit.
So, if file F in your work-tree is not staged for commit
, running git add
will copy the contents of file F into the index copy of file F. Now the index copy of F won't match the committed copy, and file F will now be staged for commit
. If you change the work-tree copy again, the file will be both: it will be not-staged and staged, at the same time. This is possible because there are three copies of F.
6Technically, you can: use git ls-files --stage
to see it. Note that this command is verbose and not user-friendly even by Git standards.
Untracked files
Because your work-tree is yours, you can put files into it that are not in Git's index. When you do this, git status
will notice that there is no index copy of the file. It will say that this file is untracked.
That is all that an untracked file is: it's a file that exists in your work-tree, but not in Git's index. Because it is not in Git's index, it will not be in the next commit.7 You will need to use git add
to copy it into Git's index, so that it is now staged for commit
: the index copy, which now exists, is different from the (nonexistent) current-commit copy.
7Note that git commit -a
won't add this file: it only runs git add
on files that are in the index.
Ignored files
The git status
command is extremely useful. Use it often. Note, however, that every time you use it, it whines about your untracked files. If you have a lot of untracked files, you will get a lot of complaints from git status
.
You can list untracked files in a file named .gitignore
. If you do so, git status
will stop whining about them. The git add
command will also stop adding them to Git's index. So, by listing files that are currently untracked, and that you don't want to have tracked, you can get Git to automatically not commit them and stop whining about them.
Listing a tracked file in a .gitignore
has no effect. So .gitignore
is not really files to ignore; instead, it's files to not complain about being untracked and not automatically add with an add-all-files operation such as git add *
. But calling this file .git-do-not-complain-about-these-untracked-files-and-do-not-add-them-when-I-use-an-en-masse-add-command
would be unwieldy, so it is called .gitignore
.
Why cloning gets you a work-tree
When you run:
git clone <url>
your Git will:
- create a new empty directory;
- inside that directory, run
git init
to create an empty repository: one with no commits at all;
- use
git remote add
to add a remote to that empty repository: this remote is normally named origin
;
- do any other configuration needed inside this new empty repository;
- run
git fetch origin
to obtain the commits from the other Git, and then rename their branches, such as master
, to your own Git's remote-tracking names such as origin/master
;
- finally, run
git checkout
on some branch name, with the usual default here being master
.
This last step, the git checkout master
, creates your master
branch from your remote-tracking name origin/master
—which holds a commit hash ID, just like a branch name would, since it's copied from their Git's master
branch—and then selects that as the current branch and current commit. It's this checkout step that fills in Git's index and your work-tree. So that's why you see actual files: your Git has extracted them, from the commit that is the last commit in your master
branch. Your Git just created your master
branch to match the other Git's master
branch, which your Git is now remembering as your origin/master
.
git add
?git clone ....; git checkout -b .....
will not suddenly show up files which had not been in the original repo. Someone must have checked in them before, or your directoryname
already existed when you did the clone .