diff options
Diffstat (limited to 'Documentation')
36 files changed, 432 insertions, 253 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines new file mode 100644 index 0000000000..3b042db624 --- /dev/null +++ b/Documentation/CodingGuidelines @@ -0,0 +1,112 @@ +Like other projects, we also have some guidelines to keep to the +code. For git in general, three rough rules are: + + - Most importantly, we never say "It's in POSIX; we'll happily + ignore your needs should your system not conform to it." + We live in the real world. + + - However, we often say "Let's stay away from that construct, + it's not even in POSIX". + + - In spite of the above two rules, we sometimes say "Although + this is not in POSIX, it (is so convenient | makes the code + much more readable | has other good characteristics) and + practically all the platforms we care about support it, so + let's use it". + + Again, we live in the real world, and it is sometimes a + judgement call, the decision based more on real world + constraints people face than what the paper standard says. + + +As for more concrete guidelines, just imitate the existing code +(this is a good guideline, no matter which project you are +contributing to). But if you must have a list of rules, +here they are. + +For shell scripts specifically (not exhaustive): + + - We prefer $( ... ) for command substitution; unlike ``, it + properly nests. It should have been the way Bourne spelled + it from day one, but unfortunately isn't. + + - We use ${parameter-word} and its [-=?+] siblings, and their + colon'ed "unset or null" form. + + - We use ${parameter#word} and its [#%] siblings, and their + doubled "longest matching" form. + + - We use Arithmetic Expansion $(( ... )). + + - No "Substring Expansion" ${parameter:offset:length}. + + - No shell arrays. + + - No strlen ${#parameter}. + + - No regexp ${parameter/pattern/string}. + + - We do not use Process Substitution <(list) or >(list). + + - We prefer "test" over "[ ... ]". + + - We do not write the noiseword "function" in front of shell + functions. + +For C programs: + + - We use tabs to indent, and interpret tabs as taking up to + 8 spaces. + + - We try to keep to at most 80 characters per line. + + - When declaring pointers, the star sides with the variable + name, i.e. "char *string", not "char* string" or + "char * string". This makes it easier to understand code + like "char *string, c;". + + - We avoid using braces unnecessarily. I.e. + + if (bla) { + x = 1; + } + + is frowned upon. A gray area is when the statement extends + over a few lines, and/or you have a lengthy comment atop of + it. Also, like in the Linux kernel, if there is a long list + of "else if" statements, it can make sense to add braces to + single line blocks. + + - Try to make your code understandable. You may put comments + in, but comments invariably tend to stale out when the code + they were describing changes. Often splitting a function + into two makes the intention of the code much clearer. + + - Double negation is often harder to understand than no negation + at all. + + - Some clever tricks, like using the !! operator with arithmetic + constructs, can be extremely confusing to others. Avoid them, + unless there is a compelling reason to use them. + + - Use the API. No, really. We have a strbuf (variable length + string), several arrays with the ALLOC_GROW() macro, a + path_list for sorted string lists, a hash map (mapping struct + objects) named "struct decorate", amongst other things. + + - When you come up with an API, document it. + + - The first #include in C files, except in platform specific + compat/ implementations, should be git-compat-util.h or another + header file that includes it, such as cache.h or builtin.h. + + - If you are planning a new command, consider writing it in shell + or perl first, so that changes in semantics can be easily + changed and discussed. Many git commands started out like + that, and a few are still scripts. + + - Avoid introducing a new dependency into git. This means you + usually should stay away from scripting languages not already + used in the git core command set (unless your command is clearly + separate from it, such as an importer to convert random-scm-X + repositories to git). diff --git a/Documentation/Makefile b/Documentation/Makefile index 39ec0ede02..d88664177d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -37,9 +37,6 @@ man7dir=$(mandir)/man7 ASCIIDOC=asciidoc ASCIIDOC_EXTRA = -ifdef ASCIIDOC8 -ASCIIDOC_EXTRA += -a asciidoc7compatible -endif INSTALL?=install RM ?= rm -f DOC_REF = origin/man @@ -52,6 +49,13 @@ DOCBOOK2X_TEXI=docbook2x-texi -include ../config.mak.autogen -include ../config.mak +ifdef ASCIIDOC8 +ASCIIDOC_EXTRA += -a asciidoc7compatible +endif +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a docbook-xsl-172 +endif + # # Please note that there is a minor bug in asciidoc. # The version after 6.0.3 _will_ include the patch found here: diff --git a/Documentation/RelNotes-1.5.3.5.txt b/Documentation/RelNotes-1.5.3.5.txt index 4e46d2c2a2..7ff1d5d0d1 100644 --- a/Documentation/RelNotes-1.5.3.5.txt +++ b/Documentation/RelNotes-1.5.3.5.txt @@ -63,8 +63,8 @@ Fixes since v1.5.3.4 * Git segfaulted when reading an invalid .gitattributes file. Fixed. - * post-receive-email example hook fixed was fixed for - non-fast-forward updates. + * post-receive-email example hook was fixed for non-fast-forward + updates. * Documentation updates for supported (but previously undocumented) options of "git-archive" and "git-reflog". @@ -90,5 +90,5 @@ Fixes since v1.5.3.4 * "git-send-pack $remote frotz" segfaulted when there is nothing named 'frotz' on the local end. - * "git-rebase -interactive" did not handle its "--strategy" option + * "git-rebase --interactive" did not handle its "--strategy" option properly. diff --git a/Documentation/RelNotes-1.5.3.6.txt b/Documentation/RelNotes-1.5.3.6.txt new file mode 100644 index 0000000000..06e44f7735 --- /dev/null +++ b/Documentation/RelNotes-1.5.3.6.txt @@ -0,0 +1,21 @@ +GIT v1.5.3.6 Release Notes +========================== + +Fixes since v1.5.3.5 +-------------------- + + * git-cvsexportcommit handles root commits better; + + * git-svn dcommit used to clobber when sending a series of + patches; + + * git-grep sometimes refused to work when your index was + unmerged; + + * Quite a lot of documentation clarifications. + +-- +exec >/var/tmp/1 +O=v1.5.3.5-32-gcb6c162 +echo O=`git describe refs/heads/maint` +git shortlog --no-merges $O..refs/heads/maint diff --git a/Documentation/RelNotes-1.5.4.txt b/Documentation/RelNotes-1.5.4.txt index 133fa64d22..93fb9c914c 100644 --- a/Documentation/RelNotes-1.5.4.txt +++ b/Documentation/RelNotes-1.5.4.txt @@ -6,7 +6,10 @@ Updates since v1.5.3 * Comes with much improved gitk. - * git-reset is now built-in. + * "progress display" from many commands are a lot nicer to the + eye. Transfer commands show throughput data. + + * git-reset is now built-in and its output can be squelched with -q. * git-send-email can optionally talk over ssmtp and use SMTP-AUTH. @@ -46,6 +49,28 @@ Updates since v1.5.3 * Various Perforce importer updates. + * git-lost-found was deprecated in favor of git-fsck's --lost-found + option. + + * git-svnimport was removed in favor of git-svn. + + * git-bisect learned "skip" action to mark untestable commits. + + * rename detection diff family, while detecting exact matches, + has been greatly optimized. + + * Example update and post-receive hooks have been improved. + + * In addition there are quite a few internal clean-ups. Notably + + - many fork/exec have been replaced with run-command API, + brought from the msysgit effort. + + - introduction and more use of the option parser API. + + - enhancement and more use of the strbuf API. + + Fixes since v1.5.3 ------------------ @@ -54,6 +79,6 @@ this release, unless otherwise noted. -- exec >/var/tmp/1 -O=v1.5.3.4-450-g952a9e5 +O=v1.5.3.5-618-g5d4138a echo O=`git describe refs/heads/master` git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 61635bf04d..83bf54c7ac 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -20,9 +20,6 @@ Checklist (and a short version for the impatient): Patch: - use "git format-patch -M" to create the patch - - send your patch to <git@vger.kernel.org>. If you use - git-send-email(1), please test it first by sending - email to yourself. - do not PGP sign your patch - do not attach your patch, but read in the mail body, unless you cannot teach your mailer to @@ -31,13 +28,15 @@ Checklist (and a short version for the impatient): corrupt whitespaces. - provide additional information (which is unsuitable for the commit message) between the "---" and the diffstat - - send the patch to the list (git@vger.kernel.org) and the - maintainer (gitster@pobox.com). - if you change, add, or remove a command line option or make some other user interface change, the associated documentation should be updated as well. - if your name is not writable in ASCII, make sure that you send off a message in the correct encoding. + - send the patch to the list (git@vger.kernel.org) and the + maintainer (gitster@pobox.com). If you use + git-send-email(1), please test it first by sending + email to yourself. Long version: diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index af5b1558a6..99d8874aa0 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -23,7 +23,9 @@ ifdef::backend-docbook[] endif::backend-docbook[] ifdef::backend-docbook[] +ifndef::docbook-xsl-172[] # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +# v1.72 breaks with this because it replaces dots not in roff requests. [listingblock] <example><title>{title}</title> <literallayout> @@ -36,6 +38,7 @@ ifdef::doctype-manpage[] endif::doctype-manpage[] </literallayout> {title#}</example> +endif::docbook-xsl-172[] endif::backend-docbook[] ifdef::doctype-manpage[] diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 8d21d423e5..57a790df63 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -3,7 +3,8 @@ use File::Compare qw(compare); sub format_one { - my ($out, $name) = @_; + my ($out, $nameattr) = @_; + my ($name, $attr) = @$nameattr; my ($state, $description); $state = 0; open I, '<', "$name.txt" or die "No such file $name.txt"; @@ -26,8 +27,11 @@ sub format_one { die "No description found in $name.txt"; } if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) { - print $out "gitlink:$name\[1\]::\n"; - print $out "\t$text.\n\n"; + print $out "gitlink:$name\[1\]::\n\t"; + if ($attr) { + print $out "($attr) "; + } + print $out "$text.\n\n"; } else { die "Description does not match $name: $description"; @@ -39,8 +43,8 @@ while (<DATA>) { next if /^#/; chomp; - my ($name, $cat) = /^(\S+)\s+(.*)$/; - push @{$cmds{$cat}}, $name; + my ($name, $cat, $attr) = /^(\S+)\s+(.*?)(?:\s+(.*))?$/; + push @{$cmds{$cat}}, [$name, $attr]; } for my $cat (qw(ancillaryinterrogators @@ -124,9 +128,8 @@ git-index-pack plumbingmanipulators git-init mainporcelain git-instaweb ancillaryinterrogators gitk mainporcelain -git-local-fetch synchingrepositories git-log mainporcelain -git-lost-found ancillarymanipulators +git-lost-found ancillarymanipulators deprecated git-ls-files plumbinginterrogators git-ls-remote plumbinginterrogators git-ls-tree plumbinginterrogators @@ -178,8 +181,6 @@ git-show-branch ancillaryinterrogators git-show-index plumbinginterrogators git-show-ref plumbinginterrogators git-sh-setup purehelpers -git-ssh-fetch synchingrepositories -git-ssh-upload synchingrepositories git-stash mainporcelain git-status mainporcelain git-stripspace purehelpers @@ -187,7 +188,7 @@ git-submodule mainporcelain git-svn foreignscminterface git-symbolic-ref plumbingmanipulators git-tag mainporcelain -git-tar-tree plumbinginterrogators +git-tar-tree plumbinginterrogators deprecated git-unpack-file plumbinginterrogators git-unpack-objects plumbingmanipulators git-update-index plumbingmanipulators diff --git a/Documentation/config.txt b/Documentation/config.txt index edf50cd211..8d5d200580 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -345,8 +345,8 @@ branch.<name>.mergeoptions:: supported. clean.requireForce:: - A boolean to make git-clean do nothing unless given -f or -n. Defaults - to false. + A boolean to make git-clean do nothing unless given -f + or -n. Defaults to true. color.branch:: A boolean to enable/disable color in the output of @@ -661,6 +661,15 @@ pack.threads:: machines. The required amount of memory for the delta search window is however multiplied by the number of threads. +pack.indexVersion:: + Specify the default pack index version. Valid values are 1 for + legacy pack index used by Git versions prior to 1.5.2, and 2 for + the new pack index with capabilities for packs larger than 4 GB + as well as proper protection against the repacking of corrupted + packs. Version 2 is selected and this config option ignored + whenever the corresponding pack is larger than 2 GB. Otherwise + the default is 1. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 5df97a1f9d..bd6cd41245 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -828,7 +828,7 @@ that branch, and do some work there. ------------------------------------------------ $ git checkout mybranch $ echo "Work, work, work" >>hello -$ git commit -m 'Some work.' -i hello +$ git commit -m "Some work." -i hello ------------------------------------------------ Here, we just added another line to `hello`, and we used a shorthand for @@ -853,7 +853,7 @@ hasn't happened in the `master` branch at all. Then do ------------ $ echo "Play, play, play" >>hello $ echo "Lots of fun" >>example -$ git commit -m 'Some fun.' -i hello example +$ git commit -m "Some fun." -i hello example ------------ since the master branch is obviously in a much better mood. @@ -931,12 +931,13 @@ Another useful tool, especially if you do not always work in X-Window environment, is `git show-branch`. ------------------------------------------------ -$ git show-branch --topo-order master mybranch +$ git-show-branch --topo-order --more=1 master mybranch * [master] Merge work in mybranch ! [mybranch] Some work. -- - [master] Merge work in mybranch *+ [mybranch] Some work. +* [master^] Some fun. ------------------------------------------------ The first two lines indicate that it is showing the two branches @@ -954,10 +955,22 @@ because `mybranch` has not been merged to incorporate these commits from the master branch. The string inside brackets before the commit log message is a short name you can use to name the commit. In the above example, 'master' and 'mybranch' -are branch heads. 'master~1' is the first parent of 'master' +are branch heads. 'master^' is the first parent of 'master' branch head. Please see 'git-rev-parse' documentation if you see more complex cases. +[NOTE] +Without the '--more=1' option, 'git-show-branch' would not output the +'[master^]' commit, as '[mybranch]' commit is a common ancestor of +both 'master' and 'mybranch' tips. Please see 'git-show-branch' +documentation for details. + +[NOTE] +If there were more commits on the 'master' branch after the merge, the +merge commit itself would not be shown by 'git-show-branch' by +default. You would need to provide '--sparse' option to make the +merge commit visible in this case. + Now, let's pretend you are the one who did all the work in `mybranch`, and the fruit of your hard work has finally been merged to the `master` branch. Let's go back to `mybranch`, and run @@ -1077,11 +1090,6 @@ server like git Native transport does. Any stock HTTP server that does not even support directory index would suffice. But you must prepare your repository with `git-update-server-info` to help dumb transport downloaders. -+ -There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload` -programs, which are 'commit walkers'; they outlived their -usefulness when git Native and SSH transports were introduced, -and are not used by `git pull` or `git push` scripts. Once you fetch from the remote repository, you `merge` that with your current branch. @@ -1144,7 +1152,7 @@ back to the earlier repository with "hello" and "example" file, and bring ourselves back to the pre-merge state: ------------ -$ git show-branch --more=3 master mybranch +$ git show-branch --more=2 master mybranch ! [master] Merge work in mybranch * [mybranch] Merge work in mybranch -- @@ -1207,7 +1215,7 @@ $ git-read-tree -m -u $mb HEAD mybranch This is the same `git-read-tree` command we have already seen, but it takes three trees, unlike previous examples. This reads the contents of each tree into different 'stage' in the index -file (the first tree goes to stage 1, the second stage 2, +file (the first tree goes to stage 1, the second to stage 2, etc.). After reading three trees into three stages, the paths that are the same in all three stages are 'collapsed' into stage 0. Also paths that are the same in two of three stages are @@ -1607,8 +1615,8 @@ in both of them. You could merge in 'diff-fix' first and then 'commit-fix' next, like this: ------------ -$ git merge -m 'Merge fix in diff-fix' diff-fix -$ git merge -m 'Merge fix in commit-fix' commit-fix +$ git merge -m "Merge fix in diff-fix" diff-fix +$ git merge -m "Merge fix in commit-fix" commit-fix ------------ Which would result in: diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 001503205b..9709c35c98 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -1,5 +1,5 @@ -The output format from "git-diff-index", "git-diff-tree" and -"git-diff-files" are very similar. +The 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: @@ -62,7 +62,8 @@ respectively. diff format for merges ---------------------- -"git-diff-tree" and "git-diff-files" can take '-c' or '--cc' option +"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: @@ -86,10 +87,10 @@ Generating patches with -p -------------------------- When "git-diff-index", "git-diff-tree", or "git-diff-files" are run -with a '-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. +with a '-p' option, or "git diff" without the '--raw' 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. @@ -137,8 +138,8 @@ file made it into the new one. combined diff format -------------------- -git-diff-tree and git-diff-files can take '-c' or '--cc' option -to produce 'combined diff', which looks like this: +"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or +'--cc' option to produce 'combined diff', which looks like this: ------------ diff --combined describe.c diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index 08c61b1f1a..ce7c170d69 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -109,7 +109,7 @@ $ tar zxf frotz.tar.gz $ cd frotz $ git-init $ git add . <1> -$ git commit -m 'import of frotz source tree.' +$ git commit -m "import of frotz source tree." $ git tag v2.43 <2> ------------ + @@ -300,7 +300,7 @@ $ git merge topic/one topic/two && git merge hold/linus <8> $ git checkout maint $ git cherry-pick master~4 <9> $ compile/test -$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <10> +$ git tag -s -m "GIT 0.99.9x" v0.99.9x <10> $ git fetch ko && git show-branch master maint 'tags/ko-*' <11> $ git push ko <12> $ git push ko v0.99.9x <13> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 2fe7355555..63829d93cc 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -50,10 +50,10 @@ OPTIONS and `dir/file2`) can be given to add all files in the directory, recursively. --n:: +-n, \--dry-run:: Don't actually add the file(s), just show if they exist. --v:: +-v, \--verbose:: Be verbose. -f:: @@ -224,6 +224,7 @@ See Also -------- gitlink:git-status[1] gitlink:git-rm[1] +gitlink:git-reset[1] gitlink:git-mv[1] gitlink:git-commit[1] gitlink:git-update-index[1] diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index b7285bcdbc..5ce905de86 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -85,7 +85,7 @@ OPTIONS -a:: List both remote-tracking branches and local branches. --v:: +-v, --verbose:: Show sha1 and commit subject line for each head. --abbrev=<length>:: @@ -105,7 +105,7 @@ OPTIONS '--track' were given. --no-track:: - When -b is given and a branch is created off a remote branch, + When a branch is created off a remote branch, set up configuration so that git-pull will not retrieve data from the remote branch, ignoring the branch.autosetupmerge configuration variable. diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 76a2edfd9b..937c4a7926 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,7 +7,7 @@ git-cherry-pick - Apply the change introduced by an existing commit SYNOPSIS -------- -'git-cherry-pick' [--edit] [-n] [-x] <commit> +'git-cherry-pick' [--edit] [-n] [-m parent-number] [-x] <commit> DESCRIPTION ----------- @@ -44,6 +44,13 @@ OPTIONS described above, and `-r` was to disable it. Now the default is not to do `-x` so this option is a no-op. +-m parent-number|--mainline parent-number:: + Usually you cannot revert a merge because you do not know which + side of the merge should be considered the mainline. This + option specifies the parent number (starting from 1) of + the mainline and allows cherry-pick to replay the change + relative to the specified parent. + -n|--no-commit:: Usually the command automatically creates a commit with a commit log message stating which commit was diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index cca14d6b5d..14e58f3866 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git-clone' [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] <repository> [<directory>] + [--depth <depth>] [--] <repository> [<directory>] DESCRIPTION ----------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index e54fb12103..d4bfd49ce1 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -154,10 +154,13 @@ 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 +called the "index" with gitlink:git-add[1]. 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: diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index ce0f502468..11c4216c4a 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -82,6 +82,9 @@ include::diff-options.txt[] the diff to the named paths (you can give directory names and get diff for all files under them). +Output format +------------- +include::diff-format.txt[] EXAMPLES -------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 385ecc900f..895d750310 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -152,7 +152,7 @@ definition impossible to preserve signatures at any rate.) does this in the '.git-rewrite/' directory but you can override that choice by this parameter. --f\|--force:: +-f|--force:: `git filter-branch` refuses to start with an existing temporary directory or when there are already refs starting with 'refs/original/', unless forced. diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 9b5f86fc30..76316bbc9e 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -14,12 +14,12 @@ SYNOPSIS DESCRIPTION ----------- Acts as a filter, extracting the commit ID stored in archives created by -git-tar-tree. It reads only the first 1024 bytes of input, thus its +gitlink:git-archive[1]. It reads only the first 1024 bytes of input, thus its runtime is not influenced by the size of <tarfile> very much. If no commit ID is found, git-get-tar-commit-id quietly exists with a return code of 1. This can happen if <tarfile> had not been created -using git-tar-tree or if the first parameter of git-tar-tree had been +using git-archive or if the <treeish> parameter of git-archive had been a tree ID instead of a commit ID or tag. diff --git a/Documentation/git-local-fetch.txt b/Documentation/git-local-fetch.txt deleted file mode 100644 index e830deeff3..0000000000 --- a/Documentation/git-local-fetch.txt +++ /dev/null @@ -1,66 +0,0 @@ -git-local-fetch(1) -================== - -NAME ----- -git-local-fetch - Duplicate another git repository on a local system - - -SYNOPSIS --------- -[verse] -'git-local-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [-l] [-s] [-n] - commit-id path - -DESCRIPTION ------------ -THIS COMMAND IS DEPRECATED. - -Duplicates another git repository on a local system. - -OPTIONS -------- --c:: - Get the commit objects. --t:: - Get trees associated with the commit objects. --a:: - Get all the objects. --v:: - Report what is downloaded. --s:: - Instead of regular file-to-file copying use symbolic links to the objects - in the remote repository. --l:: - Before attempting symlinks (if -s is specified) or file-to-file copying the - remote objects, try to hardlink the remote objects into the local - repository. --n:: - Never attempt to file-to-file copy remote objects. Only useful with - -s or -l command-line options. - --w <filename>:: - Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on - the local end after the transfer is complete. - ---stdin:: - Instead of a commit id on the command line (which is not expected in this - case), 'git-local-fetch' expects lines on stdin in the format - - <commit-id>['\t'<filename-as-in--w>] - ---recover:: - Verify that everything reachable from target is fetched. Used after - an earlier fetch is interrupted. - -Author ------- -Written by Junio C Hamano <junkio@cox.net> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index bc739117be..7f808fcd76 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -11,6 +11,10 @@ SYNOPSIS DESCRIPTION ----------- + +*NOTE*: this command is deprecated. Use gitlink:git-fsck[1] with +the option '--lost-found' instead. + Finds dangling commits and tags from the object database, and creates refs to them in the .git/lost-found/ directory. Commits and tags that dereference to commits are stored in .git/lost-found/commit, diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 2c9cf743c7..3b8ca76dff 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -34,7 +34,7 @@ OPTIONS condition. An error happens when a source is neither existing nor controlled by GIT, or when it would overwrite an existing file unless '-f' is given. --n:: +-n, \--dry-run:: Do nothing; only show what would happen diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index e5dd4c1066..4a68aaba34 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git-push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] - [--repo=all] [-f | --force] [-v] [<repository> <refspec>...] + [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...] DESCRIPTION ----------- @@ -95,7 +95,7 @@ the remote repository. transfer spends extra cycles to minimize the number of objects to be sent and meant to be used on slower connection. --v:: +-v, \--verbose:: Run verbosely. include::urls-remotes.txt[] diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 027ba11bdb..0da8704a25 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -79,7 +79,7 @@ caution. Fetch updates for a named set of remotes in the repository as defined by remotes.<group>. If a named group is not specified on the command line, the configuration parameter remotes.default will get used; if -remotes.default is not defined, all remotes which do not the +remotes.default is not defined, all remotes which do not have the configuration parameter remote.<name>.skipDefaultUpdate set to true will be updated. (See gitlink:git-config[1]). diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 15e3aca9a1..050e4eadbb 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,8 +8,8 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git-reset' [--mixed | --soft | --hard] [<commit>] -'git-reset' [--mixed] <commit> [--] <paths>... +'git-reset' [--mixed | --soft | --hard] [-q] [<commit>] +'git-reset' [--mixed] [-q] <commit> [--] <paths>... DESCRIPTION ----------- @@ -45,6 +45,9 @@ OPTIONS switched to. Any changes to tracked files in the working tree since <commit> are lost. +-q:: + Be quiet, only report errors. + <commit>:: Commit to make the current HEAD. @@ -157,7 +160,7 @@ 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 commit -a -m "snapshot WIP" <1> $ git checkout master $ fix fix fix $ git commit ;# commit with real log diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 69db498447..3457c40787 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -7,7 +7,7 @@ git-revert - Revert an existing commit SYNOPSIS -------- -'git-revert' [--edit | --no-edit] [-n] <commit> +'git-revert' [--edit | --no-edit] [-n] [-m parent-number] <commit> DESCRIPTION ----------- @@ -27,6 +27,13 @@ OPTIONS message prior committing the revert. This is the default if you run the command from a terminal. +-m parent-number|--mainline parent-number:: + Usually you cannot revert a merge because you do not know which + side of the merge should be considered the mainline. This + option specifies the parent number (starting from 1) of + the mainline and allows revert to reverse the change + relative to the specified parent. + --no-edit:: With this option, `git-revert` will not start the commit message editor. diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index be61a82164..48c1d97f93 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -30,7 +30,7 @@ OPTIONS -f:: Override the up-to-date check. --n:: +-n, \--dry-run:: Don't actually remove the file(s), just show if they exist in the index. @@ -51,7 +51,7 @@ OPTIONS \--ignore-unmatch:: Exit with a zero status even if no files matched. -\--quiet:: +-q, \--quiet:: git-rm normally outputs one line (in the form of an "rm" command) for each file removed. This option suppresses that output. diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index e38b7021b4..659215ac72 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -113,8 +113,7 @@ The --cc option must be repeated for each user you want on the cc list. is not set, this will be prompted for. --suppress-from, --no-suppress-from:: - If this is set, do not add the From: address to the cc: list, if it - shows up in a From: line. + If this is set, do not add the From: address to the cc: list. Default is the value of 'sendemail.suppressfrom' configuration value; if that is unspecified, default to --no-suppress-from. diff --git a/Documentation/git-ssh-fetch.txt b/Documentation/git-ssh-fetch.txt deleted file mode 100644 index 8d3e2ffb2c..0000000000 --- a/Documentation/git-ssh-fetch.txt +++ /dev/null @@ -1,52 +0,0 @@ -git-ssh-fetch(1) -================ - -NAME ----- -git-ssh-fetch - Fetch from a remote repository over ssh connection - - - -SYNOPSIS --------- -'git-ssh-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url - -DESCRIPTION ------------ -THIS COMMAND IS DEPRECATED. - -Pulls from a remote repository over ssh connection, invoking -git-ssh-upload on the other end. It functions identically to -git-ssh-upload, aside from which end you run it on. - - -OPTIONS -------- -commit-id:: - Either the hash or the filename under [URL]/refs/ to - pull. - --c:: - Get the commit objects. --t:: - Get trees associated with the commit objects. --a:: - Get all the objects. --v:: - Report what is downloaded. --w:: - Writes the commit-id into the filename under $GIT_DIR/refs/ on - the local end after the transfer is complete. - - -Author ------- -Written by Daniel Barkalow <barkalow@iabervon.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-ssh-upload.txt b/Documentation/git-ssh-upload.txt deleted file mode 100644 index 5e2ca8dccf..0000000000 --- a/Documentation/git-ssh-upload.txt +++ /dev/null @@ -1,48 +0,0 @@ -git-ssh-upload(1) -================= - -NAME ----- -git-ssh-upload - Push to a remote repository over ssh connection - - -SYNOPSIS --------- -'git-ssh-upload' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] commit-id url - -DESCRIPTION ------------ -THIS COMMAND IS DEPRECATED. - -Pushes from a remote repository over ssh connection, invoking -git-ssh-fetch on the other end. It functions identically to -git-ssh-fetch, aside from which end you run it on. - -OPTIONS -------- -commit-id:: - Id of commit to push. - --c:: - Get the commit objects. --t:: - Get tree associated with the requested commit object. --a:: - Get all the objects. --v:: - Report what is uploaded. --w:: - Writes the commit-id into the filename under [URL]/refs/ on - the remote end after the transfer is complete. - -Author ------- -Written by Daniel Barkalow <barkalow@iabervon.org> - -Documentation --------------- -Documentation by Daniel Barkalow - -GIT ---- -Part of the gitlink:git[7] suite diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 5212358306..f80526ba7e 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -16,7 +16,7 @@ Remove multiple empty lines, and empty lines at beginning and end. OPTIONS ------- --s\|--strip-comments:: +-s|--strip-comments:: In addition to empty lines, also strip lines starting with '#'. <stream>:: diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index a88f722860..694cabab24 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -26,7 +26,7 @@ a regular file whose contents is `ref: refs/heads/master`. OPTIONS ------- --q:: +-q, --quiet:: Do not issue an error message if the <name> is not a symbolic ref but a detached HEAD; instead exit with non-zero status silently. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 20cf8ff816..19bd25f299 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -148,22 +148,23 @@ with `$Id$` upon check-in. `filter` ^^^^^^^^ -A `filter` attribute can be set to a string value. This names +A `filter` attribute can be set to a string value that names a filter driver specified in the configuration. -A filter driver consists of `clean` command and `smudge` +A filter driver consists of a `clean` command and a `smudge` command, either of which can be left unspecified. Upon -checkout, when `smudge` command is specified, the command is fed -the blob object from its standard input, and its standard output -is used to update the worktree file. Similarly, `clean` command -is used to convert the contents of worktree file upon checkin. +checkout, when the `smudge` command is specified, the command is +fed the blob object from its standard input, and its standard +output is used to update the worktree file. Similarly, the +`clean` command is used to convert the contents of worktree file +upon checkin. -Missing filter driver definition in the config is not an error +A missing filter driver definition in the config is not an error but makes the filter a no-op passthru. The content filtering is done to massage the content into a shape that is more convenient for the platform, filesystem, and -the user to use. The keyword here is "more convenient" and not +the user to use. The key phrase here is "more convenient" and not "turning something unusable into usable". In other words, the intent is that if someone unsets the filter driver definition, or does not have the appropriate filter program, the project diff --git a/Documentation/howto/recover-corrupted-blob-object.txt b/Documentation/howto/recover-corrupted-blob-object.txt new file mode 100644 index 0000000000..323b513ed0 --- /dev/null +++ b/Documentation/howto/recover-corrupted-blob-object.txt @@ -0,0 +1,134 @@ +Date: Fri, 9 Nov 2007 08:28:38 -0800 (PST) +From: Linus Torvalds <torvalds@linux-foundation.org> +Subject: corrupt object on git-gc +Abstract: Some tricks to reconstruct blob objects in order to fix + a corrupted repository. + +On Fri, 9 Nov 2007, Yossi Leybovich wrote: +> +> Did not help still the repository look for this object? +> Any one know how can I track this object and understand which file is it + +So exactly *because* the SHA1 hash is cryptographically secure, the hash +itself doesn't actually tell you anything, in order to fix a corrupt +object you basically have to find the "original source" for it. + +The easiest way to do that is almost always to have backups, and find the +same object somewhere else. Backups really are a good idea, and git makes +it pretty easy (if nothing else, just clone the repository somewhere else, +and make sure that you do *not* use a hard-linked clone, and preferably +not the same disk/machine). + +But since you don't seem to have backups right now, the good news is that +especially with a single blob being corrupt, these things *are* somewhat +debuggable. + +First off, move the corrupt object away, and *save* it. The most common +cause of corruption so far has been memory corruption, but even so, there +are people who would be interested in seeing the corruption - but it's +basically impossible to judge the corruption until we can also see the +original object, so right now the corrupt object is useless, but it's very +interesting for the future, in the hope that you can re-create a +non-corrupt version. + +So: + +> ib]$ mv .git/objects/4b/9458b3786228369c63936db65827de3cc06200 ../ + +This is the right thing to do, although it's usually best to save it under +it's full SHA1 name (you just dropped the "4b" from the result ;). + +Let's see what that tells us: + +> ib]$ git-fsck --full +> broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 +> to blob 4b9458b3786228369c63936db65827de3cc06200 +> missing blob 4b9458b3786228369c63936db65827de3cc06200 + +Ok, I removed the "dangling commit" messages, because they are just +messages about the fact that you probably have rebased etc, so they're not +at all interesting. But what remains is still very useful. In particular, +we now know which tree points to it! + +Now you can do + + git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 + +which will show something like + + 100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore + 100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap + 100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING + 100644 blob ee909f2cc49e54f0799a4739d24c4cb9151ae453 CREDITS + 040000 tree 0f5f709c17ad89e72bdbbef6ea221c69807009f6 Documentation + 100644 blob 1570d248ad9237e4fa6e4d079336b9da62d9ba32 Kbuild + 100644 blob 1c7c229a092665b11cd46a25dbd40feeb31661d9 MAINTAINERS + ... + +and you should now have a line that looks like + + 10064 blob 4b9458b3786228369c63936db65827de3cc06200 my-magic-file + +in the output. This already tells you a *lot* it tells you what file the +corrupt blob came from! + +Now, it doesn't tell you quite enough, though: it doesn't tell what +*version* of the file didn't get correctly written! You might be really +lucky, and it may be the version that you already have checked out in your +working tree, in which case fixing this problem is really simple, just do + + git hash-object -w my-magic-file + +again, and if it outputs the missing SHA1 (4b945..) you're now all done! + +But that's the really lucky case, so let's assume that it was some older +version that was broken. How do you tell which version it was? + +The easiest way to do it is to do + + git log --raw --all --full-history -- subdirectory/my-magic-file + +and that will show you the whole log for that file (please realize that +the tree you had may not be the top-level tree, so you need to figure out +which subdirectory it was in on your own), and because you're asking for +raw output, you'll now get something like + + commit abc + Author: + Date: + .. + :100644 100644 4b9458b... newsha... M somedirectory/my-magic-file + + + commit xyz + Author: + Date: + + .. + :100644 100644 oldsha... 4b9458b... M somedirectory/my-magic-file + +and this actually tells you what the *previous* and *subsequent* versions +of that file were! So now you can look at those ("oldsha" and "newsha" +respectively), and hopefully you have done commits often, and can +re-create the missing my-magic-file version by looking at those older and +newer versions! + +If you can do that, you can now recreate the missing object with + + git hash-object -w <recreated-file> + +and your repository is good again! + +(Btw, you could have ignored the fsck, and started with doing a + + 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 +just missing one particular blob version. + +Trying to recreate trees and especially commits is *much* harder. So you +were lucky that it's a blob. It's quite possible that you can recreate the +thing. + + Linus diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index d99adc6f72..c7cfbbccfc 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -475,7 +475,7 @@ Bisecting: 3537 revisions left to test after this If you run "git branch" at this point, you'll see that git has temporarily moved you to a new branch named "bisect". This branch points to a commit (with commit id 65934...) that is reachable from -v2.6.19 but not from v2.6.18. Compile and test it, and see whether +"master" but not from v2.6.18. Compile and test it, and see whether it crashes. Assume it does crash. Then: ------------------------------------------------- @@ -1367,7 +1367,7 @@ If you make a commit that you later wish you hadn't, there are two fundamentally different ways to fix the problem: 1. You can create a new commit that undoes whatever was done - by the previous commit. This is the correct thing if your + by the old commit. This is the correct thing if your mistake has already been made public. 2. You can go back and modify the old commit. You should @@ -1568,7 +1568,7 @@ $ git log master@{1} ------------------------------------------------- This lists the commits reachable from the previous version of the head. -This syntax can be used to with any git command that accepts a commit, +This syntax can be used with any git command that accepts a commit, not just with git log. Some other examples: ------------------------------------------------- |