Documentation/git-commit.txt

   1 git-commit(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-commit - Record your changes
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>]
  12            [-e] [--author <author>] [--] [[-i | -o ]<file>...]
  13
  14 DESCRIPTION
  15 -----------
  16 Updates the index file for given paths, or all modified files if
  17 '-a' is specified, and makes a commit object.  The command
  18 VISUAL and EDITOR environment variables to edit the commit log
  19 message.
  20
  21 This command can run `commit-msg`, `pre-commit`, and
  22 `post-commit` hooks.  See link:hooks.html[hooks] for more
  23 information.
  24
  25 OPTIONS
  26 -------
  27 -a|--all::
  28         Update all paths in the index file.  This flag notices
  29         files that have been modified and deleted, but new files
  30         you have not told git about are not affected.
  31
  32 -c or -C <commit>::
  33         Take existing commit object, and reuse the log message
  34         and the authorship information (including the timestamp)
  35         when creating the commit.  With '-C', the editor is not
  36         invoked; with '-c' the user can further edit the commit
  37         message.
  38
  39 -F <file>::
  40         Take the commit message from the given file.  Use '-' to
  41         read the message from the standard input.
  42
  43 --author <author>::
  44         Override the author name used in the commit.  Use
  45         `A U Thor <author@example.com>` format.
  46
  47 -m <msg>::
  48         Use the given <msg> as the commit message.
  49
  50 -s|--signoff::
  51         Add Signed-off-by line at the end of the commit message.
  52
  53 -v|--verify::
  54         Look for suspicious lines the commit introduces, and
  55         abort committing if there is one.  The definition of
  56         'suspicious lines' is currently the lines that has
  57         trailing whitespaces, and the lines whose indentation
  58         has a SP character immediately followed by a TAB
  59         character.  This is the default.
  60
  61 -n|--no-verify::
  62         The opposite of `--verify`.
  63
  64 -e|--edit::
  65         The message taken from file with `-F`, command line with
  66         `-m`, and from file with `-C` are usually used as the
  67         commit log message unmodified.  This option lets you
  68         further edit the message taken from these sources.
  69
  70 -i|--include::
  71         Instead of committing only the files specified on the
  72         command line, update them in the index file and then
  73         commit the whole index.  This is the traditional
  74         behaviour.
  75
  76 -o|--only::
  77         Commit only the files specified on the command line.
  78         This format cannot be used during a merge, nor when the
  79         index and the latest commit does not match on the
  80         specified paths to avoid confusion.
  81
  82 --::
  83         Do not interpret any more arguments as options.
  84
  85 <file>...::
  86         Files to be committed.  The meaning of these is
  87         different between `--include` and `--only`.  Without
  88         either, it defaults `--include` semantics.
  89
  90 If you make a commit and then found a mistake immediately after
  91 that, you can recover from it with gitlink:git-reset[1].
  92
  93
  94 WARNING
  95 -------
  96
  97 The 1.2.0 and its maintenance series 1.2.X will keep the
  98 traditional `--include` semantics as the default when neither
  99 `--only` nor `--include` is specified and `paths...` are given.
 100 This *will* change during the development towards 1.3.0 in the
 101 'master' branch of `git.git` repository.  If you are using this
 102 command in your scripts, and you depend on the traditional
 103 `--include` semantics, please update them to explicitly ask for
 104 `--include` semantics.  Also if you are used to making partial
 105 commit using `--include` semantics, please train your fingers to
 106 say `git commit --include paths...` (or `git commit -i paths...`).
 107
 108
 109 Discussion
 110 ----------
 111
 112 `git commit` without _any_ parameter commits the tree structure
 113 recorded by the current index file.  This is a whole-tree commit
 114 even the command is invoked from a subdirectory.
 115
 116 `git commit --include paths...` is equivalent to
 117
 118         git update-index --remove paths...
 119         git commit
 120
 121 That is, update the specified paths to the index and then commit
 122 the whole tree.
 123
 124 `git commit --only paths...` largely bypasses the index file and
 125 commits only the changes made to the specified paths.  It has
 126 however several safety valves to prevent confusion.
 127
 128 . It refuses to run during a merge (i.e. when
 129   `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
 130   that the traditional semantics now needs -i flag.
 131
 132 . It refuses to run if named `paths...` are different in HEAD
 133   and the index (ditto about reminding).  Added paths are OK.
 134   This is because an earlier `git diff` (not `git diff HEAD`)
 135   would have shown the differences since the last `git
 136   update-index paths...` to the user, and an inexperienced user
 137   may mistakenly think that the changes between the index and
 138   the HEAD (i.e. earlier changes made before the last `git
 139   update-index paths...` was done) are not being committed.
 140
 141 . It reads HEAD commit into a temporary index file, updates the
 142   specified `paths...` and makes a commit.  At the same time,
 143   the real index file is also updated with the same `paths...`.
 144
 145 `git commit --all` updates the index file with _all_ changes to
 146 the working tree, and makes a whole-tree commit, regardless of
 147 which subdirectory the command is invoked in.
 148
 149
 150 Author
 151 ------
 152 Written by Linus Torvalds <torvalds@osdl.org> and
 153 Junio C Hamano <junkio@cox.net>
 154
 155
 156 GIT
 157 ---
 158 Part of the gitlink:git[7] suite