The main tool you use to examine which files are in which state: which files have changes, whether there are any new files, and so on, is the git status command.

The default output is explanatory and quite verbose. If there are no changes, for example, directly after clone, you could see something like this:

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

If the branch (you are on the master branch in this example) is a local branch intended to create changes that are to be published and to appear in the public repository, and is configured to track its upstream branch, origin/master, you would also see the information about the tracked branch:

Your branch is up-to-date with 'origin/master'.

In further examples, we will ignore it and not include this information.

Let's say you add two new files to your project, a COPYING file with the copyright and license, and a NEWS file, which is currently empty. In order to begin tracking a new COPYING file, you use git add COPYING. Accidentally, you remove the README file from the working directory with rm README. You modify Makefile and rename rand.c to random.c with git mv (without modifying it).

The default, long format, is designed to be human-readable, verbose, and descriptive:

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

        new file:   COPYING
        renamed:    src/rand.c -> src/random.c

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:   Makefile
        deleted:    README

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

        NEWS

As you can see, Git does not only describe which files have changed, but also explains how to change their status—either include in the commit, or remove from the set of pending changes (more information about commands in use in git status output can be found in Chapter 4, Managing Your Worktree). There are up to three sections present in the output:

One does not need to make use of the flexibility that the explicit staging area gives; one can simply use git add just to add new files, and git commit –a to create the commit from changes to all tracked files. In this case, you would create commit from both the Changes to be committed and Changes not staged for commit sections.

There is also a terse --short output format. Its --porcelain version is suitable for scripting because it is promised to remain stable, while --short is intended for user output and could change. For the same set of changes, this output format would look something like this:

$ git status --short
A  COPYING
 M Makefile
 D README
R  src/rand.c -> src/random.c
?? NEWS

In this format, the status of each path is shown using a two-letter status code. The first letter shows the status of the index (the difference between the staging area and the last commit), and the second letter shows the status of the worktree (the difference between the working area and the staging area):

Not all the combinations are possible. Status letters A, R, and C are possible only in the first column, for the status of the index.

A special case, ??, is used for the unknown (untracked) files and !! for ignored files (when using git status --short --ignored). Note that not all the possible outputs are described here; the case where we have just done a merge that resulted in merge conflicts is not shown in this table, but is left to be described in Chapter 7, Merging Changes Together.

If you want to know not only which files were changed (which you get with git status), but also what exactly you have changed, use the git diff command:

Fig 4. Examining the differences between the working directory, staging area, and local git repository

In the last section, we learned that in Git there are three stages: the working directory, the staging area, and the repository (usually the last commit). Therefore, we have not one set of differences but three, as shown in Fig 4. You can ask Git the following questions:

To see what you've changed but not yet staged, type git diff with no other arguments. This command compares what is in your working directory with what is in your staging area. These are the changes that could be added, but wouldn't be present if we create commit with git commit (without -a): Changes not staged for commit in the git status output.

To see what you've staged that will go into your next commit, use git diff --staged (or git diff --cached). This command compares what is in your staging area to the content of your last commit. These are the changes that would be added with git commit (without -a): Changes to be committed in the git status output. You can compare your staging area to any commit with git diff --staged <commit>; HEAD (the last commit) is just the default.

You can use git diff HEAD to compare what is in your working directory with the last commit (or arbitrary commit with git diff <commit>). These are the changes that would be added with the git commit -a shortcut.

If you are using git commit –a, and not making use of the staging area, usually it is enough to use git diff to check the changes which will be in the next commit. The only issue is the new files that are added with bare git add; they won't show in the git diff output unless you use git add --intent-to-add (or its equivalent git add -N) to add new files.

Git, by default and in most cases, will show the changes in unified diff output format. Understanding this output is very important, not only when examining changes to be committed, but also when reviewing and examining changes (for example, in code review, or in finding bugs after git bisect has found the suspected commit).

Let's take a look at an example of advanced diff from Git project history . Let's use the diff from the commit 1088261f from the git.git repository. You can view these changes in a web browser, for example, on GitHub; this is the third patch in this commit:

diff --git a/builtin-http-fetch.c b/http-fetch.c
similarity index 95%
rename from builtin-http-fetch.c
rename to http-fetch.c
index f3e63d7..e8f44ba 100644
--- a/builtin-http-fetch.c
+++ b/http-fetch.c
@@ -1,8 +1,9 @@
 #include "cache.h"
 #include "walker.h"

-int cmd_http_fetch(int argc, const char **argv, const char *prefix)
+int main(int argc, const char **argv)
 {
+       const char *prefix;
        struct walker *walker;
        int commits_on_stdin = 0;
        int commits;
@@ -18,6 +19,8 @@ int cmd_http_fetch(int argc, const char **argv,
        int get_verbosely = 0;
        int get_recover = 0;
 
+       prefix = setup_git_directory();
+
        git_config(git_default_config, NULL);
 
        while (arg < argc && argv[arg][0] == '-') {

Let's analyze this patch line after line:

So, for the example used here, first chunk means that cmd_http_fetch was replaced by main and the const char *prefix; line was added:

#include "cache.h"
#include "walker.h"

-int cmd_http_fetch(int argc, const char **argv, const char *prefix)
+int main(int argc, const char **argv)
 {
+       const char *prefix;
        struct walker *walker;
        int commits_on_stdin = 0;
        int commits;

See how for the replaced line, the old version of the line appears as removed (-) and the new version as added (+).

In other words, before the change, the appropriate fragment of the file, that was then named builtin-http-fetch.c, looked similar to the following:

#include "cache.h"
#include "walker.h"

int cmd_http_fetch(int argc, const char **argv, const char *prefix)
{
       struct walker *walker;
       int commits_on_stdin = 0;
       int commits;

After the change, this fragment of the file that is now named http-fetch.c, looks similar to this instead:

#include "cache.h"
#include "walker.h"
 
int main(int argc, const char **argv)
{
       const char *prefix;
       struct walker *walker;
       int commits_on_stdin = 0;
       int commits;

The simplest situation is when these unrelated changes touch different files. For example, if the bug was in the view/entry.tmpl file and only in this file, and there were no other changes to this file, you can create a bug fix commit with the following command:

$ git commit view/entry.tmpl

This command will ignore changes staged in the index (what was in the staging area), and instead record the current contents of a given file or files (what is in the working directory).

Sometimes, however, the changes cannot be separated in this way. The changes to the file are tangled together. You can try to tease them apart by giving the --interactive option to git commit:

$ git commit --interactive
           staged     unstaged path
  1:    unchanged        +3/-2 Makefile
  2:    unchanged       +64/-1 src/rand.c

*** Commands ***
  1: status       2: update       3: revert       4: add untracked
  5: patch        6: diff         7: quit         8: help
What now>

Here, Git shows us the status and the summary of changes to the working area (unstaged) and to the staging area / the index (staged)—the output of the status subcommand. The changes are described by the number of added and deleted files (similar to what the git diff --numstat command shows):

What now> h
status        - show paths with changes
update        - add working tree state to the staged set of changes
revert        - revert staged set of changes back to the HEAD version
patch         - pick hunks and update selectively
diff          - view diff between HEAD and index
add untracked - add contents of untracked files to the staged set of changes
*** Commands ***
  1: status       2: update       3: revert       4: add untracked
  5: patch        6: diff         7: quit         8: help

To tease apart changes, you need to choose the patch subcommand (for example, with 5 or s). Git will then ask for the files with the Update>> prompt; you then need to select the files to selectively update with their numeric identifiers, as shown in the status, and type return. You can say * to select all the files possible. After making the selection, end it by answering with an empty line. (You can skip directly to patching files with the --patch option.)

Git will then display all the changes to the specified files on a hunk-by-hunk basis, and let you choose, among others, one of the following options for each hunk:

       y - stage this hunk
       n - do not stage this hunk
       q - quit; do not stage this hunk or any of the remaining ones

       s - split the current hunk into smaller hunks
       e - manually edit the current hunk
       ? - print help

The hunk output and the prompt look similar to this:

@@ -16,7 +15,6 @@ int main(int argc, char *argv[])

        int max = atoi(argv[1]);

+       srand(time(NULL));
        int result = random_int(max);
        printf("%d
", result);

Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]? y

In many cases, it is enough to simply select which of those hunks of changes you want to have in the commit. In extreme cases, you can split a chunk into smaller pieces, or even manually edit the diff.

Interactively selecting changes to commit with git commit --interactive doesn't unfortunately allow to test the changes to be committed. You can always check that everything works after creating a commit (compile and/or run tests), and then amend it if there are any errors. There is, however, an alternative solution.

You can prepare commit by putting the pending changes into the staging area with git add --interactive, or an equivalent solution (like graphical Git commit tool for Git, for example, git gui). The interactive commit is just a shortcut for interactive add followed by commit, anyway. Then you should examine these changes with git diff --cached, modifying them as appropriate with git add <file>, git checkout <file>, and git reset <file>.

In theory, you should also test these changes whether they are correct, checking that at least they do not break the build. To do this, first use git stash save --keep-index to save the current state and bring the working directory to the state prepared in the staging area (the index). After this command, you can run tests (or at least check whether the program compiles and doesn't crash). If tests pass, you can then run git commit to create a new revision. If tests fail, you should restore the working directory while keeping the staging area state with the git stash pop --index command; it might be required to precede it with git reset --hard. The latter might be needed because Git is overly conservative when preserving your work, and does not know that you have just stashed. First, there are uncommitted changes in the index prevent Git from applying the stash, and second, the changes to the working directory are the same as stashed, so of course they would conflict.

You can find more information about stashes, including how they work, in Chapter 4, Managing Your Worktree.