NAME
git-add - Add file contents to the index
SYNOPSIS
git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
[--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]
[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]
[--] [<pathspec>…]
DESCRIPTION
This command updates the index using the current content found in the working tree, to prepare the content staged for the next commit. It typically adds the current content of existing paths as a whole, but with some options it can also be used to add content with only part of the changes made to the working tree files applied, or remove paths that do not exist in the working tree anymore.
The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus after making any changes to the working directory, and before running the commit command, you must use the add
command to add any new or modified files to the index.
This command can be performed multiple times before a commit. It only adds the content of the specified file(s) at the time the add command is run; if you want subsequent changes included in the next commit, then you must run git add
again to add the new content to the index.
The git status
command can be used to obtain a summary of which files have changes that are staged for the next commit.
The git add
command will not add ignored files by default. If any ignored files were explicitly specified on the command line, git add
will fail with a list of ignored files. Ignored files reached by directory recursion or filename globbing performed by Git (quote your globs before the shell) will be silently ignored. The git add command can be used to add ignored files with the -f
(force) option.
Please see git-commit[1] for alternative ways to add content to a commit.
OPTIONS
-
<pathspec>…
-
Files to add content from. Fileglobs (e.g.
*.c
) can be given to add all matching files. Also a leading directory name (e.g.dir
to adddir/file1
anddir/file2
) can be given to update the index to match the current state of the directory as a whole (e.g. specifyingdir
will record not just a filedir/file1
modified in the working tree, a filedir/file2
added to the working tree, but also a filedir/file3
removed from the working tree. Note that older versions of Git used to ignore removed files; use--no-all
option if you want to add modified or new files but ignore removed ones.
-n
--dry-run
-
Don’t actually add the file(s), just show if they exist and/or will be ignored.
-v
--verbose
-
Be verbose.
-f
--force
-
Allow adding otherwise ignored files.
-i
--interactive
-
Add modified contents in the working tree interactively to the index. Optional path arguments may be supplied to limit operation to a subset of the working tree. See “Interactive mode” for details.
-p
--patch
-
Interactively choose hunks of patch between the index and the work tree and add them to the index. This gives the user a chance to review the difference before adding modified contents to the index.
This effectively runs
add --interactive
, but bypasses the initial command menu and directly jumps to thepatch
subcommand. See “Interactive mode” for details.
-e
--edit
-
Open the diff vs. the index in an editor and let the user edit it. After the editor was closed, adjust the hunk headers and apply the patch to the index.
The intent of this option is to pick and choose lines of the patch to apply, or even to modify the contents of lines to be staged. This can be quicker and more flexible than using the interactive hunk selector. However, it is easy to confuse oneself and create a patch that does not apply to the index. See EDITING PATCHES below.
-u
--update
-
Update the index just where it already has an entry matching <pathspec>. This removes as well as modifies index entries to match the working tree, but adds no new files.
If no <pathspec> is given when
-u
option is used, all tracked files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories).
-A
--all
--no-ignore-removal
-
Update the index not only where the working tree has a file matching <pathspec> but also where the index already has an entry. This adds, modifies, and removes index entries to match the working tree.
If no <pathspec> is given when
-A
option is used, all files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories).
--no-all
--ignore-removal
-
Update the index by adding new files that are unknown to the index and files modified in the working tree, but ignore files that have been removed from the working tree. This option is a no-op when no <pathspec> is used.
This option is primarily to help users who are used to older versions of Git, whose "git add <pathspec>…" was a synonym for "git add --no-all <pathspec>…", i.e. ignored removed files.
-N
--intent-to-add
-
Record only the fact that the path will be added later. An entry for the path is placed in the index with no content. This is useful for, among other things, showing the unstaged content of such files with
git diff
and committing them withgit commit -a
.
--refresh
-
Don’t add the file(s), but only refresh their stat() information in the index.
--ignore-errors
-
If some files could not be added because of errors indexing them, do not abort the operation, but continue adding the others. The command shall still exit with non-zero status. The configuration variable
add.ignoreErrors
can be set to true to make this the default behaviour.
--ignore-missing
-
This option can only be used together with --dry-run. By using this option the user can check if any of the given files would be ignored, no matter if they are already present in the work tree or not.
--
-
This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options).
Configuration
The optional configuration variable core.excludesFile
indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to those in info/exclude. See gitignore[5].
EXAMPLES
-
Adds content from all
*.txt
files underDocumentation
directory and its subdirectories:$ git add Documentation/\*.txt
Note that the asterisk
*
is quoted from the shell in this example; this lets the command include the files from subdirectories ofDocumentation/
directory. -
Considers adding content from all git-*.sh scripts:
$ git add git-*.sh
Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not consider
subdir/git-foo.sh
.
Interactive mode
When the command enters the interactive mode, it shows the output of the status subcommand, and then goes into its interactive command loop.
The command loop shows the list of subcommands available, and gives a prompt "What now> ". In general, when the prompt ends with a single >, you can pick only one of the choices given and type return, like this:
*** Commands *** 1: status 2: update 3: revert 4: add untracked 5: patch 6: diff 7: quit 8: help What now> 1
You also could say s
or sta
or status
above as long as the choice is unique.
The main command loop has 6 subcommands (plus help and quit).
-
status
-
This shows the change between HEAD and index (i.e. what will be committed if you say
git commit
), and between index and working tree files (i.e. what you could stage further beforegit commit
usinggit add
) for each path. A sample output looks like this:staged unstaged path 1: binary nothing foo.png 2: +403/-35 +1/-1 git-add--interactive.perl
It shows that foo.png has differences from HEAD (but that is binary so line count cannot be shown) and there is no difference between indexed copy and the working tree version (if the working tree version were also different, binary would have been shown in place of nothing). The other file, git-add{litdd}interactive.perl, has 403 lines added and 35 lines deleted if you commit what is in the index, but working tree file has further modifications (one addition and one deletion).
update
-
This shows the status information and issues an "Update>>" prompt. When the prompt ends with double >>, you can make more than one selection, concatenated with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" to choose 2,3,4,5,7,9 from the list. If the second number in a range is omitted, all remaining patches are taken. E.g. "7-" to choose 7,8,9 from the list. You can say * to choose everything.
What you chose are then highlighted with *, like this:
staged unstaged path 1: binary nothing foo.png * 2: +403/-35 +1/-1 git-add--interactive.perl
To remove selection, prefix the input with
-
like this:Update>> -2
After making the selection, answer with an empty line to stage the contents of working tree files for selected paths in the index.
revert
-
This has a very similar UI to update, and the staged information for selected paths are reverted to that of the HEAD version. Reverting new paths makes them untracked.
add untracked
-
This has a very similar UI to update and revert, and lets you add untracked paths to the index.
patch
-
This lets you choose one path out of a status like selection. After choosing the path, it presents the diff between the index and the working tree file and asks you if you want to stage the change of each hunk. You can select one of the following options and type return:
y - stage this hunk n - do not stage this hunk q - quit; do not stage this hunk or any of the remaining ones a - stage this hunk and all later hunks in the file d - do not stage this hunk or any of the later hunks in the file g - select a hunk to go to / - search for a hunk matching the given regex j - leave this hunk undecided, see next undecided hunk J - leave this hunk undecided, see next hunk k - leave this hunk undecided, see previous undecided hunk K - leave this hunk undecided, see previous hunk s - split the current hunk into smaller hunks e - manually edit the current hunk ? - print help
After deciding the fate for all hunks, if there is any hunk that was chosen, the index is updated with the selected hunks.
You can omit having to type return here, by setting the configuration variable
interactive.singleKey
totrue
.
diff
-
This lets you review what will be committed (i.e. between HEAD and index).
EDITING PATCHES
Invoking git add -e
or selecting e
from the interactive hunk selector will open a patch in your editor; after the editor exits, the result is applied to the index. You are free to make arbitrary changes to the patch, but note that some changes may have confusing results, or even result in a patch that cannot be applied. If you want to abort the operation entirely (i.e., stage nothing new in the index), simply delete all lines of the patch. The list below describes some common things you may see in a patch, and which editing operations make sense on them.
-
added content
-
Added content is represented by lines beginning with "+". You can prevent staging any addition lines by deleting them.
removed content
-
Removed content is represented by lines beginning with "-". You can prevent staging their removal by converting the "-" to a " " (space).
modified content
-
Modified content is represented by "-" lines (removing the old content) followed by "+" lines (adding the replacement content). You can prevent staging the modification by converting "-" lines to " ", and removing "+" lines. Beware that modifying only half of the pair is likely to introduce confusing changes to the index.
There are also more complex operations that can be performed. But beware that because the patch is applied only to the index and not the working tree, the working tree will appear to "undo" the change in the index. For example, introducing a new line into the index that is in neither the HEAD nor the working tree will stage the new line for commit, but the line will appear to be reverted in the working tree.
Avoid using these constructs, or do so with extreme caution.
-
removing untouched content
-
Content which does not differ between the index and working tree may be shown on context lines, beginning with a " " (space). You can stage context lines for removal by converting the space to a "-". The resulting working tree file will appear to re-add the content.
modifying existing content
-
One can also modify context lines by staging them for removal (by converting " " to "-") and adding a "+" line with the new content. Similarly, one can modify "+" lines for existing additions or modifications. In all cases, the new modification will appear reverted in the working tree.
new content
-
You may also add new content that does not exist in the patch; simply add new lines, each starting with "+". The addition will appear reverted in the working tree.
There are also several operations which should be avoided entirely, as they will make the patch impossible to apply:
-
adding context (" ") or removal ("-") lines
-
deleting context or removal lines
-
modifying the contents of context or removal lines
GIT
Part of the git[1] suite
AME
git-status - Show the working tree status
SYNOPSIS
git status [<options>…] [--] [<pathspec>…]
DESCRIPTION
Displays paths that have differences between the index file and the current HEAD commit, paths that have differences between the working tree and the index file, and paths in the working tree that are not tracked by Git (and are not ignored by gitignore[5]). The first are what you wouldcommit by running git commit
; the second and third are what you could commit by running git add before running git commit
.
OPTIONS
-
-s
--short
-
Give the output in the short-format.
-b
--branch
-
Show the branch and tracking info even in short-format.
--porcelain
-
Give the output in an easy-to-parse format for scripts. This is similar to the short output, but will remain stable across Git versions and regardless of user configuration. See below for details.
--long
-
Give the output in the long-format. This is the default.
-v
--verbose
-
In addition to the names of files that have been changed, also show the textual changes that are staged to be committed (i.e., like the output of
git diff --cached
). If-v
is specified twice, then also show the changes in the working tree that have not yet been staged (i.e., like the output ofgit diff
).
-u[<mode>]
--untracked-files[=<mode>]
-
Show untracked files.
The mode parameter is used to specify the handling of untracked files. It is optional: it defaults toall, and if specified, it must be stuck to the option (e.g.
-uno
, but not-u no
).The possible options are:
-
no - Show no untracked files.
-
normal - Shows untracked files and directories.
-
all - Also shows individual files in untracked directories.
When
-u
option is not used, untracked files and directories are shown (i.e. the same as specifyingnormal
), to help you avoid forgetting to add newly created files. Because it takes extra work to find untracked files in the filesystem, this mode may take some time in a large working tree. Consider enabling untracked cache and split index if supported (seegit update-index --untracked-cache
andgit update-index --split-index
), Otherwise you can useno
to havegit status
return more quickly without showing untracked files.The default can be changed using the status.showUntrackedFiles configuration variable documented in git-config[1].
--ignore-submodules[=<when>]
-
-
Ignore changes to submodules when looking for changes. <when> can be either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the ignore option in git-config[1] or gitmodules[5]. When "untracked" is used submodules are not considered dirty when they only contain untracked content (but they are still scanned for modified content). Using "dirty" ignores all changes to the work tree of submodules, only changes to the commits stored in the superproject are shown (this was the behavior before 1.7.0). Using "all" hides all changes to submodules (and suppresses the output of submodule summaries when the config option
status.submoduleSummary
is set).
--ignored
-
Show ignored files as well.
-z
-
Terminate entries with NUL, instead of LF. This implies the
--porcelain
output format if no other format is given.
--column[=<options>]
--no-column
-
Display untracked files in columns. See configuration variable column.status for option syntax.
--column
and--no-column
without options are equivalent to always and never respectively.
OUTPUT
The output from this command is designed to be used as a commit template comment. The default, long format, is designed to be human readable, verbose and descriptive. Its contents and format are subject to change at any time.
The paths mentioned in the output, unlike many other Git commands, are made relative to the current directory if you are working in a subdirectory (this is on purpose, to help cutting and pasting). See the status.relativePaths config option below.
Short Format
In the short-format, the status of each path is shown as
XY PATH1 -> PATH2
where PATH1
is the path in the HEAD
, and the " -> PATH2
" part is shown only when PATH1
corresponds to a different path in the index/worktree (i.e. the file is renamed). The XY
is a two-letter status code.
The fields (including the ->
) are separated from each other by a single space. If a filename contains whitespace or other nonprintable characters, that field will be quoted in the manner of a C string literal: surrounded by ASCII double quote (34) characters, and with interior special characters backslash-escaped.
For paths with merge conflicts, X
and Y
show the modification states of each side of the merge. For paths that do not have merge conflicts, X
shows the status of the index, and Y
shows the status of the work tree. For untracked paths, XY
are ??
. Other status codes can be interpreted as follows:
-
' ' = unmodified
-
M = modified
-
A = added
-
D = deleted
-
R = renamed
-
C = copied
-
U = updated but unmerged
Ignored files are not listed, unless --ignored
option is in effect, in which case XY
are !!
.
X Y Meaning ------------------------------------------------- [MD] not updated M [ MD] updated in index A [ MD] added to index D [ M] deleted from index R [ MD] renamed in index C [ MD] copied in index [MARC] index and work tree matches [ MARC] M work tree changed since index [ MARC] D deleted in work tree ------------------------------------------------- D D unmerged, both deleted A U unmerged, added by us U D unmerged, deleted by them U A unmerged, added by them D U unmerged, deleted by us A A unmerged, both added U U unmerged, both modified ------------------------------------------------- ? ? untracked ! ! ignored -------------------------------------------------
If -b is used the short-format status is preceded by a line
branchname tracking info
Porcelain Format
The porcelain format is similar to the short format, but is guaranteed not to change in a backwards-incompatible way between Git versions or based on user configuration. This makes it ideal for parsing by scripts. The description of the short format above also describes the porcelain format, with a few exceptions:
-
The user’s color.status configuration is not respected; color will always be off.
-
The user’s status.relativePaths configuration is not respected; paths shown will always be relative to the repository root.
There is also an alternate -z format recommended for machine parsing. In that format, the status field is the same, but some other things change. First, the -> is omitted from rename entries and the field order is reversed (e.g from -> to becomes to from). Second, a NUL (ASCII 0) follows each filename, replacing space as a field separator and the terminating newline (but a space still separates the status field from the first filename). Third, filenames containing special characters are not specially formatted; no quoting or backslash-escaping is performed.
CONFIGURATION
The command honors color.status
(or status.color
— they mean the same thing and the latter is kept for backward compatibility) and color.status.<slot>
configuration variables to colorize its output.
If the config variable status.relativePaths
is set to false, then all paths shown are relative to the repository root, not to the current directory.
If status.submoduleSummary
is set to a non zero number or true (identical to -1 or an unlimited number), the submodule summary will be enabled for the long format and a summary of commits for modified submodules will be shown (see --summary-limit option of git-submodule[1]). Please note that the summary output from the status command will be suppressed for all submodules whendiff.ignoreSubmodules
is set to all or only for those submodules where submodule.<name>.ignore=all
. To also view the summary for ignored submodules you can either use the --ignore-submodules=dirty command line option or the git submodule summary command, which shows a similar output but does not honor these settings.
SEE ALSO
GIT
Part of the git[1] suite
NAME
git-diff - Show changes between commits, commit and working tree, etc
SYNOPSIS
git diff [options] [<commit>] [--] [<path>…] git diff [options] --cached [<commit>] [--] [<path>…] git diff [options] <commit> <commit> [--] [<path>…] git diff [options] <blob> <blob> git diff [options] [--no-index] [--] <path> <path>
DESCRIPTION
Show changes between the working tree and the index or a tree, changes between the index and a tree, changes between two trees, changes between two blob objects, or changes between two files on disk.
-
git diff [--options] [--] [<path>…]
-
This form is to view the changes you made relative to the index (staging area for the next commit). In other words, the differences are what you could tell Git to further add to the index but you still haven’t. You can stage these changes by using git-add[1].
git diff --no-index [--options] [--] [<path>…]
-
This form is to compare the given two paths on the filesystem. You can omit the
--no-index
option when running the command in a working tree controlled by Git and at least one of the paths points outside the working tree, or when running the command outside a working tree controlled by Git.
git diff [--options] --cached [<commit>] [--] [<path>…]
-
This form is to view the changes you staged for the next commit relative to the named <commit>. Typically you would want comparison with the latest commit, so if you do not give <commit>, it defaults to HEAD. If HEAD does not exist (e.g. unborn branches) and <commit> is not given, it shows all staged changes. --staged is a synonym of --cached.
git diff [--options] <commit> [--] [<path>…]
-
This form is to view the changes you have in your working tree relative to the named <commit>. You can use HEAD to compare it with the latest commit, or a branch name to compare with the tip of a different branch.
git diff [--options] <commit> <commit> [--] [<path>…]
-
This is to view the changes between two arbitrary <commit>.
git diff [--options] <commit>..<commit> [--] [<path>…]
-
This is synonymous to the previous form. If <commit> on one side is omitted, it will have the same effect as using HEAD instead.
git diff [--options] <commit>...<commit> [--] [<path>…]
-
This form is to view the changes on the branch containing and up to the second <commit>, starting at a common ancestor of both <commit>. "git diff A...B" is equivalent to "git diff $(git-merge-base A B) B". You can omit any one of <commit>, which has the same effect as using HEAD instead.
Just in case if you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the last two forms that use ".." notations, can be any <tree>.
For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section ingitrevisions[7]. However, "diff" is about comparing two endpoints, not ranges, and the range notations ("<commit>..<commit>" and "<commit>...<commit>") do not mean a range as defined in the "SPECIFYING RANGES" section in gitrevisions[7].
-
git diff [options] <blob> <blob>
-
This form is to view the differences between the raw contents of two blob objects.
OPTIONS
-
-p
-u
--patch
-
Generate patch (see section on generating patches). This is the default.
-s
--no-patch
-
Suppress diff output. Useful for commands like
git show
that show the patch by default, or to cancel the effect of--patch
.
-U<n>
--unified=<n>
-
Generate diffs with <n> lines of context instead of the usual three. Implies
-p
.
--raw
-
Generate the diff in raw format.
--patch-with-raw
-
Synonym for
-p --raw
.
--minimal
-
Spend extra time to make sure the smallest possible diff is produced.
--patience
-
Generate a diff using the "patience diff" algorithm.
--histogram
-
Generate a diff using the "histogram diff" algorithm.
--diff-algorithm={patience|minimal|histogram|myers}
-
Choose a diff algorithm. The variants are as follows:
-
The basic greedy diff algorithm. Currently, this is the default.
-
Spend extra time to make sure the smallest possible diff is produced.
-
Use "patience diff" algorithm when generating patches.
-
This algorithm extends the patience algorithm to "support low-occurrence common elements".
default
,myers
minimal
patience
histogram
For instance, if you configured diff.algorithm variable to a non-default value and want to use the default one, then you have to use
--diff-algorithm=default
option.
--stat[=<width>[,<name-width>[,<count>]]]
-
-
Generate a diffstat. By default, as much space as necessary will be used for the filename part, and the rest for the graph part. Maximum width defaults to terminal width, or 80 columns if not connected to a terminal, and can be overridden by
<width>
. The width of the filename part can be limited by giving another width<name-width>
after a comma. The width of the graph part can be limited by using--stat-graph-width=<width>
(affects all commands generating a stat graph) or by settingdiff.statGraphWidth=<width>
(does not affectgit format-patch
). By giving a third parameter<count>
, you can limit the output to the first<count>
lines, followed by...
if there are more.These parameters can also be set individually with
--stat-width=<width>
,--stat-name-width=<name-width>
and--stat-count=<count>
.
--numstat
-
Similar to
--stat
, but shows number of added and deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. For binary files, outputs two-
instead of saying0 0
.
--shortstat
-
Output only the last line of the
--stat
format containing total number of modified files, as well as number of added and deleted lines.
--dirstat[=<param1,param2,…>]
-
Output the distribution of relative amount of changes for each sub-directory. The behavior of
--dirstat
can be customized by passing it a comma separated list of parameters. The defaults are controlled by thediff.dirstat
configuration variable (see git-config[1]). The following parameters are available:-
Compute the dirstat numbers by counting the lines that have been removed from the source, or added to the destination. This ignores the amount of pure code movements within a file. In other words, rearranging lines in a file is not counted as much as other changes. This is the default behavior when no parameter is given.
-
Compute the dirstat numbers by doing the regular line-based diff analysis, and summing the removed/added line counts. (For binary files, count 64-byte chunks instead, since binary files have no natural concept of lines). This is a more expensive
--dirstat
behavior than thechanges
behavior, but it does count rearranged lines within a file as much as other changes. The resulting output is consistent with what you get from the other--*stat
options. -
Compute the dirstat numbers by counting the number of files changed. Each changed file counts equally in the dirstat analysis. This is the computationally cheapest
--dirstat
behavior, since it does not have to look at the file contents at all. -
Count changes in a child directory for the parent directory as well. Note that when using
cumulative
, the sum of the percentages reported may exceed 100%. The default (non-cumulative) behavior can be specified with thenoncumulative
parameter.
<limit>
-
An integer parameter specifies a cut-off percent (3% by default). Directories contributing less than this percentage of the changes are not shown in the output.
changes
lines
files
cumulative
Example: The following will count changed files, while ignoring directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories:
--dirstat=files,10,cumulative
.
--summary
-
-
Output a condensed summary of extended header information such as creations, renames and mode changes.
--patch-with-stat
-
Synonym for
-p --stat
.
-z
-
When
--raw
,--numstat
,--name-only
or--name-status
has been given, do not munge pathnames and use NULs as output field terminators.Without this option, each pathname output will have TAB, LF, double quotes, and backslash characters replaced with
\t
,\n
,\"
, and\\
, respectively, and the pathname will be enclosed in double quotes if any of those replacements occurred.
--name-only
-
Show only names of changed files.
--name-status
-
Show only names and status of changed files. See the description of the
--diff-filter
option on what the status letters mean.
--submodule[=<format>]
-
Specify how differences in submodules are shown. When
--submodule
or--submodule=log
is given, the log format is used. This format lists the commits in the range like git-submodule[1]summary
does. Omitting the--submodule
option or specifying--submodule=short
, uses the short format. This format just shows the names of the commits at the beginning and end of the range. Can be tweaked via thediff.submodule
configuration variable.
--color[=<when>]
-
Show colored diff.
--color
(i.e. without =<when>) is the same as--color=always
. <when>can be one ofalways
,never
, orauto
. It can be changed by thecolor.ui
andcolor.diff
configuration settings.
--no-color
-
Turn off colored diff. This can be used to override configuration settings. It is the same as
--color=never
.
--word-diff[=<mode>]
-
Show a word diff, using the <mode> to delimit changed words. By default, words are delimited by whitespace; see
--word-diff-regex
below. The <mode> defaults to plain, and must be one of:-
color
-
Highlight changed words using only colors. Implies
--color
.
plain
-
Show words as
[-removed-]
and{+added+}
. Makes no attempts to escape the delimiters if they appear in the input, so the output may be ambiguous.
porcelain
-
Use a special line-based format intended for script consumption. Added/removed/unchanged runs are printed in the usual unified diff format, starting with a
+
/-
/` ` character at the beginning of the line and extending to the end of the line. Newlines in the input are represented by a tilde~
on a line of its own.
none
-
Disable word diff again.
Note that despite the name of the first mode, color is used to highlight the changed parts in all modes if enabled.
--word-diff-regex=<regex>
-
-
Use <regex> to decide what a word is, instead of considering runs of non-whitespace to be a word. Also implies
--word-diff
unless it was already enabled.Every non-overlapping match of the <regex> is considered a word. Anything between these matches is considered whitespace and ignored(!) for the purposes of finding differences. You may want to append
|[^[:space:]]
to your regular expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline.For example,
--word-diff-regex=.
will treat each character as a word and, correspondingly, show differences character by character.The regex can also be set via a diff driver or configuration option, see gitattributes[1] or git-config[1]. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings.
--color-words[=<regex>]
-
Equivalent to
--word-diff=color
plus (if a regex was specified)--word-diff-regex=<regex>
.
--no-renames
-
Turn off rename detection, even when the configuration file gives the default to do so.
--check
-
Warn if changes introduce whitespace errors. What are considered whitespace errors is controlled by
core.whitespace
configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the initial indent of the line are considered whitespace errors. Exits with non-zero status if problems are found. Not compatible with --exit-code.
--ws-error-highlight=<kind>
-
Highlight whitespace errors on lines specified by <kind> in the color specified by
color.diff.whitespace
. <kind> is a comma separated list ofold
,new
,context
. When this option is not given, only whitespace errors innew
lines are highlighted. E.g.--ws-error-highlight=new,old
highlights whitespace errors on both deleted and added lines.all
can be used as a short-hand forold,new,context
.
--full-index
-
Instead of the first handful of characters, show the full pre- and post-image blob object names on the "index" line when generating patch format output.
--binary
-
In addition to
--full-index
, output a binary diff that can be applied withgit-apply
.
--abbrev[=<n>]
-
Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header lines, show only a partial prefix. This is independent of the
--full-index
option above, which controls the diff-patch output format. Non default number of digits can be specified with--abbrev=<n>
.
-B[<n>][/<m>]
--break-rewrites[=[<n>][/<m>]]
-
Break complete rewrite changes into pairs of delete and create. This serves two purposes:
It affects the way a change that amounts to a total rewrite of a file not as a series of deletion and insertion mixed together with a very few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number
m
controls this aspect of the -B option (defaults to 60%).-B/70%
specifies that less than 30% of the original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines).When used with -M, a totally-rewritten file is also considered as the source of a rename (usually -M only considers a file that disappeared as the source of a rename), and the number
n
controls this aspect of the -B option (defaults to 50%).-B20%
specifies that a change with addition and deletion compared to 20% or more of the file’s size are eligible for being picked up as a possible source of a rename to another file.
-M[<n>]
--find-renames[=<n>]
-
Detect renames. If
n
is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the file’s size). For example,-M90%
means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn’t changed. Without a%
sign, the number is to be read as a fraction, with a decimal point before it. I.e.,-M5
becomes 0.5, and is thus the same as-M50%
. Similarly,-M05
is the same as-M5%
. To limit detection to exact renames, use-M100%
. The default similarity index is 50%.
-C[<n>]
--find-copies[=<n>]
-
Detect copies as well as renames. See also
--find-copies-harder
. Ifn
is specified, it has the same meaning as for-M<n>
.
--find-copies-harder
-
For performance reasons, by default,
-C
option finds copies only if the original file of the copy was modified in the same changeset. This flag makes the command inspect unmodified files as candidates for the source of copy. This is a very expensive operation for large projects, so use it with caution. Giving more than one-C
option has the same effect.
-D
--irreversible-delete
-
Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and
/dev/null
. The resulting patch is not meant to be applied withpatch
orgit apply
; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, hence the name of the option.When used together with
-B
, omit also the preimage in the deletion part of a delete/create pair.
-l<num>
-
The
-M
and-C
options require O(n^2) processing time where n is the number of potential rename/copy targets. This option prevents rename/copy detection from running if the number of rename/copy targets exceeds the specified number.
--diff-filter=[(A|C|D|M|R|T|U|X|B)…[*]]
-
Select only files that are Added (
A
), Copied (C
), Deleted (D
), Modified (M
), Renamed (R
), have their type (i.e. regular file, symlink, submodule, …) changed (T
), are Unmerged (U
), are Unknown (X
), or have had their pairing Broken (B
). Any combination of the filter characters (including none) can be used. When*
(All-or-none) is added to the combination, all paths are selected if there is any file that matches other criteria in the comparison; if there is no file that matches other criteria, nothing is selected.
-S<string>
-
Look for differences that change the number of occurrences of the specified string (i.e. addition/deletion) in a file. Intended for the scripter’s use.
It is useful when you’re looking for an exact block of code (like a struct), and want to know the history of that block since it first came into being: use the feature iteratively to feed the interesting block in the preimage back into
-S
, and keep going until you get the very first version of the block.
-G<regex>
-
Look for differences whose patch text contains added/removed lines that match <regex>.
To illustrate the difference between
-S<regex> --pickaxe-regex
and-G<regex>
, consider a commit with the following diff in the same file:+ return !regexec(regexp, two->ptr, 1, ®match, 0); ... - hit = !regexec(regexp, mf2.ptr, 1, ®match, 0);
While
git log -G"regexec\(regexp"
will show this commit,git log -S"regexec\(regexp" --pickaxe-regex
will not (because the number of occurrences of that string did not change).See the pickaxe entry in gitdiffcore[7] for more information.
--pickaxe-all
-
When
-S
or-G
finds a change, show all the changes in that changeset, not just the files that contain the change in <string>.
--pickaxe-regex
-
Treat the <string> given to
-S
as an extended POSIX regular expression to match.
-O<orderfile>
-
Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. This overrides the
diff.orderFile
configuration variable (see git-config[1]). To canceldiff.orderFile
, use-O/dev/null
.
-R
-
Swap two inputs; that is, show differences from index or on-disk file to tree contents.
--relative[=<path>]
-
When run from a subdirectory of the project, it can be told to exclude changes outside the directory and show pathnames relative to it with this option. When you are not in a subdirectory (e.g. in a bare repository), you can name which subdirectory to make the output relative to by giving a <path> as an argument.
-a
--text
-
Treat all files as text.
--ignore-space-at-eol
-
Ignore changes in whitespace at EOL.
-b
--ignore-space-change
-
Ignore changes in amount of whitespace. This ignores whitespace at line end, and considers all other sequences of one or more whitespace characters to be equivalent.
-w
--ignore-all-space
-
Ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none.
--ignore-blank-lines
-
Ignore changes whose lines are all blank.
--inter-hunk-context=<lines>
-
Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other.
-W
--function-context
-
Show whole surrounding functions of changes.
--exit-code
-
Make the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and 0 means no differences.
--quiet
-
Disable all output of the program. Implies
--exit-code
.
--ext-diff
-
Allow an external diff helper to be executed. If you set an external diff driver with gitattributes[5], you need to use this option with git-log[1] and friends.
--no-ext-diff
-
Disallow external diff drivers.
--textconv
--no-textconv
-
Allow (or disallow) external text conversion filters to be run when comparing binary files. Seegitattributes[5] for details. Because textconv filters are typically a one-way conversion, the resulting diff is suitable for human consumption, but cannot be applied. For this reason, textconv filters are enabled by default only for git-diff[1] and git-log[1], but not for git-format-patch[1] or diff plumbing commands.
--ignore-submodules[=<when>]
-
Ignore changes to submodules in the diff generation. <when> can be either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the ignore option in git-config[1] orgitmodules[5]. When "untracked" is used submodules are not considered dirty when they only contain untracked content (but they are still scanned for modified content). Using "dirty" ignores all changes to the work tree of submodules, only changes to the commits stored in the superproject are shown (this was the behavior until 1.7.0). Using "all" hides all changes to submodules.
--src-prefix=<prefix>
-
Show the given source prefix instead of "a/".
--dst-prefix=<prefix>
-
Show the given destination prefix instead of "b/".
--no-prefix
-
Do not show any source or destination prefix.
For more detailed explanation on these common options, see also gitdiffcore[7].
-
<path>…
-
The <paths> parameters, when given, are used to limit the diff to the named paths (you can give directory names and get diff for all files under them).
Raw output format
The raw output format from "git-diff-index", "git-diff-tree", "git-diff-files" and "git diff --raw" are very similar.
These commands all compare two sets of things; what is compared differs:
-
git-diff-index <tree-ish>
-
compares the <tree-ish> and the files on the filesystem.
git-diff-index --cached <tree-ish>
-
compares the <tree-ish> and the index.
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…]
-
compares the trees named by the two arguments.
git-diff-files [<pattern>…]
-
compares the index and the files on the filesystem.
The "git-diff-tree" command begins its output by printing the hash of what is being compared. After that, all the commands print one output line per changed file.
An output line is formatted this way:
in-place edit :100644 100644 bcd1234... 0123456... M file0 copy-edit :100644 100644 abcd123... 1234567... C68 file1 file2 rename-edit :100644 100644 abcd123... 1234567... R86 file1 file3 create :000000 100644 0000000... 1234567... A file4 delete :100644 000000 1234567... 0000000... D file5 unmerged :000000 000000 0000000... 0000000... U file6
That is, from the left to the right:
-
a colon.
-
mode for "src"; 000000 if creation or unmerged.
-
a space.
-
mode for "dst"; 000000 if deletion or unmerged.
-
a space.
-
sha1 for "src"; 0{40} if creation or unmerged.
-
a space.
-
sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree".
-
a space.
-
status, followed by optional "score" number.
-
a tab or a NUL when -z option is used.
-
path for "src"
-
a tab or a NUL when -z option is used; only exists for C or R.
-
path for "dst"; only exists for C or R.
-
an LF or a NUL when -z option is used, to terminate the record.
Possible status letters are:
-
A: addition of a file
-
C: copy of a file into a new one
-
D: deletion of a file
-
M: modification of the contents or mode of a file
-
R: renaming of a file
-
T: change in the type of the file
-
U: file is unmerged (you must complete the merge before it can be committed)
-
X: "unknown" change type (most probably a bug, please report it)
Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites.
<sha1> is shown as all 0’s if a file is new on the filesystem and it is out of sync with the index.
Example:
:100644 100644 5be4a4...... 000000...... M file.c
When -z
option is not used, TAB, LF, and backslash characters in pathnames are represented as\t
, \n
, and \\
, respectively.
diff format for merges
"git-diff-tree", "git-diff-files" and "git-diff --raw" can take -c or --cc option to generate diff output also for merge commits. The output differs from the format described above in the following way:
-
there is a colon for each parent
-
there are more "src" modes and "src" sha1
-
status is concatenated status characters for each parent
-
no optional "score" number
-
single path, only for "dst"
Example:
::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM describe.c
Note that combined diff lists only files which were modified from all parents.
Generating patches with -p
When "git-diff-index", "git-diff-tree", or "git-diff-files" are run with a -p option, "git diff" without the --raw option, or "git log" with the "-p" option, they do not produce the output described above; instead they produce a patch file. You can customize the creation of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.
What the -p option produces is slightly different from the traditional diff format:
-
It is preceded with a "git diff" header that looks like this:
diff --git a/file1 b/file2
The
a/
andb/
filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion,/dev/null
is not used in place of thea/
orb/
filenames.When rename/copy is involved,
file1
andfile2
show the name of the source file of the rename/copy and the name of the file that rename/copy produces, respectively. -
It is followed by one or more extended header lines:
old mode <mode> new mode <mode> deleted file mode <mode> new file mode <mode> copy from <path> copy to <path> rename from <path> rename to <path> similarity index <number> dissimilarity index <number> index <hash>..<hash> <mode>
File modes are printed as 6-digit octal numbers including the file type and file permission bits.
Path names in extended headers do not include the
a/
andb/
prefixes.The similarity index is the percentage of unchanged lines, and the dissimilarity index is the percentage of changed lines. It is a rounded down integer, followed by a percent sign. The similarity index value of 100% is thus reserved for two equal files, while 100% dissimilarity means that no line from the old file made it into the new one.
The index line includes the SHA-1 checksum before and after the change. The <mode> is included if the file mode does not change; otherwise, separate lines indicate the old and the new mode.
-
TAB, LF, double quote and backslash characters in pathnames are represented as
\t
,\n
,\"
and\\
, respectively. If there is need for such substitution then the whole pathname is put in double quotes. -
All the
file1
files in the output refer to files before the commit, and all thefile2
files refer to files after the commit. It is incorrect to apply each change to each file sequentially. For example, this patch will swap a and b:diff --git a/a b/b rename from a rename to b diff --git a/b b/a rename from b rename to a
combined diff format
Any diff-generating command can take the -c
or --cc
option to produce a combined diff when showing a merge. This is the default format when showing merges with git-diff[1] or git-show[1]. Note also that you can give the -m
option to any of these commands to force generation of diffs with individual parents of a merge.
A combined diff format looks like this:
diff --combined describe.c index fabadb8,cc95eb0..4866510 --- a/describe.c +++ b/describe.c @@@ -98,20 -98,12 +98,20 @@@ return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1; } - static void describe(char *arg) -static void describe(struct commit *cmit, int last_one) ++static void describe(char *arg, int last_one) { + unsigned char sha1[20]; + struct commit *cmit; struct commit_list *list; static int initialized = 0; struct commit_name *n; + if (get_sha1(arg, sha1) < 0) + usage(describe_usage); + cmit = lookup_commit_reference(sha1); + if (!cmit) + usage(describe_usage); + if (!initialized) { initialized = 1; for_each_ref(get_name);
-
It is preceded with a "git diff" header, that looks like this (when -c option is used):
diff --combined file
or like this (when --cc option is used):
diff --cc file
-
It is followed by one or more extended header lines (this example shows a merge with two parents):
index <hash>,<hash>..<hash> mode <mode>,<mode>..<mode> new file mode <mode> deleted file mode <mode>,<mode>
The
mode <mode>,<mode>..<mode>
line appears only if at least one of the <mode> is different from the rest. Extended headers with information about detected contents movement (renames and copying detection) are designed to work with diff of two <tree-ish> and are not used by combined diff format. -
It is followed by two-line from-file/to-file header
--- a/file +++ b/file
Similar to two-line header for traditional unified diff format,
/dev/null
is used to signal created or deleted files. -
Chunk header format is modified to prevent people from accidentally feeding it to
patch -p1
. Combined diff format was created for review of merge commit changes, and was not meant for apply. The change is similar to the change in the extended index header:@@@ <from-file-range> <from-file-range> <to-file-range> @@@
There are (number of parents + 1)
@
characters in the chunk header for combined diff format.
Unlike the traditional unified diff format, which shows two files A and B with a single column that has -
(minus — appears in A but removed in B), +
(plus — missing in A but added to B), or " "
(space — unchanged) prefix, this format compares two or more files file1, file2,… with one file X, and shows how X differs from each of fileN. One column for each of fileN is prepended to the output line to note how X’s line is different from it.
A -
character in the column N means that the line appears in fileN but it does not appear in the result. A +
character in the column N means that the line appears in the result, and fileN does not have that line (in other words, the line was added, from the point of view of that parent).
In the above example output, the function signature was changed from both files (hence two -
removals from both file1 and file2, plus ++
to mean one line that was added does not appear in either file1 or file2). Also eight other lines are the same from file1 but do not appear in file2 (hence prefixed with +
).
When shown by git diff-tree -c
, it compares the parents of a merge commit with the merge result (i.e. file1..fileN are the parents). When shown by git diff-files -c
, it compares the two unresolved merge parents with the working tree file (i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka "their version").
other diff formats
The --summary
option describes newly added, deleted, renamed and copied files. The --stat
option adds diffstat(1) graph to the output. These options can be combined with other options, such as -p
, and are meant for human consumption.
When showing a change that involves a rename or a copy, --stat
output formats the pathnames compactly by combining common prefix and suffix of the pathnames. For example, a change that moves arch/i386/Makefile
to arch/x86/Makefile
while modifying 4 lines will be shown like this:
arch/{i386 => x86}/Makefile | 4 +--
The --numstat
option gives the diffstat(1) information but is designed for easier machine consumption. An entry in --numstat
output looks like this:
1 2 README 3 1 arch/{i386 => x86}/Makefile
That is, from left to right:
-
the number of added lines;
-
a tab;
-
the number of deleted lines;
-
a tab;
-
pathname (possibly with rename/copy information);
-
a newline.
When -z
output option is in effect, the output is formatted this way:
1 2 README NUL 3 1 NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
That is:
-
the number of added lines;
-
a tab;
-
the number of deleted lines;
-
a tab;
-
a NUL (only exists if renamed/copied);
-
pathname in preimage;
-
a NUL (only exists if renamed/copied);
-
pathname in postimage (only exists if renamed/copied);
-
a NUL.
The extra NUL
before the preimage path in renamed case is to allow scripts that read the output to tell if the current record being read is a single-path record or a rename/copy record without reading ahead. After reading added and deleted lines, reading up to NUL
would yield the pathname, but if that is NUL
, the record will show two paths.
EXAMPLES
-
Various ways to check your working tree
-
$ git diff (1) $ git diff --cached (2) $ git diff HEAD (3)
-
Changes in the working tree not yet staged for the next commit.
-
Changes between the index and your last commit; what you would be committing if you run "git commit" without "-a" option.
-
Changes in the working tree since your last commit; what you would be committing if you run "git commit -a"
Comparing with arbitrary commits
-
-
$ git diff test (1) $ git diff HEAD -- ./test (2) $ git diff HEAD^ HEAD (3)
-
Instead of using the tip of the current branch, compare with the tip of "test" branch.
-
Instead of comparing with the tip of "test" branch, compare with the tip of the current branch, but limit the comparison to the file "test".
-
Compare the version before the last commit and the last commit.
Comparing branches
-
-
$ git diff topic master (1) $ git diff topic..master (2) $ git diff topic...master (3)
-
Changes between the tips of the topic and the master branches.
-
Same as above.
-
Changes that occurred on the master branch since when the topic branch was started off it.
Limiting the diff output
-
-
$ git diff --diff-filter=MRC (1) $ git diff --name-status (2) $ git diff arch/i386 include/asm-i386 (3)
-
Show only modification, rename, and copy, but not addition or deletion.
-
Show only names and the nature of change, but not actual diff output.
-
Limit diff output to named subtrees.
Munging the diff output
-
-
$ git diff --find-copies-harder -B -C (1) $ git diff -R (2)
-
Spend extra cycles to find renames, copies and complete rewrites (very expensive).
-
Output diff in reverse.
-
SEE ALSO
GIT
Part of the git[1] suite
NAME
git-commit - Record changes to the repository
SYNOPSIS
git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
[--dry-run] [(-c | -C | --fixup | --squash) <commit>]
[-F <file> | -m <msg>] [--reset-author] [--allow-empty]
[--allow-empty-message] [--no-verify] [-e] [--author=<author>]
[--date=<date>] [--cleanup=<mode>] [--[no-]status]
[-i | -o] [-S[<keyid>]] [--] [<file>…]
DESCRIPTION
Stores the current contents of the index in a new commit along with a log message from the user describing the changes.
The content to be added can be specified in several ways:
-
by using git add to incrementally "add" changes to the index before using the commit command (Note: even modified files must be "added");
-
by using git rm to remove files from the working tree and the index, again before using thecommit command;
-
by listing files as arguments to the commit command, in which case the commit will ignore changes staged in the index, and instead record the current content of the listed files (which must already be known to Git);
-
by using the -a switch with the commit command to automatically "add" changes from all known files (i.e. all files that are already listed in the index) and to automatically "rm" files in the index that have been removed from the working tree, and then perform the actual commit;
-
by using the --interactive or --patch switches with the commit command to decide one by one which files or hunks should be part of the commit, before finalizing the operation. See the “Interactive Mode” section of git-add[1] to learn how to operate these modes.
The --dry-run
option can be used to obtain a summary of what is included by any of the above for the next commit by giving the same set of parameters (options and paths).
If you make a commit and then find a mistake immediately after that, you can recover from it withgit reset.
OPTIONS
-
-a
--all
-
Tell the command to automatically stage files that have been modified and deleted, but new files you have not told Git about are not affected.
-p
--patch
-
Use the interactive patch selection interface to chose which changes to commit. See git-add[1] for details.
-C <commit>
--reuse-message=<commit>
-
Take an existing commit object, and reuse the log message and the authorship information (including the timestamp) when creating the commit.
-c <commit>
--reedit-message=<commit>
-
Like -C, but with -c the editor is invoked, so that the user can further edit the commit message.
--fixup=<commit>
-
Construct a commit message for use with
rebase --autosquash
. The commit message will be the subject line from the specified commit with a prefix of "fixup! ". See git-rebase[1] for details.
--squash=<commit>
-
Construct a commit message for use with
rebase --autosquash
. The commit message subject line is taken from the specified commit with a prefix of "squash! ". Can be used with additional commit message options (-m
/-c
/-C
/-F
). See git-rebase[1] for details.
--reset-author
-
When used with -C/-c/--amend options, or when committing after a a conflicting cherry-pick, declare that the authorship of the resulting commit now belongs to the committer. This also renews the author timestamp.
--short
-
When doing a dry-run, give the output in the short-format. See git-status[1] for details. Implies
--dry-run
.
--branch
-
Show the branch and tracking info even in short-format.
--porcelain
-
When doing a dry-run, give the output in a porcelain-ready format. See git-status[1] for details. Implies
--dry-run
.
--long
-
When doing a dry-run, give the output in a the long-format. Implies
--dry-run
.
-z
--null
-
When showing
short
orporcelain
status output, terminate entries in the status output with NUL, instead of LF. If no format is given, implies the--porcelain
output format.
-F <file>
--file=<file>
-
Take the commit message from the given file. Use - to read the message from the standard input.
--author=<author>
-
Override the commit author. Specify an explicit author using the standard
A U Thor <author@example.com>
format. Otherwise <author> is assumed to be a pattern and is used to search for an existing commit by that author (i.e. rev-list --all -i --author=<author>); the commit author is then copied from the first such commit found.
--date=<date>
-
Override the author date used in the commit.
-m <msg>
--message=<msg>
-
Use the given <msg> as the commit message. If multiple
-m
options are given, their values are concatenated as separate paragraphs.
-t <file>
--template=<file>
-
When editing the commit message, start the editor with the contents in the given file. The
commit.template
configuration variable is often used to give this option implicitly to the command. This mechanism can be used by projects that want to guide participants with some hints on what to write in the message in what order. If the user exits the editor without editing the message, the commit is aborted. This has no effect when a message is given by other means, e.g. with the-m
or-F
options.
-s
--signoff
-
Add Signed-off-by line by the committer at the end of the commit log message.
-n
--no-verify
-
This option bypasses the pre-commit and commit-msg hooks. See also githooks[5].
--allow-empty
-
Usually recording a commit that has the exact same tree as its sole parent commit is a mistake, and the command prevents you from making such a commit. This option bypasses the safety, and is primarily for use by foreign SCM interface scripts.
--allow-empty-message
-
Like --allow-empty this command is primarily for use by foreign SCM interface scripts. It allows you to create a commit with an empty commit message without using plumbing commands likegit-commit-tree[1].
--cleanup=<mode>
-
This option determines how the supplied commit message should be cleaned up before committing. The <mode> can be
strip
,whitespace
,verbatim
,scissors
ordefault
.-
strip
-
Strip leading and trailing empty lines, trailing whitespace, commentary and collapse consecutive empty lines.
whitespace
-
Same as
strip
except #commentary is not removed.
verbatim
-
Do not change the message at all.
scissors
-
Same as
whitespace
, except that everything from (and including) the line "# ------------------------ >8 ------------------------
" is truncated if the message is to be edited. "#
" can be customized with core.commentChar.
default
-
Same as
strip
if the message is to be edited. Otherwisewhitespace
.
The default can be changed by the commit.cleanup configuration variable (see git-config[1]).
-e
--edit
-
-
The message taken from file with
-F
, command line with-m
, and from commit object with-C
are usually used as the commit log message unmodified. This option lets you further edit the message taken from these sources.
--no-edit
-
Use the selected commit message without launching an editor. For example,
git commit --amend --no-edit
amends a commit without changing its commit message.
--amend
-
Replace the tip of the current branch by creating a new commit. The recorded tree is prepared as usual (including the effect of the
-i
and-o
options and explicit pathspec), and the message from the original commit is used as the starting point, instead of an empty message, when no other message is specified from the command line via options such as-m
,-F
,-c
, etc. The new commit has the same parents and author as the current one (the--reset-author
option can countermand this).It is a rough equivalent for:
$ git reset --soft HEAD^ $ ... do something else to come up with the right tree ... $ git commit -c ORIG_HEAD
but can be used to amend a merge commit.
You should understand the implications of rewriting history if you amend a commit that has already been published. (See the "RECOVERING FROM UPSTREAM REBASE" section in git-rebase[1].)
--no-post-rewrite
-
Bypass the post-rewrite hook.
-i
--include
-
Before making a commit out of staged contents so far, stage the contents of paths given on the command line as well. This is usually not what you want unless you are concluding a conflicted merge.
-o
--only
-
Make a commit by taking the updated working tree contents of the paths specified on the command line, disregarding any contents that have been staged for other paths. This is the default mode of operation of git commit if any paths are given on the command line, in which case this option can be omitted. If this option is specified together with --amend, then no paths need to be specified, which can be used to amend the last commit without committing changes that have already been staged.
-u[<mode>]
--untracked-files[=<mode>]
-
Show untracked files.
The mode parameter is optional (defaults to all), and is used to specify the handling of untracked files; when -u is not used, the default is normal, i.e. show untracked files and directories.
The possible options are:
-
no - Show no untracked files
-
normal - Shows untracked files and directories
-
all - Also shows individual files in untracked directories.
The default can be changed using the status.showUntrackedFiles configuration variable documented in git-config[1].
-v
--verbose
-
-
Show unified diff between the HEAD commit and what would be committed at the bottom of the commit message template to help the user describe the commit by reminding what changes the commit has. Note that this diff output doesn’t have its lines prefixed with #. This diff will not be a part of the commit message.
If specified twice, show in addition the unified diff between what would be committed and the worktree files, i.e. the unstaged changes to tracked files.
-q
--quiet
-
Suppress commit summary message.
--dry-run
-
Do not create a commit, but show a list of paths that are to be committed, paths with local changes that will be left uncommitted and paths that are untracked.
--status
-
Include the output of git-status[1] in the commit message template when using an editor to prepare the commit message. Defaults to on, but can be used to override configuration variable commit.status.
--no-status
-
Do not include the output of git-status[1] in the commit message template when using an editor to prepare the default commit message.
-S[<keyid>]
--gpg-sign[=<keyid>]
-
GPG-sign commits. The
keyid
argument is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space.
--no-gpg-sign
-
Countermand
commit.gpgSign
configuration variable that is set to force each and every commit to be signed.
--
-
Do not interpret any more arguments as options.
<file>…
-
When files are given on the command line, the command commits the contents of the named files, without recording the changes already staged. The contents of these files are also staged for the next commit on top of what have been staged before.
DATE FORMATS
The GIT_AUTHOR_DATE, GIT_COMMITTER_DATE environment variables and the --date
option support the following date formats:
-
Git internal format
-
It is
<unix timestamp> <time zone offset>
, where<unix timestamp>
is the number of seconds since the UNIX epoch.<time zone offset>
is a positive or negative offset from UTC. For example CET (which is 2 hours ahead UTC) is+0200
.
RFC 2822
-
The standard email format as described by RFC 2822, for example
Thu, 07 Apr 2005 22:13:13 +0200
.
ISO 8601
-
Time and date specified by the ISO 8601 standard, for example
2005-04-07T22:13:13
. The parser accepts a space instead of theT
character as well.NoteIn addition, the date part is accepted in the following formats: YYYY.MM.DD
,MM/DD/YYYY
andDD.MM.YYYY
.
EXAMPLES
When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area called the "index" with git add. A file can be reverted back, only in the index but not in the working tree, to that of the last commit with git reset HEAD -- <file>
, which effectively reverts git add and prevents the changes to this file from participating in the next commit. After building the state to be committed incrementally with these commands, git commit
(without any pathname parameter) is used to record what has been staged so far. This is the most basic form of the command. An example:
$ edit hello.c $ git rm goodbye.c $ git add hello.c $ git commit
Instead of staging files after each individual change, you can tell git commit
to notice the changes to the files whose contents are tracked in your working tree and do corresponding git add
and git rm
for you. That is, this example does the same as the earlier example if there is no other change in your working tree:
$ edit hello.c $ rm goodbye.c $ git commit -a
The command git commit -a
first looks at your working tree, notices that you have modified hello.c and removed goodbye.c, and performs necessary git add
and git rm
for you.
After staging changes to many files, you can alter the order the changes are recorded in, by giving pathnames to git commit
. When pathnames are given, the command makes a commit that only records the changes made to the named paths:
$ edit hello.c hello.h $ git add hello.c hello.h $ edit Makefile $ git commit Makefile
This makes a commit that records the modification to Makefile
. The changes staged forhello.c
and hello.h
are not included in the resulting commit. However, their changes are not lost — they are still staged and merely held back. After the above sequence, if you do:
$ git commit
this second commit would record the changes to hello.c
and hello.h
as expected.
After a merge (initiated by git merge or git pull) stops because of conflicts, cleanly merged paths are already staged to be committed for you, and paths that conflicted are left in unmerged state. You would have to first check which paths are conflicting with git status and after fixing them manually in your working tree, you would stage the result as usual with git add:
$ git status | grep unmerged unmerged: hello.c $ edit hello.c $ git add hello.c
After resolving conflicts and staging the result, git ls-files -u
would stop mentioning the conflicted path. When you are done, run git commit
to finally record the merge:
$ git commit
As with the case to record your own changes, you can use -a
option to save typing. One difference is that during a merge resolution, you cannot use git commit
with pathnames to alter the order the changes are committed, because the merge should be recorded as a single commit. In fact, the command refuses to run when given pathnames (but see -i
option).
DISCUSSION
Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, git-format-patch[1] turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.
Git is to some extent character encoding agnostic.
-
The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level.
-
Path names are encoded in UTF-8 normalization form C. This applies to tree objects, the index file, ref names, as well as path names in command line arguments, environment variables and config files (
.git/config
(see git-config[1]), gitignore[5], gitattributes[5] and gitmodules[5]).Note that Git at the core level treats path names simply as sequences of non-NUL bytes, there are no path name encoding conversions (except on Mac and Windows). Therefore, using non-ASCII path names will mostly work even on platforms and file systems that use legacy extended ASCII encodings. However, repositories created on such systems will not work properly on UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. Additionally, many Git-based tools simply assume path names to be UTF-8 and will fail to display other encodings correctly.
-
Commit log messages are typically encoded in UTF-8, but other extended ASCII encodings are also supported. This includes ISO-8859-x, CP125x and many others, but not UTF-16/32, EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, EUC-x, CP9xx etc.).
Although we encourage that the commit log messages are encoded in UTF-8, both the core and Git Porcelain are designed not to force UTF-8 on projects. If all participants of a particular project find it more convenient to use legacy encodings, Git does not forbid it. However, there are a few things to keep in mind.
-
git commit and git commit-tree issues a warning if the commit log message given to it does not look like a valid UTF-8 string, unless you explicitly say your project uses a legacy encoding. The way to say this is to have i18n.commitencoding in
.git/config
file, like this:[i18n] commitencoding = ISO-8859-1
Commit objects created with the above setting record the value of
i18n.commitencoding
in itsencoding
header. This is to help other people who look at them later. Lack of this header implies that the commit log message is encoded in UTF-8. -
git log, git show, git blame and friends look at the
encoding
header of a commit object, and try to re-code the log message into UTF-8 unless otherwise specified. You can specify the desired output encoding withi18n.logoutputencoding
in.git/config
file, like this:[i18n] logoutputencoding = ISO-8859-1
If you do not have this configuration variable, the value of
i18n.commitencoding
is used instead.
Note that we deliberately chose not to re-code the commit log message when a commit is made to force UTF-8 at the commit object level, because re-coding to UTF-8 is not necessarily a reversible operation.
ENVIRONMENT AND CONFIGURATION VARIABLES
The editor used to edit the commit log message will be chosen from the GIT_EDITOR environment variable, the core.editor configuration variable, the VISUAL environment variable, or the EDITOR environment variable (in that order). See git-var[1] for details.
HOOKS
This command can run commit-msg
, prepare-commit-msg
, pre-commit
, and post-commit
hooks. See githooks[5] for more information.
FILES
-
This file contains the commit message of a commit in progress. If
git commit
exits due to an error before creating a commit, any commit message that has been provided by the user (e.g., in an editor session) will be available in this file, but will be overwritten by the next invocation ofgit commit
.
$GIT_DIR/COMMIT_EDITMSG
SEE ALSO
GIT
Part of the git[1] suite
NAME
git-reset - Reset current HEAD to the specified state
SYNOPSIS
git reset [-q] [<tree-ish>] [--] <paths>… git reset (--patch | -p) [<tree-ish>] [--] [<paths>…] git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
DESCRIPTION
In the first and second form, copy entries from <tree-ish> to the index. In the third form, set the current branch head (HEAD) to <commit>, optionally modifying index and working tree to match. The <tree-ish>/<commit> defaults to HEAD in all forms.
-
git reset [-q] [<tree-ish>] [--] <paths>…
-
This form resets the index entries for all <paths> to their state at <tree-ish>. (It does not affect the working tree or the current branch.)
This means that
git reset <paths>
is the opposite ofgit add <paths>
.After running
git reset <paths>
to update the index entry, you can use git-checkout[1] to check the contents out of the index to the working tree. Alternatively, using git-checkout[1] and specifying a commit, you can copy the contents of a path out of a commit to the index and to the working tree in one go.
git reset (--patch | -p) [<tree-ish>] [--] [<paths>…]
-
Interactively select hunks in the difference between the index and <tree-ish> (defaults to HEAD). The chosen hunks are applied in reverse to the index.
This means that
git reset -p
is the opposite ofgit add -p
, i.e. you can use it to selectively reset hunks. See the “Interactive Mode” section of git-add[1] to learn how to operate the--patch
mode.
git reset [<mode>] [<commit>]
-
This form resets the current branch head to <commit> and possibly updates the index (resetting it to the tree of <commit>) and the working tree depending on <mode>. If <mode> is omitted, defaults to "--mixed". The <mode> must be one of the following:
-
--soft
-
Does not touch the index file or the working tree at all (but resets the head to <commit>, just like all modes do). This leaves all your changed files "Changes to be committed", as git status would put it.
--mixed
-
Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action.
If
-N
is specified, removed paths are marked as intent-to-add (see git-add[1]).
--hard
-
Resets the index and working tree. Any changes to tracked files in the working tree since <commit> are discarded.
--merge
-
Resets the index and updates the files in the working tree that are different between <commit> and HEAD, but keeps those which are different between the index and working tree (i.e. which have changes which have not been added). If a file that is different between <commit> and the index has unstaged changes, reset is aborted.
In other words, --merge does something like a git read-tree -u -m <commit>, but carries forward unmerged index entries.
--keep
-
Resets index entries and updates files in the working tree that are different between <commit> and HEAD. If a file that is different between <commit> and HEAD has local changes, reset is aborted.
-
If you want to undo a commit other than the latest on a branch, git-revert[1] is your friend.
OPTIONS
-
-q
--quiet
-
Be quiet, only report errors.
EXAMPLES
-
Undo add
-
$ edit (1) $ git add frotz.c filfre.c $ mailx (2) $ git reset (3) $ git pull git://info.example.com/ nitfol (4)
-
You are happily working on something, and find the changes in these files are in good order. You do not want to see them when you run "git diff", because you plan to work on other files and changes with these files are distracting.
-
Somebody asks you to pull, and the changes sounds worthy of merging.
-
However, you already dirtied the index (i.e. your index does not match the HEAD commit). But you know the pull you are going to make does not affect frotz.c or filfre.c, so you revert the index changes for these two files. Your changes in working tree remain there.
-
Then you can pull and merge, leaving frotz.c and filfre.c changes still in the working tree.
Undo a commit and redo
-
-
$ git commit ... $ git reset --soft HEAD^ (1) $ edit (2) $ git commit -a -c ORIG_HEAD (3)
-
This is most often done when you remembered what you just committed is incomplete, or you misspelled your commit message, or both. Leaves working tree as it was before "reset".
-
Make corrections to working tree files.
-
"reset" copies the old head to .git/ORIG_HEAD; redo the commit by starting with its log message. If you do not need to edit the message further, you can give -C option instead.
See also the --amend option to git-commit[1].
Undo a commit, making it a topic branch
-
-
$ git branch topic/wip (1) $ git reset --hard HEAD~3 (2) $ git checkout topic/wip (3)
-
You have made some commits, but realize they were premature to be in the "master" branch. You want to continue polishing them in a topic branch, so create "topic/wip" branch off of the current HEAD.
-
Rewind the master branch to get rid of those three commits.
-
Switch to "topic/wip" branch and keep working.
Undo commits permanently
-
-
$ git commit ... $ git reset --hard HEAD~3 (1)
-
The last three commits (HEAD, HEAD^, and HEAD~2) were bad and you do not want to ever see them again. Do not do this if you have already given these commits to somebody else. (See the "RECOVERING FROM UPSTREAM REBASE" section in git-rebase[1] for the implications of doing so.)
Undo a merge or pull
-
-
$ git pull (1) Auto-merging nitfol CONFLICT (content): Merge conflict in nitfol Automatic merge failed; fix conflicts and then commit the result. $ git reset --hard (2) $ git pull . topic/branch (3) Updating from 41223... to 13134... Fast-forward $ git reset --hard ORIG_HEAD (4)
-
Try to update from the upstream resulted in a lot of conflicts; you were not ready to spend a lot of time merging right now, so you decide to do that later.
-
"pull" has not made merge commit, so "git reset --hard" which is a synonym for "git reset --hard HEAD" clears the mess from the index file and the working tree.
-
Merge a topic branch into the current branch, which resulted in a fast-forward.
-
But you decided that the topic branch is not ready for public consumption yet. "pull" or "merge" always leaves the original tip of the current branch in ORIG_HEAD, so resetting hard to it brings your index file and the working tree back to that state, and resets the tip of the branch to that commit.
Undo a merge or pull inside a dirty working tree
-
-
$ git pull (1) Auto-merging nitfol Merge made by recursive. nitfol | 20 +++++---- ... $ git reset --merge ORIG_HEAD (2)
-
Even if you may have local modifications in your working tree, you can safely say "git pull" when you know that the change in the other branch does not overlap with them.
-
After inspecting the result of the merge, you may find that the change in the other branch is unsatisfactory. Running "git reset --hard ORIG_HEAD" will let you go back to where you were, but it will discard your local changes, which you do not want. "git reset --merge" keeps your local changes.
Interrupted workflow
-
-
Suppose you are interrupted by an urgent fix request while you are in the middle of a large change. The files in your working tree are not in any shape to be committed yet, but you need to get to the other branch for a quick bugfix.
$ git checkout feature ;# you were working in "feature" branch and $ work work work ;# got interrupted $ git commit -a -m "snapshot WIP" (1) $ git checkout master $ fix fix fix $ git commit ;# commit with real log $ git checkout feature $ git reset --soft HEAD^ ;# go back to WIP state (2) $ git reset (3)
-
This commit will get blown away so a throw-away log message is OK.
-
This removes the WIP commit from the commit history, and sets your working tree to the state just before you made that snapshot.
-
At this point the index file still has all the WIP changes you committed as snapshot WIP. This updates the index to show your WIP files as uncommitted.
See also git-stash[1].
Reset a single file in the index
-
-
Suppose you have added a file to your index, but later decide you do not want to add it to your commit. You can remove the file from the index while keeping your changes with git reset.
$ git reset -- frotz.c (1) $ git commit -m "Commit files in index" (2) $ git add frotz.c (3)
-
This removes the file from the index while keeping it in the working directory.
-
This commits all other changes in the index.
-
Adds the file to the index again.
Keep changes in working tree while discarding some previous commits
-
-
Suppose you are working on something and you commit it, and then you continue working a bit more, but now you think that what you have in your working tree should be in another branch that has nothing to do with what you committed previously. You can start a new branch and reset it while keeping the changes in your working tree.
$ git tag start $ git checkout -b branch1 $ edit $ git commit ... (1) $ edit $ git checkout -b branch2 (2) $ git reset --keep start (3)
-
This commits your first edits in branch1.
-
In the ideal world, you could have realized that the earlier commit did not belong to the new topic when you created and switched to branch2 (i.e. "git checkout -b branch2 start"), but nobody is perfect.
-
But you can use "reset --keep" to remove the unwanted commit after you switched to "branch2".
-
DISCUSSION
The tables below show what happens when running:
git reset --option target
to reset the HEAD to another commit (target
) with the different reset options depending on the state of the files.
In these tables, A, B, C and D are some different states of a file. For example, the first line of the first table means that if a file is in state A in the working tree, in state B in the index, in state C in HEAD and in state D in the target, then "git reset --soft target" will leave the file in the working tree in state A and in the index in state B. It resets (i.e. moves) the HEAD (i.e. the tip of the current branch, if you are on one) to "target" (which has the file in state D).
working index HEAD target working index HEAD ---------------------------------------------------- A B C D --soft A B D --mixed A D D --hard D D D --merge (disallowed) --keep (disallowed)
working index HEAD target working index HEAD ---------------------------------------------------- A B C C --soft A B C --mixed A C C --hard C C C --merge (disallowed) --keep A C C
working index HEAD target working index HEAD ---------------------------------------------------- B B C D --soft B B D --mixed B D D --hard D D D --merge D D D --keep (disallowed)
working index HEAD target working index HEAD ---------------------------------------------------- B B C C --soft B B C --mixed B C C --hard C C C --merge C C C --keep B C C
working index HEAD target working index HEAD ---------------------------------------------------- B C C D --soft B C D --mixed B D D --hard D D D --merge (disallowed) --keep (disallowed)
working index HEAD target working index HEAD ---------------------------------------------------- B C C C --soft B C C --mixed B C C --hard C C C --merge B C C --keep B C C
"reset --merge" is meant to be used when resetting out of a conflicted merge. Any mergy operation guarantees that the working tree file that is involved in the merge does not have local change wrt the index before it starts, and that it writes the result out to the working tree. So if we see some difference between the index and the target and also between the index and the working tree, then it means that we are not resetting out from a state that a mergy operation left after failing with a conflict. That is why we disallow --merge option in this case.
"reset --keep" is meant to be used when removing some of the last commits in the current branch while keeping changes in the working tree. If there could be conflicts between the changes in the commit we want to remove and the changes in the working tree we want to keep, the reset is disallowed. That’s why it is disallowed if there are both changes between the working tree and HEAD, and between HEAD and the target. To be safe, it is also disallowed when there are unmerged entries.
The following tables show what happens when there are unmerged entries:
working index HEAD target working index HEAD ---------------------------------------------------- X U A B --soft (disallowed) --mixed X B B --hard B B B --merge B B B --keep (disallowed)
working index HEAD target working index HEAD ---------------------------------------------------- X U A A --soft (disallowed) --mixed X A A --hard A A A --merge A A A --keep (disallowed)
X means any state and U means an unmerged index.
GIT
Part of the git[1] suite
NAME
git-rm - Remove files from the working tree and from the index
SYNOPSIS
git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>…
DESCRIPTION
Remove files from the index, or from the working tree and the index. git rm
will not remove a file from just your working directory. (There is no option to remove a file only from the working tree and yet keep it in the index; use /bin/rm
if you want to do that.) The files being removed have to be identical to the tip of the branch, and no updates to their contents can be staged in the index, though that default behavior can be overridden with the -f
option. When --cached
is given, the staged content has to match either the tip of the branch or the file on disk, allowing the file to be removed from just the index.
OPTIONS
-
<file>…
-
Files to remove. Fileglobs (e.g.
*.c
) can be given to remove all matching files. If you want Git to expand file glob characters, you may need to shell-escape them. A leading directory name (e.g.dir
to removedir/file1
anddir/file2
) can be given to remove all files in the directory, and recursively all sub-directories, but this requires the-r
option to be explicitly given.
-f
--force
-
Override the up-to-date check.
-n
--dry-run
-
Don’t actually remove any file(s). Instead, just show if they exist in the index and would otherwise be removed by the command.
-r
-
Allow recursive removal when a leading directory name is given.
--
-
This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options).
--cached
-
Use this option to unstage and remove paths only from the index. Working tree files, whether modified or not, will be left alone.
--ignore-unmatch
-
Exit with a zero status even if no files matched.
-q
--quiet
-
git rm
normally outputs one line (in the form of anrm
command) for each file removed. This option suppresses that output.
DISCUSSION
The <file> list given to the command can be exact pathnames, file glob patterns, or leading directory names. The command removes only the paths that are known to Git. Giving the name of a file that you have not told Git about does not remove that file.
File globbing matches across directory boundaries. Thus, given two directories d
and d2
, there is a difference between using git rm 'd*'
and git rm 'd/*'
, as the former will also remove all of directory d2
.
REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM
There is no option for git rm
to remove from the index only the paths that have disappeared from the filesystem. However, depending on the use case, there are several ways that can be done.
Using “git commit -a”
If you intend that your next commit should record all modifications of tracked files in the working tree and record all removals of files that have been removed from the working tree with rm
(as opposed to git rm
), use git commit -a
, as it will automatically notice and record all removals. You can also have a similar effect without committing by using git add -u
.
Using “git add -A”
When accepting a new code drop for a vendor branch, you probably want to record both the removal of paths and additions of new paths as well as modifications of existing paths.
Typically you would first remove all tracked files from the working tree using this command:
git ls-files -z | xargs -0 rm -f
and then untar the new code in the working tree. Alternately you could rsync the changes into the working tree.
After that, the easiest way to record all removals, additions, and modifications in the working tree is:
git add -A
See git-add[1].
Other ways
If all you really want to do is to remove from the index the files that are no longer present in the working tree (perhaps because your working tree is dirty so that you cannot use git commit -a
), use the following command:
git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
SUBMODULES
Only submodules using a gitfile (which means they were cloned with a Git version 1.7.8 or newer) will be removed from the work tree, as their repository lives inside the .git directory of the superproject. If a submodule (or one of those nested inside it) still uses a .git directory, git rm
will fail - no matter if forced or not - to protect the submodule’s history. If it exists the submodule.<name> section in the gitmodules[5] file will also be removed and that file will be staged (unless --cached or -n are used).
A submodule is considered up-to-date when the HEAD is the same as recorded in the index, no tracked files are modified and no untracked files that aren’t ignored are present in the submodules work tree. Ignored files are deemed expendable and won’t stop a submodule’s work tree from being removed.
If you only want to remove the local checkout of a submodule from your work tree without committing the removal, use git-submodule[1] deinit
instead.
EXAMPLES
-
Removes all
*.txt
files from the index that are under theDocumentation
directory and any of its subdirectories.Note that the asterisk
*
is quoted from the shell in this example; this lets Git, and not the shell, expand the pathnames of files and subdirectories under theDocumentation/
directory. -
Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not remove
subdir/git-foo.sh
.
git rm Documentation/\*.txt
git rm -f git-*.sh
BUGS
Each time a superproject update removes a populated submodule (e.g. when switching between commits before and after the removal) a stale submodule checkout will remain in the old location. Removing the old directory is only safe when it uses a gitfile, as otherwise the history of the submodule will be deleted too. This step will be obsolete when recursive submodule update has been implemented.
SEE ALSO
GIT
Part of the git[1] suite
NAME
git-stash - Stash the changes in a dirty working directory away
SYNOPSIS
git stash list [<options>] git stash show [<stash>] git stash drop [-q|--quiet] [<stash>] git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>] git stash branch <branchname> [<stash>] git stash [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [<message>]] git stash clear git stash create [<message>] git stash store [-m|--message <message>] [-q|--quiet] <commit>
DESCRIPTION
Use git stash
when you want to record the current state of the working directory and the index, but want to go back to a clean working directory. The command saves your local modifications away and reverts the working directory to match the HEAD
commit.
The modifications stashed away by this command can be listed with git stash list
, inspected with git stash show
, and restored (potentially on top of a different commit) with git stash apply
. Calling git stash
without any arguments is equivalent to git stash save
. A stash is by default listed as "WIP on branchname …", but you can give a more descriptive message on the command line when you create one.
The latest stash you created is stored in refs/stash
; older stashes are found in the reflog of this reference and can be named using the usual reflog syntax (e.g. stash@{0}
is the most recently created stash, stash@{1}
is the one before it, stash@{2.hours.ago}
is also possible).
OPTIONS
-
save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]
-
Save your local modifications to a new stash, and run
git reset --hard
to revert them. The <message> part is optional and gives the description along with the stashed state. For quickly making a snapshot, you can omit both "save" and <message>, but giving only <message> does not trigger this action to prevent a misspelled subcommand from making an unwanted stash.If the
--keep-index
option is used, all changes already added to the index are left intact.If the
--include-untracked
option is used, all untracked files are also stashed and then cleaned up withgit clean
, leaving the working directory in a very clean state. If the--all
option is used instead then the ignored files are stashed and cleaned in addition to the untracked files.With
--patch
, you can interactively select hunks from the diff between HEAD and the working tree to be stashed. The stash entry is constructed such that its index state is the same as the index state of your repository, and its worktree contains only the changes you selected interactively. The selected changes are then rolled back from your worktree. See the “Interactive Mode” section ofgit-add[1] to learn how to operate the--patch
mode.The
--patch
option implies--keep-index
. You can use--no-keep-index
to override this.
list [<options>]
-
List the stashes that you currently have. Each stash is listed with its name (e.g.
stash@{0}
is the latest stash,stash@{1}
is the one before, etc.), the name of the branch that was current when the stash was made, and a short description of the commit the stash was based on.stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation stash@{1}: On master: 9cc0589... Add git-stash
The command takes options applicable to the git log command to control what is shown and how. See git-log[1].
show [<stash>]
-
Show the changes recorded in the stash as a diff between the stashed state and its original parent. When no
<stash>
is given, shows the latest one. By default, the command shows the diffstat, but it will accept any format known to git diff (e.g.,git stash show -p stash@{1}
to view the second most recent stash in patch form).
pop [--index] [-q|--quiet] [<stash>]
-
Remove a single stashed state from the stash list and apply it on top of the current working tree state, i.e., do the inverse operation of
git stash save
. The working directory must match the index.Applying the state can fail with conflicts; in this case, it is not removed from the stash list. You need to resolve the conflicts by hand and call
git stash drop
manually afterwards.If the
--index
option is used, then tries to reinstate not only the working tree’s changes, but also the index’s ones. However, this can fail, when you have conflicts (which are stored in the index, where you therefore can no longer apply the changes as they were originally).When no
<stash>
is given,stash@{0}
is assumed, otherwise<stash>
must be a reference of the formstash@{<revision>}
.
apply [--index] [-q|--quiet] [<stash>]
-
Like
pop
, but do not remove the state from the stash list. Unlikepop
,<stash>
may be any commit that looks like a commit created bystash save
orstash create
.
branch <branchname> [<stash>]
-
Creates and checks out a new branch named
<branchname>
starting from the commit at which the<stash>
was originally created, applies the changes recorded in<stash>
to the new working tree and index. If that succeeds, and<stash>
is a reference of the formstash@{<revision>}
, it then drops the<stash>
. When no<stash>
is given, applies the latest one.This is useful if the branch on which you ran
git stash save
has changed enough thatgit stash apply
fails due to conflicts. Since the stash is applied on top of the commit that was HEAD at the timegit stash
was run, it restores the originally stashed state with no conflicts.
clear
-
Remove all the stashed states. Note that those states will then be subject to pruning, and may be impossible to recover (see Examples below for a possible strategy).
drop [-q|--quiet] [<stash>]
-
Remove a single stashed state from the stash list. When no
<stash>
is given, it removes the latest one. i.e.stash@{0}
, otherwise<stash>
must be a valid stash log reference of the formstash@{<revision>}
.
create
-
Create a stash (which is a regular commit object) and return its object name, without storing it anywhere in the ref namespace. This is intended to be useful for scripts. It is probably not the command you want to use; see "save" above.
store
-
Store a given stash created via git stash create (which is a dangling merge commit) in the stash ref, updating the stash reflog. This is intended to be useful for scripts. It is probably not the command you want to use; see "save" above.
DISCUSSION
A stash is represented as a commit whose tree records the state of the working directory, and its first parent is the commit at HEAD
when the stash was created. The tree of the second parent records the state of the index when the stash is made, and it is made a child of the HEAD
commit. The ancestry graph looks like this:
.----W / / -----H----I
where H
is the HEAD
commit, I
is a commit that records the state of the index, and W
is a commit that records the state of the working tree.
EXAMPLES
-
Pulling into a dirty tree
-
When you are in the middle of something, you learn that there are upstream changes that are possibly relevant to what you are doing. When your local changes do not conflict with the changes in the upstream, a simple
git pull
will let you move forward.However, there are cases in which your local changes do conflict with the upstream changes, and
git pull
refuses to overwrite your changes. In such a case, you can stash your changes away, perform a pull, and then unstash, like this:$ git pull ... file foobar not up to date, cannot merge. $ git stash $ git pull $ git stash pop
Interrupted workflow
-
When you are in the middle of something, your boss comes in and demands that you fix something immediately. Traditionally, you would make a commit to a temporary branch to store your changes away, and return to your original branch to make the emergency fix, like this:
# ... hack hack hack ... $ git checkout -b my_wip $ git commit -a -m "WIP" $ git checkout master $ edit emergency fix $ git commit -a -m "Fix in a hurry" $ git checkout my_wip $ git reset --soft HEAD^ # ... continue hacking ...
You can use git stash to simplify the above, like this:
# ... hack hack hack ... $ git stash $ edit emergency fix $ git commit -a -m "Fix in a hurry" $ git stash pop # ... continue hacking ...
Testing partial commits
-
You can use
git stash save --keep-index
when you want to make two or more commits out of the changes in the work tree, and you want to test each change before committing:# ... hack hack hack ... $ git add --patch foo # add just first part to the index $ git stash save --keep-index # save all other changes to the stash $ edit/build/test first part $ git commit -m 'First part' # commit fully tested change $ git stash pop # prepare to work on all other changes # ... repeat above five steps until one commit remains ... $ edit/build/test remaining parts $ git commit foo -m 'Remaining parts'
Recovering stashes that were cleared/dropped erroneously
-
If you mistakenly drop or clear stashes, they cannot be recovered through the normal safety mechanisms. However, you can try the following incantation to get a list of stashes that are still in your repository, but not reachable any more:
git fsck --unreachable | grep commit | cut -d\ -f3 | xargs git log --merges --no-walk --grep=WIP
SEE ALSO
GIT
Part of the git[1] suite
NAME
git-stash - Stash the changes in a dirty working directory away
SYNOPSIS
git stash list [<options>] git stash show [<stash>] git stash drop [-q|--quiet] [<stash>] git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>] git stash branch <branchname> [<stash>] git stash [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [<message>]] git stash clear git stash create [<message>] git stash store [-m|--message <message>] [-q|--quiet] <commit>
DESCRIPTION
Use git stash
when you want to record the current state of the working directory and the index, but want to go back to a clean working directory. The command saves your local modifications away and reverts the working directory to match the HEAD
commit.
The modifications stashed away by this command can be listed with git stash list
, inspected with git stash show
, and restored (potentially on top of a different commit) with git stash apply
. Calling git stash
without any arguments is equivalent to git stash save
. A stash is by default listed as "WIP on branchname …", but you can give a more descriptive message on the command line when you create one.
The latest stash you created is stored in refs/stash
; older stashes are found in the reflog of this reference and can be named using the usual reflog syntax (e.g. stash@{0}
is the most recently created stash, stash@{1}
is the one before it, stash@{2.hours.ago}
is also possible).
OPTIONS
-
save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]
-
Save your local modifications to a new stash, and run
git reset --hard
to revert them. The <message> part is optional and gives the description along with the stashed state. For quickly making a snapshot, you can omit both "save" and <message>, but giving only <message> does not trigger this action to prevent a misspelled subcommand from making an unwanted stash.If the
--keep-index
option is used, all changes already added to the index are left intact.If the
--include-untracked
option is used, all untracked files are also stashed and then cleaned up withgit clean
, leaving the working directory in a very clean state. If the--all
option is used instead then the ignored files are stashed and cleaned in addition to the untracked files.With
--patch
, you can interactively select hunks from the diff between HEAD and the working tree to be stashed. The stash entry is constructed such that its index state is the same as the index state of your repository, and its worktree contains only the changes you selected interactively. The selected changes are then rolled back from your worktree. See the “Interactive Mode” section ofgit-add[1] to learn how to operate the--patch
mode.The
--patch
option implies--keep-index
. You can use--no-keep-index
to override this.
list [<options>]
-
List the stashes that you currently have. Each stash is listed with its name (e.g.
stash@{0}
is the latest stash,stash@{1}
is the one before, etc.), the name of the branch that was current when the stash was made, and a short description of the commit the stash was based on.stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation stash@{1}: On master: 9cc0589... Add git-stash
The command takes options applicable to the git log command to control what is shown and how. See git-log[1].
show [<stash>]
-
Show the changes recorded in the stash as a diff between the stashed state and its original parent. When no
<stash>
is given, shows the latest one. By default, the command shows the diffstat, but it will accept any format known to git diff (e.g.,git stash show -p stash@{1}
to view the second most recent stash in patch form).
pop [--index] [-q|--quiet] [<stash>]
-
Remove a single stashed state from the stash list and apply it on top of the current working tree state, i.e., do the inverse operation of
git stash save
. The working directory must match the index.Applying the state can fail with conflicts; in this case, it is not removed from the stash list. You need to resolve the conflicts by hand and call
git stash drop
manually afterwards.If the
--index
option is used, then tries to reinstate not only the working tree’s changes, but also the index’s ones. However, this can fail, when you have conflicts (which are stored in the index, where you therefore can no longer apply the changes as they were originally).When no
<stash>
is given,stash@{0}
is assumed, otherwise<stash>
must be a reference of the formstash@{<revision>}
.
apply [--index] [-q|--quiet] [<stash>]
-
Like
pop
, but do not remove the state from the stash list. Unlikepop
,<stash>
may be any commit that looks like a commit created bystash save
orstash create
.
branch <branchname> [<stash>]
-
Creates and checks out a new branch named
<branchname>
starting from the commit at which the<stash>
was originally created, applies the changes recorded in<stash>
to the new working tree and index. If that succeeds, and<stash>
is a reference of the formstash@{<revision>}
, it then drops the<stash>
. When no<stash>
is given, applies the latest one.This is useful if the branch on which you ran
git stash save
has changed enough thatgit stash apply
fails due to conflicts. Since the stash is applied on top of the commit that was HEAD at the timegit stash
was run, it restores the originally stashed state with no conflicts.
clear
-
Remove all the stashed states. Note that those states will then be subject to pruning, and may be impossible to recover (see Examples below for a possible strategy).
drop [-q|--quiet] [<stash>]
-
Remove a single stashed state from the stash list. When no
<stash>
is given, it removes the latest one. i.e.stash@{0}
, otherwise<stash>
must be a valid stash log reference of the formstash@{<revision>}
.
create
-
Create a stash (which is a regular commit object) and return its object name, without storing it anywhere in the ref namespace. This is intended to be useful for scripts. It is probably not the command you want to use; see "save" above.
store
-
Store a given stash created via git stash create (which is a dangling merge commit) in the stash ref, updating the stash reflog. This is intended to be useful for scripts. It is probably not the command you want to use; see "save" above.
DISCUSSION
A stash is represented as a commit whose tree records the state of the working directory, and its first parent is the commit at HEAD
when the stash was created. The tree of the second parent records the state of the index when the stash is made, and it is made a child of the HEAD
commit. The ancestry graph looks like this:
.----W / / -----H----I
where H
is the HEAD
commit, I
is a commit that records the state of the index, and W
is a commit that records the state of the working tree.
EXAMPLES
-
Pulling into a dirty tree
-
When you are in the middle of something, you learn that there are upstream changes that are possibly relevant to what you are doing. When your local changes do not conflict with the changes in the upstream, a simple
git pull
will let you move forward.However, there are cases in which your local changes do conflict with the upstream changes, and
git pull
refuses to overwrite your changes. In such a case, you can stash your changes away, perform a pull, and then unstash, like this:$ git pull ... file foobar not up to date, cannot merge. $ git stash $ git pull $ git stash pop
Interrupted workflow
-
When you are in the middle of something, your boss comes in and demands that you fix something immediately. Traditionally, you would make a commit to a temporary branch to store your changes away, and return to your original branch to make the emergency fix, like this:
# ... hack hack hack ... $ git checkout -b my_wip $ git commit -a -m "WIP" $ git checkout master $ edit emergency fix $ git commit -a -m "Fix in a hurry" $ git checkout my_wip $ git reset --soft HEAD^ # ... continue hacking ...
You can use git stash to simplify the above, like this:
# ... hack hack hack ... $ git stash $ edit emergency fix $ git commit -a -m "Fix in a hurry" $ git stash pop # ... continue hacking ...
Testing partial commits
-
You can use
git stash save --keep-index
when you want to make two or more commits out of the changes in the work tree, and you want to test each change before committing:# ... hack hack hack ... $ git add --patch foo # add just first part to the index $ git stash save --keep-index # save all other changes to the stash $ edit/build/test first part $ git commit -m 'First part' # commit fully tested change $ git stash pop # prepare to work on all other changes # ... repeat above five steps until one commit remains ... $ edit/build/test remaining parts $ git commit foo -m 'Remaining parts'
Recovering stashes that were cleared/dropped erroneously
-
If you mistakenly drop or clear stashes, they cannot be recovered through the normal safety mechanisms. However, you can try the following incantation to get a list of stashes that are still in your repository, but not reachable any more:
git fsck --unreachable | grep commit | cut -d\ -f3 | xargs git log --merges --no-walk --grep=WIP
SEE ALSO
GIT
Part of the git[1] suite