From 6c96753df9db7f790a2ac4d95ec2a868394cd5ff Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 8 Dec 2006 21:48:07 -0800 Subject: Documentation/git-commit: rewrite to make it more end-user friendly. Signed-off-by: Junio C Hamano --- Documentation/git-commit.txt | 233 +++++++++++++++++++++++++++++-------------- 1 file changed, 157 insertions(+), 76 deletions(-) (limited to 'Documentation/git-commit.txt') diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 517a86b238..97d66ef4d2 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -14,25 +14,41 @@ SYNOPSIS DESCRIPTION ----------- -Updates the index file for given paths, or all modified files if -'-a' is specified, and makes a commit object. The command specified -by either the VISUAL or EDITOR environment variables are used to edit -the commit log message. +Use 'git commit' when you want to record your changes into the repository +along with a log message describing what the commit is about. All changes +to be committed must be explicitly identified using one of the following +methods: -Several environment variable are used during commits. They are -documented in gitlink:git-commit-tree[1]. +1. by using gitlink:git-add[1] to incrementally "add" changes to the + next commit before using the 'commit' command (Note: even modified + files must be "added"); +2. by using gitlink:git-rm[1] to identify content removal for the next + commit, again before using the 'commit' command; + +3. by directly listing files containing changes to be committed as arguments + to the 'commit' command, in which cases only those files alone will be + considered for the commit; + +4. by using the -a switch with the 'commit' command to automatically "add" + changes from all known files i.e. files that have already been committed + before, and perform the actual commit. + +The gitlink:git-status[1] command 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 you would give to +this command. + +If you make a commit and then found a mistake immediately after +that, you can recover from it with gitlink:git-reset[1]. -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more -information. OPTIONS ------- -a|--all:: - Update all paths in the index file. This flag notices - files that have been modified and deleted, but new files - you have not told git about are not affected. + 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. -c or -C :: Take existing commit object, and reuse the log message @@ -55,16 +71,13 @@ OPTIONS -s|--signoff:: Add Signed-off-by line at the end of the commit message. --v|--verify:: - Look for suspicious lines the commit introduces, and - abort committing if there is one. The definition of - 'suspicious lines' is currently the lines that has - trailing whitespaces, and the lines whose indentation - has a SP character immediately followed by a TAB - character. This is the default. - --n|--no-verify:: - The opposite of `--verify`. +--no-verify:: + By default, the command looks for suspicious lines the + commit introduces, and aborts committing if there is one. + The definition of 'suspicious lines' is currently the + lines that has trailing whitespaces, and the lines whose + indentation has a SP character immediately followed by a + TAB character. This option turns off the check. -e|--edit:: The message taken from file with `-F`, command line with @@ -95,69 +108,137 @@ but can be used to amend a merge commit. -- -i|--include:: - Instead of committing only the files specified on the - command line, update them in the index file and then - commit the whole index. This is the traditional - behavior. - --o|--only:: - Commit only the files specified on the command line. - This format cannot be used during a merge, nor when the - index and the latest commit does not match on the - specified paths to avoid confusion. + 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. \--:: Do not interpret any more arguments as options. ...:: - Files to be committed. The meaning of these is - different between `--include` and `--only`. Without - either, it defaults `--only` semantics. - -If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. + 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. -Discussion ----------- - -`git commit` without _any_ parameter commits the tree structure -recorded by the current index file. This is a whole-tree commit -even the command is invoked from a subdirectory. - -`git commit --include paths...` is equivalent to - - git update-index --remove paths... - git commit - -That is, update the specified paths to the index and then commit -the whole tree. - -`git commit paths...` largely bypasses the index file and -commits only the changes made to the specified paths. It has -however several safety valves to prevent confusion. - -. It refuses to run during a merge (i.e. when - `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users - that the traditional semantics now needs -i flag. - -. It refuses to run if named `paths...` are different in HEAD - and the index (ditto about reminding). Added paths are OK. - This is because an earlier `git diff` (not `git diff HEAD`) - would have shown the differences since the last `git - update-index paths...` to the user, and an inexperienced user - may mistakenly think that the changes between the index and - the HEAD (i.e. earlier changes made before the last `git - update-index paths...` was done) are not being committed. - -. It reads HEAD commit into a temporary index file, updates the - specified `paths...` and makes a commit. At the same time, - the real index file is also updated with the same `paths...`. +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 gitlink:git-add[1]. Removal +of a file is staged with gitlink:git-rm[1]. 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 +------------ + +//////////// +We should fix 'git rm' to remove goodbye.c from both index and +working tree for the above example. +//////////// + +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 for `hello.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 either gitlink:git-merge[1] or +gitlink:git-pull[1]) 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 gitlink:git-status[1] +and after fixing them manually in your working tree, you would +stage the result as usual with gitlink:git-add[1]: + +------------ +$ 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). + + +ENVIRONMENT VARIABLES +--------------------- +The command specified by either the VISUAL or EDITOR environment +variables is used to edit the commit log message. + +HOOKS +----- +This command can run `commit-msg`, `pre-commit`, and +`post-commit` hooks. See link:hooks.html[hooks] for more +information. -`git commit --all` updates the index file with _all_ changes to -the working tree, and makes a whole-tree commit, regardless of -which subdirectory the command is invoked in. +SEE ALSO +-------- +gitlink:git-add[1], +gitlink:git-rm[1], +gitlink:git-mv[1], +gitlink:git-merge[1], +gitlink:git-commit-tree[1] Author ------ -- cgit v1.3 From ebd124c6783da5e064963611ee17741cd173f6b5 Mon Sep 17 00:00:00 2001 From: Nicolas Pitre Date: Thu, 14 Dec 2006 23:15:44 -0500 Subject: make commit message a little more consistent and conforting It is nicer to let the user know when a commit succeeded all the time, not only the first time. Also the commit sha1 is much more useful than the tree sha1 in this case. This patch also introduces a -q switch to supress this message as well as the summary of created/deleted files. Signed-off-by: Nicolas Pitre Signed-off-by: Junio C Hamano --- Documentation/core-tutorial.txt | 14 +++----------- Documentation/diff-options.txt | 5 +++++ Documentation/git-commit.txt | 3 +++ Documentation/tutorial-2.txt | 29 ++++++++++++++++++++--------- builtin-commit-tree.c | 2 -- diff.c | 38 +++++++++++++++++++++++++++++++++++++- diff.h | 1 + git-commit.sh | 19 +++++++++++++++---- t/t1200-tutorial.sh | 2 -- 9 files changed, 84 insertions(+), 29 deletions(-) (limited to 'Documentation/git-commit.txt') diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 47505aa20a..1c311590c7 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -336,17 +336,9 @@ $ commit=$(echo 'Initial commit' | git-commit-tree $tree) $ git-update-ref HEAD $commit ------------------------------------------------ -which will say: - ----------------- -Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb ----------------- - -just to warn you about the fact that it created a totally new commit -that is not related to anything else. Normally you do this only *once* -for a project ever, and all later commits will be parented on top of an -earlier commit, and you'll never see this "Committing initial tree" -message ever again. +In this case this creates a totally new commit that is not related to +anything else. Normally you do this only *once* for a project ever, and +all later commits will be parented on top of an earlier commit. Again, normally you'd never actually do this by hand. There is a helpful script called `git commit` that will do all of this for you. So diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 9cdd171af7..f12082e134 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -21,6 +21,11 @@ deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. +--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. + --summary:: Output a condensed summary of extended header information such as creations, renames and mode changes. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 97d66ef4d2..0b74cd708e 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -113,6 +113,9 @@ but can be used to amend a merge commit. as well. This is usually not what you want unless you are concluding a conflicted merge. +-q|--quiet:: + Supress commit summary message. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/tutorial-2.txt b/Documentation/tutorial-2.txt index 6389de5ef7..8606381e6c 100644 --- a/Documentation/tutorial-2.txt +++ b/Documentation/tutorial-2.txt @@ -22,14 +22,14 @@ defaulting to local storage area $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" -Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe +Created initial commit 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" +Created commit c4d59f390b9cfd4318117afde11d601c1085f241 ------------------------------------------------ -What are the 40 digits of hex that git responded to the first commit -with? +What are the 40 digits of hex that git responded to the commit with? We saw in part one of the tutorial that commits have names like this. It turns out that every object in the git history is stored under @@ -39,13 +39,25 @@ the same data twice (since identical data is given an identical SHA1 name), and that the contents of a git object will never change (since that would change the object's name as well). +It is expected that the content of the commit object you created while +following the example above generates a different SHA1 hash than +the one shown above because the commit object records the time when +it was created and the name of the person performing the commit. + We can ask git about this particular object with the cat-file -command--just cut-and-paste from the reply to the initial commit, to -save yourself typing all 40 hex digits: +command. Don't copy the 40 hex digits from this example but use those +from your own version. Note that you can shorten it to only a few +characters to save yourself typing all 40 hex digits: ------------------------------------------------ -$ git cat-file -t 92b8b694ffb1675e5975148e1121810081dbdffe -tree +$ git-cat-file -t 54196cc2 +commit +$ git-cat-file commit 54196cc2 +tree 92b8b694ffb1675e5975148e1121810081dbdffe +author J. Bruce Fields 1143414668 -0500 +committer J. Bruce Fields 1143414668 -0500 + +initial commit ------------------------------------------------ A tree can refer to one or more "blob" objects, each corresponding to @@ -102,8 +114,7 @@ $ find .git/objects/ and the contents of these files is just the compressed data plus a header identifying their length and their type. The type is either a -blob, a tree, a commit, or a tag. We've seen a blob and a tree now, -so next we should look at a commit. +blob, a tree, a commit, or a tag. The simplest commit to find is the HEAD commit, which we can find from .git/HEAD: diff --git a/builtin-commit-tree.c b/builtin-commit-tree.c index e2e690a1ae..856f3cd841 100644 --- a/builtin-commit-tree.c +++ b/builtin-commit-tree.c @@ -107,8 +107,6 @@ int cmd_commit_tree(int argc, const char **argv, const char *prefix) if (new_parent(parents)) parents++; } - if (!parents) - fprintf(stderr, "Committing initial tree %s\n", argv[1]); init_buffer(&buffer, &size); add_buffer(&buffer, &size, "tree %s\n", sha1_to_hex(tree_sha1)); diff --git a/diff.c b/diff.c index 77ba641aa4..99744354a7 100644 --- a/diff.c +++ b/diff.c @@ -801,6 +801,35 @@ static void show_stats(struct diffstat_t* data, struct diff_options *options) set, total_files, adds, dels, reset); } +static void show_shortstats(struct diffstat_t* data) +{ + int i, adds = 0, dels = 0, total_files = data->nr; + + if (data->nr == 0) + return; + + for (i = 0; i < data->nr; i++) { + if (!data->files[i]->is_binary && + !data->files[i]->is_unmerged) { + int added = data->files[i]->added; + int deleted= data->files[i]->deleted; + if (!data->files[i]->is_renamed && + (added + deleted == 0)) { + total_files--; + } else { + adds += added; + dels += deleted; + } + } + free(data->files[i]->name); + free(data->files[i]); + } + free(data->files); + + printf(" %d files changed, %d insertions(+), %d deletions(-)\n", + total_files, adds, dels); +} + static void show_numstat(struct diffstat_t* data, struct diff_options *options) { int i; @@ -1771,6 +1800,7 @@ int diff_setup_done(struct diff_options *options) options->output_format &= ~(DIFF_FORMAT_RAW | DIFF_FORMAT_NUMSTAT | DIFF_FORMAT_DIFFSTAT | + DIFF_FORMAT_SHORTSTAT | DIFF_FORMAT_SUMMARY | DIFF_FORMAT_PATCH); @@ -1781,6 +1811,7 @@ int diff_setup_done(struct diff_options *options) if (options->output_format & (DIFF_FORMAT_PATCH | DIFF_FORMAT_NUMSTAT | DIFF_FORMAT_DIFFSTAT | + DIFF_FORMAT_SHORTSTAT | DIFF_FORMAT_SUMMARY | DIFF_FORMAT_CHECKDIFF)) options->recursive = 1; @@ -1872,6 +1903,9 @@ int diff_opt_parse(struct diff_options *options, const char **av, int ac) else if (!strcmp(arg, "--numstat")) { options->output_format |= DIFF_FORMAT_NUMSTAT; } + else if (!strcmp(arg, "--shortstat")) { + options->output_format |= DIFF_FORMAT_SHORTSTAT; + } else if (!strncmp(arg, "--stat", 6)) { char *end; int width = options->stat_width; @@ -2646,7 +2680,7 @@ void diff_flush(struct diff_options *options) separator++; } - if (output_format & (DIFF_FORMAT_DIFFSTAT|DIFF_FORMAT_NUMSTAT)) { + if (output_format & (DIFF_FORMAT_DIFFSTAT|DIFF_FORMAT_SHORTSTAT|DIFF_FORMAT_NUMSTAT)) { struct diffstat_t diffstat; memset(&diffstat, 0, sizeof(struct diffstat_t)); @@ -2660,6 +2694,8 @@ void diff_flush(struct diff_options *options) show_numstat(&diffstat, options); if (output_format & DIFF_FORMAT_DIFFSTAT) show_stats(&diffstat, options); + else if (output_format & DIFF_FORMAT_SHORTSTAT) + show_shortstats(&diffstat); separator++; } diff --git a/diff.h b/diff.h index 101b2b505d..eff445596d 100644 --- a/diff.h +++ b/diff.h @@ -29,6 +29,7 @@ typedef void (*diff_format_fn_t)(struct diff_queue_struct *q, #define DIFF_FORMAT_NUMSTAT 0x0004 #define DIFF_FORMAT_SUMMARY 0x0008 #define DIFF_FORMAT_PATCH 0x0010 +#define DIFF_FORMAT_SHORTSTAT 0x0020 /* These override all above */ #define DIFF_FORMAT_NAME 0x0100 diff --git a/git-commit.sh b/git-commit.sh index 05828bb113..a30bda19d5 100755 --- a/git-commit.sh +++ b/git-commit.sh @@ -80,6 +80,7 @@ no_edit= log_given= log_message= verify=t +quiet= verbose= signoff= force_author= @@ -241,6 +242,10 @@ $1" signoff=t shift ;; + -q|--q|--qu|--qui|--quie|--quiet) + quiet=t + shift + ;; -v|--v|--ve|--ver|--verb|--verbo|--verbos|--verbose) verbose=t shift @@ -615,11 +620,17 @@ then git-rerere fi -if test -x "$GIT_DIR"/hooks/post-commit && test "$ret" = 0 +if test "$ret" = 0 then - "$GIT_DIR"/hooks/post-commit + if test -x "$GIT_DIR"/hooks/post-commit + then + "$GIT_DIR"/hooks/post-commit + fi + if test -z "$quiet" + then + echo "Created${initial_commit:+ initial} commit $commit" + git-diff-tree --shortstat --summary --root --no-commit-id HEAD + fi fi -test "$ret" = 0 && git-diff-tree --summary --root --no-commit-id HEAD - exit "$ret" diff --git a/t/t1200-tutorial.sh b/t/t1200-tutorial.sh index 0272dd4293..eebe643bda 100755 --- a/t/t1200-tutorial.sh +++ b/t/t1200-tutorial.sh @@ -37,8 +37,6 @@ test_expect_success 'tree' "test 8988da15d077d4829fc51d8544c097def6644dbb = $tre output="$(echo "Initial commit" | git-commit-tree $(git-write-tree) 2>&1 > .git/refs/heads/master)" -test_expect_success 'commit' "test 'Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb' = \"$output\"" - git-diff-index -p HEAD > diff.output test_expect_success 'git-diff-index -p HEAD' 'cmp diff.expect diff.output' -- cgit v1.3