It's easy to adjust:
edit your files # this can include running "git add NEW" or "git rm BAD"
- git commit --amend -e -a
+ git commit --amend -a
git format-patch --stdout -1 > your-branch.diff
That replaces the most recent change-set with the revised one.
=======================
Your commit log should always start with a one-line summary, the second
line should be blank, and the remaining lines are usually ChangeLog-style
-entries for all affected files. Omit the leading TABs that you're used
-to seeing in a "real" ChangeLog file.
+entries for all affected files. However, it's fine -- even recommended --
+to write a few lines of prose describing the change, when the summary
+and ChangeLog entries don't give enough of the big picture. Omit the
+leading TABs that you're used to seeing in a "real" ChangeLog file, but
+keep the maximum line length at 72 or smaller, so that the generated
+ChangeLog lines, each with its leading TAB, will not exceed 80 columns.
+As for the ChangeLog-style content, please follow these guidelines:
+
+ http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html
Try to make the summary line fit one of the following forms:
prog1, prog2: change-description
doc: change-description
tests: change-description
+ build: change-description
+ maint: change-description
+
+
+Curly braces: use judiciously
+=============================
+Omit the curly braces around an "if", "while", "for" etc. body only when
+that body occupies a single line. In every other case we require the braces.
+This ensures that it is trivially easy to identify a single-*statement* loop:
+each has only one *line* in its body.
+
+Omitting braces with a single-line body is fine:
+
+ while (expr)
+ single_line_stmt ();
+
+However, the moment your loop/if/else body extends onto a second line,
+for whatever reason (even if it's just an added comment), then you should
+add braces. Otherwise, it would be too easy to insert a statement just
+before that comment (without adding braces), thinking it is already a
+multi-statement loop:
+
+ while (true)
+ /* comment... */ // BAD: multi-line body without braces
+ single_line_stmt ();
+
+Do this instead:
+
+ while (true)
+ { /* Always put braces around a multi-line body. */
+ /* explanation... */
+ single_line_stmt ();
+ }
+
+There is one exception: when the second body line is not at the same
+indentation level as the first body line.
+
+ if (expr)
+ error (0, 0, _("a diagnostic that would make this line"
+ " extend past the 80-column limit"));
+
+It is safe to omit the braces in the code above, since the
+further-indented second body line makes it obvious that this is still
+a single-statement body.
+
+To reiterate, don't do this:
+
+ if (expr)
+ while (expr_2) // BAD: multi-line body without braces
+ {
+ ...
+ }
+
+Do this, instead:
+
+ if (expr)
+ {
+ while (expr_2)
+ {
+ ...
+ }
+ }
+
+However, there is one exception in the other direction, when even a
+one-line block should have braces. That occurs when that one-line,
+brace-less block is an "else" block, and the corresponding "then" block
+*does* use braces. In that case, either put braces around the "else"
+block, or negate the "if"-condition and swap the bodies, putting the
+one-line block first and making the longer, multi-line block be the
+"else" block.
+
+ if (expr)
+ {
+ ...
+ ...
+ }
+ else
+ x = y; // BAD: braceless "else" with braced "then"
+
+This is preferred, especially when the multi-line body is more than a
+few lines long, because it is easier to read and grasp the semantics of
+an if-then-else block when the simpler block occurs first, rather than
+after the more involved block:
+
+ if (!expr)
+ x = y; /* more readable */
+ else
+ {
+ ...
+ ...
+ }
+
+If you'd rather not negate the condition, then add braces:
+
+ if (expr)
+ {
+ ...
+ ...
+ }
+ else
+ {
+ x = y;
+ }
+
+
+Use SPACE-only indentation in all[*] files
+==========================================
+We use space-only indentation in nearly all files.
+If you use Emacs and your coreutils working directory name matches,
+this code enables the right mode:
+
+ ;; In coreutils, indent with spaces everywhere (not TABs).
+ ;; Exceptions: Makefile and ChangeLog modes.
+ (add-hook 'find-file-hook '(lambda ()
+ (if (and buffer-file-name
+ (string-match "/coreutils\\>" (buffer-file-name))
+ (not (string-equal mode-name "Change Log"))
+ (not (string-equal mode-name "Makefile")))
+ (setq indent-tabs-mode nil))))
+[*] Makefile and ChangeLog files are exempt, of course.
-Use SPACE-only indentation in new files.
-========================================
-In any new file, eliminate all leading TABs (e.g., via running GNU indent
-with --no-tabs) and put these lines at the end of the file:
[FIXME: suggest vim syntax to do same thing, if it can be done safely.
Most distros now "set nomodeline" by default for a good reason. ]
-/*
- * Local variables:
- * indent-tabs-mode: nil
- * End:
- */
-
-Do not change TABs to spaces or vice versa in any existing file.
-
Send patches to the address listed in --help output
===================================================
active voice, not a passive one. I.e., say "print the frobnozzle",
not "the frobnozzle will be printed".
+Please add comments per the GNU Coding Standard:
+ http://www.gnu.org/prep/standards/html_node/Comments.html
+
Minor syntactic preferences
===========================
addition that exercises it. If you fix a bug, add at least one test that
fails without the patch, but that succeeds once your patch is applied.
If you add a feature, add tests to exercise as much of the new code
-as possible. Note to run tests/misc/newtest in isolation you can do:
+as possible. Note to run tests/misc/new-test in isolation you can do:
- (cd tests && make check TESTS=misc/newtest VERBOSE=yes)
+ (cd tests && make check TESTS=misc/new-test VERBOSE=yes)
There are hundreds of tests in the tests/ directories. You can use
tests/sample-test as a template, or one of the various Perl-based ones
Miscellaneous useful git commands
=================================
- * gitk: give a graphical view of the revision graph
+ * gitk: give a graphical view of the revision graph of the current branch
+ * gitk --all: same, but display all branches
* git log: to get most of the same info in text form
* git log -p: same as above, but with diffs
* git log -p SOME_FILE: same as above, but limit to SOME_FILE
+ * git log -p -2 SOME_FILE: same as above, but print only two deltas
+ * git log -p -1: print the most recently committed change set
+ * git format-patch --stdout -1 > FILE: output the most recently committed
+ change set, in a format suitable to be submitted and/or applied via
+ "git am FILE".
* git reset --soft HEAD^: Commit the delta required to restore
state to the revision just before HEAD (i.e., next-to-last).
* git rebase -i master: run this from on a branch, and it gives
its SHA1 and then tag it or cherry-pick it onto an existing branch.
For example, run this:
git fsck --lost-found HEAD && cd .git/lost-found/commit \
- && for i in *; do git show $i|grep SOME_IDENTIFYING_STRING \
- && echo $i; done
+ && for i in *; do git show $i|grep SOME_IDENTIFYING_STRING \
+ && echo $i; done
The "git fsck ..." command creates the .git/lost-found/... hierarchy
listing all unreachable objects. Then the for loop
print SHA1s for commits that match via log or patch.
in your favorite web browser.
========================================================================
-Copyright (C) 2009 Free Software Foundation, Inc.
+Copyright (C) 2009-2010 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the ``GNU Free
projects / platform / upstream / coreutils.git / blobdiff