diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 42 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.8.2.txt | 25 | ||||
| -rw-r--r-- | Documentation/git-add.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-bisect.txt | 7 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 26 |
5 files changed, 88 insertions, 22 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 9eb2d9fe7e..b1bfff630f 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -18,6 +18,7 @@ code. For Git in general, three rough rules are: judgement call, the decision based more on real world constraints people face than what the paper standard says. +Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code (this is a good guideline, no matter which project you are @@ -179,6 +180,47 @@ For C programs: - Use Git's gettext wrappers to make the user interface translatable. See "Marking strings for translation" in po/README. +For Perl programs: + + - Most of the C guidelines above apply. + + - We try to support Perl 5.8 and later ("use Perl 5.008"). + + - use strict and use warnings are strongly preferred. + + - Don't overuse statement modifiers unless using them makes the + result easier to follow. + + ... do something ... + do_this() unless (condition); + ... do something else ... + + is more readable than: + + ... do something ... + unless (condition) { + do_this(); + } + ... do something else ... + + *only* when the condition is so rare that do_this() will be almost + always called. + + - We try to avoid assignments inside "if ()" conditions. + + - Learn and use Git.pm if you need that functionality. + + - For Emacs, it's useful to put the following in + GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: + + ;; note the first part is useful for C editing, too + ((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) + For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). diff --git a/Documentation/RelNotes/1.8.2.txt b/Documentation/RelNotes/1.8.2.txt index a244034b90..ad6496f826 100644 --- a/Documentation/RelNotes/1.8.2.txt +++ b/Documentation/RelNotes/1.8.2.txt @@ -39,6 +39,12 @@ UI, Workflows & Features All-caps "GIT" was merely a way to imitate "Git" typeset in small caps in our ASCII text only documentation and to be avoided. + * The completion script (in contrib/completion) used to let the + default completer to suggest pathnames, which gave too many + irrelevant choices (e.g. "git add" would not want to add an + unmodified path). It learnt to use a more git-aware logic to + enumerate only relevant ones. + * In bare repositories, "git shortlog" and other commands now read mailmap files from the tip of the history, to help running these tools in server settings. @@ -248,12 +254,22 @@ details). was merged to 'maint' and 1.8.1.2 was with a severe performance degradations and needs to merge a fix-up topic. + * The smart HTTP clients forgot to verify the content-type that comes + back from the server side to make sure that the request is being + handled properly. + (merge 3443db5 sp/smart-http-content-type-check later to maint). + * "git am" did not parse datestamp correctly from Hg generated patch, when it is run in a locale outside C (or en). * "git apply" misbehaved when fixing whitespace breakages by removing excess trailing blank lines. + * "git apply --summary" has been taught to make sure the similarity + value shown in its output is sensible, even when the input had a + bogus value. + (merge afcb6ac jk/apply-similaritly-parsing later to maint). + * A tar archive created by "git archive" recorded a directory in a way that made NetBSD's implementation of "tar" sometimes unhappy. @@ -279,6 +295,11 @@ details). failed to remove the real location of the $GIT_DIR it created. This was most visible when interrupting a submodule update. + * We used to have an arbitrary 32 limit for combined diff input, + resulting in incorrect number of leading colons shown when showing + the "--raw --cc" output. + (merge edbc00e jc/combine-diff-many-parents later to maint). + * "git fetch --depth" was broken in at least three ways. The resulting history was deeper than specified by one commit, it was unclear how to wipe the shallowness of the repository with the @@ -377,6 +398,10 @@ details). unfortunately is still relevant because some people use ancient distros. + * The autoconf subsystem passed --mandir down to generated + config.mak.autogen but forgot to do the same for --htmldir. + (merge fc1c541 ct/autoconf-htmldir later to maint). + * We have been carrying a translated and long-unmaintained copy of an old version of the tutorial; removed. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 533355984c..d980e2cb7d 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--] - [<filepattern>...] + [<pathspec>...] DESCRIPTION ----------- @@ -49,7 +49,7 @@ commit. OPTIONS ------- -<filepattern>...:: +<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 add `dir/file1` @@ -100,21 +100,21 @@ apply to the index. See EDITING PATCHES below. -u:: --update:: - Only match <filepattern> against already tracked files in + Only match <pathspec> against already tracked files in the index rather than the working tree. That means that it will never stage new files, but that it will stage modified new contents of tracked files and that it will remove files from the index if the corresponding files in the working tree have been removed. + -If no <filepattern> is given, the current version of Git defaults to +If no <pathspec> is given, the current version of Git defaults to "."; in other words, update all tracked files in the current directory and its subdirectories. This default will change in a future version of Git, hence the form without <filepattern> should not be used. -A:: --all:: - Like `-u`, but match <filepattern> against files in the + Like `-u`, but match <pathspec> against files in the working tree in addition to the index. That means that it will find new files as well as staging modified content and removing files that are no longer in the working tree. diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index b4831bb0cf..f986c5cb3a 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -83,7 +83,7 @@ Bisect reset ~~~~~~~~~~~~ After a bisect session, to clean up the bisection state and return to -the original HEAD, issue the following command: +the original HEAD (i.e., to quit bisecting), issue the following command: ------------------------------------------------ $ git bisect reset @@ -284,6 +284,7 @@ EXAMPLES ------------ $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good $ git bisect run make # "make" builds the app +$ git bisect reset # quit the bisect session ------------ * Automatically bisect a test failure between origin and HEAD: @@ -291,6 +292,7 @@ $ git bisect run make # "make" builds the app ------------ $ git bisect start HEAD origin -- # HEAD is bad, origin is good $ git bisect run make test # "make test" builds and tests +$ git bisect reset # quit the bisect session ------------ * Automatically bisect a broken test case: @@ -302,6 +304,7 @@ make || exit 125 # this skips broken builds ~/check_test_case.sh # does the test case pass? $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 $ git bisect run ~/test.sh +$ git bisect reset # quit the bisect session ------------ + Here we use a "test.sh" custom script. In this script, if "make" @@ -351,6 +354,7 @@ use `git cherry-pick` instead of `git merge`.) ------------ $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" +$ git bisect reset # quit the bisect session ------------ + This shows that you can do without a run script if you write the test @@ -368,6 +372,7 @@ $ git bisect run sh -c ' rm -f tmp.$$ test $rc = 0' +$ git bisect reset # quit the bisect session ------------ + In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 5077e7cd20..32cadc3f73 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -782,7 +782,7 @@ e05db0fd4f31dde7005f075a84f96b360d05984b Or you could recall that the ... operator selects all commits contained reachable from either one reference or the other but not -both: so +both; so ------------------------------------------------- $ git log origin...master @@ -1562,17 +1562,11 @@ Ensuring good performance ------------------------- On large repositories, Git depends on compression to keep the history -information from taking up too much space on disk or in memory. - -This compression is not performed automatically. Therefore you -should occasionally run linkgit:git-gc[1]: - -------------------------------------------------- -$ git gc -------------------------------------------------- - -to recompress the archive. This can be very time-consuming, so -you may prefer to run `git gc` when you are not doing other work. +information from taking up too much space on disk or in memory. Some +Git commands may automatically run linkgit:git-gc[1], so you don't +have to worry about running it manually. However, compressing a large +repository may take a while, so you may want to call `gc` explicitly +to avoid automatic compression kicking in when it is not convenient. [[ensuring-reliability]] @@ -1931,11 +1925,11 @@ linkgit:git-daemon[1] man page for details. (See especially the examples section.) [[exporting-via-http]] -Exporting a Git repository via http +Exporting a git repository via HTTP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Git protocol gives better performance and reliability, but on a -host with a web server set up, http exports may be simpler to set up. +host with a web server set up, HTTP exports may be simpler to set up. All you need to do is place the newly created bare Git repository in a directory that is exported by the web server, and make some @@ -1961,7 +1955,7 @@ $ git clone http://yourserver.com/~you/proj.git (See also link:howto/setup-git-server-over-http.txt[setup-git-server-over-http] for a slightly more sophisticated setup using WebDAV which also -allows pushing over http.) +allows pushing over HTTP.) [[pushing-changes-to-a-public-repository]] Pushing changes to a public repository @@ -3396,7 +3390,7 @@ $ git log --raw --all ------------------------------------------------ and just looked for the sha of the missing object (4b9458b..) in that -whole thing. It's up to you - Git does *have* a lot of information, it is +whole thing. It's up to you--Git does *have* a lot of information, it is just missing one particular blob version. [[the-index]] |