diff options
Diffstat (limited to 'Documentation')
54 files changed, 871 insertions, 515 deletions
diff --git a/Documentation/RelNotes-1.5.4.txt b/Documentation/RelNotes-1.5.4.txt new file mode 100644 index 0000000000..a4a2a7f429 --- /dev/null +++ b/Documentation/RelNotes-1.5.4.txt @@ -0,0 +1,124 @@ +GIT v1.5.4 Release Notes +======================== + +Updates since v1.5.3 +-------------------- + + * Comes with much improved gitk. + + * "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. + + * git-rebase learned --whitespace option. + + * git-remote knows --mirror mode. + + * git-merge can call the "post-merge" hook. + + * git-pack-objects can optionally run deltification with multiple threads. + + * git-archive can optionally substitute keywords in files marked with + export-subst attribute. + + * git-for-each-ref learned %(xxxdate:<dateformat>) syntax to + show the various date fields in different formats. + + * git-gc --auto is a low-impact way to automatically run a + variant of git-repack that does not lose unreferenced objects + (read: safer than the usual one) after the user accumulates + too many loose objects. + + * You need to explicitly set clean.requireForce to "false" to allow + git-clean without -f to do any damage (lack of the configuration + variable used to mean "do not require", but we now use the safer + default). + + * git-push has been rewritten in C. + + * git-push learned --dry-run option to show what would happen + if a push is run. + + * git-remote learned "rm" subcommand. + + * git-rebase --interactive mode can now work on detached HEAD. + + * git-cvsserver can be run via git-shell. + + * git-am and git-rebase are far less verbose. + + * git-pull learned to pass --[no-]ff option to underlying git-merge. + + * Various Perforce importer updates. + + * git-lost-found was deprecated in favor of git-fsck's --lost-found + option. + + * "git log" learned --early-output option to help interactive + GUI implementations. + + * git-svnimport was removed in favor of git-svn. + + * git-bisect learned "skip" action to mark untestable commits. + + * git-format-patch learned "format.numbered" configuration variable + to automatically turn --numbered option on when more than one + commits are formatted. + + * git-ls-files learned "--exclude-standard" to use the canned + set of exclude files. + + * git-rebase now detaches head during its operation, so after a + successful "git rebase" operation, the reflog entry branch@{1} + for the current branch points at the commit before the rebase + was started. + + * "git-tag -a -f existing" begins the editor session using the + existing annotation message. + + * "git cvsexportcommit" learned -w option to specify and switch + to the CVS working directory. + + * "git checkout" from a subdirectory learned to use "../path" + to allow checking out a path outside the current directory + without cd'ing up. + + * Output processing for '--pretty=format:<user format>' has + been optimized. + + * 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 +------------------ + +All of the fixes in v1.5.3 maintenance series are included in +this release, unless otherwise noted. + + * git-svn talking with the SVN over http will correctly quote branch + and project names. + + * "git rev-list --objects A..B" choked when the lower boundary + of the range involved a subproject. This fix is also queued + for 'maint' (but not in there yet). + +-- +exec >/var/tmp/1 +O=v1.5.3.6-727-g5d3d1ca +echo O=`git describe refs/heads/master` +git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 4ee76eaf99..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 @@ -94,7 +98,6 @@ git-clone mainporcelain git-commit mainporcelain git-commit-tree plumbingmanipulators git-config ancillarymanipulators -git-convert-objects ancillarymanipulators git-count-objects ancillaryinterrogators git-cvsexportcommit foreignscminterface git-cvsimport foreignscminterface @@ -125,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 @@ -179,17 +181,14 @@ 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 git-submodule mainporcelain git-svn foreignscminterface -git-svnimport 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 83bc33c421..39d1ef5298 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -188,7 +188,7 @@ core.worktree:: Set the path to the working tree. The value will not be used in combination with repositories found automatically in a .git directory (i.e. $GIT_DIR is not set). - This can be overriden by the GIT_WORK_TREE environment + This can be overridden by the GIT_WORK_TREE environment variable and the '--work-tree' command line option. core.logAllRefUpdates:: @@ -326,10 +326,11 @@ branch.<name>.remote:: If this option is not given, `git fetch` defaults to remote "origin". branch.<name>.merge:: - When in branch <name>, it tells `git fetch` the default refspec to - be marked for merging in FETCH_HEAD. The value has exactly to match - a remote part of one of the refspecs which are fetched from the remote - given by "branch.<name>.remote". + When in branch <name>, it tells `git fetch` the default + refspec to be marked for merging in FETCH_HEAD. The value is + handled like the remote part of a refspec, and must match a + ref which is fetched from the remote given by + "branch.<name>.remote". The merge information is used by `git pull` (which at first calls `git fetch`) to lookup the default branch for merging. Without this option, `git pull` defaults to merge the first refspec fetched. @@ -339,9 +340,15 @@ branch.<name>.merge:: branch.<name>.merge to the desired branch, and use the special setting `.` (a period) for branch.<name>.remote. +branch.<name>.mergeoptions:: + Sets default options for merging into branch <name>. The syntax and + supported options are equal to that of gitlink:git-merge[1], but + option values containing whitespace characters are currently not + 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 @@ -427,6 +434,12 @@ fetch.unpackLimit:: pack from a push can make the push operation complete faster, especially on slow filesystems. +format.numbered:: + A boolean which can enable sequence numbers in patch subjects. + Seting this option to "auto" will enable it only if there is + more than one patch. See --numbered option in + gitlink:git-format-patch[1]. + format.headers:: Additional email headers to include in a patch to be submitted by mail. See gitlink:git-format-patch[1]. @@ -441,6 +454,19 @@ gc.aggressiveWindow:: algorithm used by 'git gc --aggressive'. This defaults to 10. +gc.auto:: + When there are approximately more than this many loose + objects in the repository, `git gc --auto` will pack them. + Some Porcelain commands use this command to perform a + light-weight garbage collection from time to time. Setting + this to 0 disables it. + +gc.autopacklimit:: + When there are more than this many packs that are not + marked with `*.keep` file in the repository, `git gc + --auto` consolidates them into one larger pack. Setting + this to 0 disables this. + gc.packrefs:: `git gc` does not run `git pack-refs` in a bare repository by default so that older dumb-transport clients can still fetch @@ -590,7 +616,7 @@ merge.verbosity:: message if conflicts were detected. Level 1 outputs only conflicts, 2 outputs conflicts and file changes. Level 5 and above outputs debugging information. The default is level 2. - Can be overriden by 'GIT_MERGE_VERBOSITY' environment variable. + Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. merge.<driver>.name:: Defines a human readable name for a custom low-level @@ -634,9 +660,26 @@ pack.deltaCacheSize:: A value of 0 means no limit. Defaults to 0. pack.deltaCacheLimit:: - The maxium size of a delta, that is cached in + The maximum size of a delta, that is cached in gitlink:git-pack-objects[1]. Defaults to 1000. +pack.threads:: + Specifies the number of threads to spawn when searching for best + delta matches. This requires that gitlink:git-pack-objects[1] + be compiled with pthreads otherwise this option is ignored with a + warning. This is meant to reduce packing time on multiprocessor + 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 c3f0be535d..bd6cd41245 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -553,13 +553,8 @@ can explore on your own. [NOTE] Most likely, you are not directly using the core -git Plumbing commands, but using Porcelain like Cogito on top -of it. Cogito works a bit differently and you usually do not -have to run `git-update-index` yourself for changed files (you -do tell underlying git about additions and removals via -`cg-add` and `cg-rm` commands). Just before you make a commit -with `cg-commit`, Cogito figures out which files you modified, -and runs `git-update-index` on them for you. +git Plumbing commands, but using Porcelain such as `git-add`, `git-rm' +and `git-commit'. Tagging a version @@ -686,8 +681,8 @@ $ git reset and in fact a lot of the common git command combinations can be scripted with the `git xyz` interfaces. You can learn things by just looking -at what the various git scripts do. For example, `git reset` is the -above two lines implemented in `git-reset`, but some things like +at what the various git scripts do. For example, `git reset` used to be +the above two lines implemented in `git-reset`, but some things like `git status` and `git commit` are slightly more complex scripts around the basic git commands. @@ -805,8 +800,8 @@ you have, you can say $ git branch ------------ -which is nothing more than a simple script around `ls .git/refs/heads`. -There will be asterisk in front of the branch you are currently on. +which used to be nothing more than a simple script around `ls .git/refs/heads`. +There will be an asterisk in front of the branch you are currently on. Sometimes you may wish to create a new branch _without_ actually checking it out and switching to it. If so, just use the command @@ -936,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 @@ -952,17 +948,29 @@ the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` branch. Three commits are shown along with their log messages. All of them have non blank characters in the first column (`*` -shows an ordinary commit on the current branch, `.` is a merge commit), which +shows an ordinary commit on the current branch, `-` is a merge commit), which means they are now part of the `master` branch. Only the "Some work" commit has the plus `+` character in the second column, 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 @@ -1188,7 +1196,7 @@ $ mb=$(git-merge-base HEAD mybranch) The command writes the commit object name of the common ancestor to the standard output, so we captured its output to a variable, -because we will be using it in the next step. BTW, the common +because we will be using it in the next step. By the way, the common ancestor commit is the "New day." commit in this case. You can tell it by: @@ -1454,8 +1462,7 @@ Although git is a truly distributed system, it is often convenient to organize your project with an informal hierarchy of developers. Linux kernel development is run this way. There is a nice illustration (page 17, "Merges to Mainline") in -link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf -[Randy Dunlap's presentation]. +link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation]. It should be stressed that this hierarchy is purely *informal*. There is nothing fundamental in git that enforces the "chain of diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index b1f528ae88..e4af393515 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -1,5 +1,25 @@ +// Please don't remove this comment as asciidoc behaves badly when +// the first non-empty line is ifdef/ifndef. The symptom is that +// without this comment the <git-diff-core> attribute conditionally +// defined below ends up being defined unconditionally. +// Last checked with asciidoc 7.0.2. + +ifndef::git-format-patch[] +ifndef::git-diff[] +:git-diff-core: 1 +endif::git-diff[] +endif::git-format-patch[] + +ifdef::git-format-patch[] -p:: - Generate patch (see section on generating patches) + Generate patches without diffstat. +endif::git-format-patch[] + +ifndef::git-format-patch[] +-p:: + Generate patch (see section on generating patches). + {git-diff? This is the default.} +endif::git-format-patch[] -u:: Synonym for "-p". @@ -13,6 +33,7 @@ --raw:: Generate the raw format. + {git-diff-core? This is the default.} --patch-with-raw:: Synonym for "-p --raw". @@ -41,6 +62,7 @@ --patch-with-stat:: Synonym for "-p --stat". + {git-format-patch? This is the default.} -z:: NUL-line termination on output. This affects the --raw diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index fd82fc19b5..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:: diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 1072fb87d1..4795349c10 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -16,8 +16,9 @@ The command takes various subcommands, and different options depending on the subcommand: git bisect start [<bad> [<good>...]] [--] [<paths>...] - git bisect bad <rev> - git bisect good <rev> + git bisect bad [<rev>] + git bisect good [<rev>...] + git bisect skip [<rev>...] git bisect reset [<branch>] git bisect visualize git bisect replay <logfile> @@ -134,6 +135,20 @@ $ git reset --hard HEAD~3 # try 3 revs before what Then compile and test the one you chose to try. After that, tell bisect what the result was as usual. +Bisect skip +~~~~~~~~~~~~ + +Instead of choosing by yourself a nearby commit, you may just want git +to do it for you using: + +------------ +$ git bisect skip # Current version cannot be tested +------------ + +But computing the commit to test may be slower afterwards and git may +eventually not be able to tell the first bad among a bad and one or +more "skip"ped commits. + Cutting down bisection by giving more parameters to bisect start ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -167,14 +182,18 @@ $ git bisect run my_script ------------ Note that the "run" script (`my_script` in the above example) should -exit with code 0 in case the current source code is good and with a -code between 1 and 127 (included) in case the current source code is -bad. +exit with code 0 in case the current source code is good. Exit with a +code between 1 and 127 (inclusive), except 125, if the current +source code is bad. Any other exit code will abort the automatic bisect process. (A program that does "exit(-1)" leaves $? = 255, see exit(3) manual page, the value is chopped with "& 0377".) +The special exit code 125 should be used when the current source code +cannot be tested. If the "run" script exits with this code, the current +revision will be skipped, see `git bisect skip` above. + You may often find that during bisect you want to have near-constant tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or "revision that does not have this commit needs this patch applied to diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 37cb8b83b2..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>:: diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 47b1e8c2fc..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 ----------- @@ -27,11 +27,12 @@ OPTIONS message prior committing. -x:: - Cause the command to append which commit was - cherry-picked after the original commit message when - making a commit. Do not use this option if you are - cherry-picking from your private branch because the - information is useless to the recipient. If on the + When recording the commit, append to the original commit + message a note that indicates which commit this change + was cherry-picked from. Append the note only for cherry + picks without conflicts. Do not use this option if + you are cherry-picking from your private branch because + the information is useless to the recipient. If on the other hand you are cherry-picking between two publicly visible branches (e.g. backporting a fix to a maintenance branch for an older release from a @@ -43,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..c90bcece24 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 ----------- @@ -130,6 +130,7 @@ OPTIONS for "host.xz:foo/.git"). Cloning into an existing directory is not allowed. +:git-clone: 1 include::urls.txt[] Examples diff --git a/Documentation/git-convert-objects.txt b/Documentation/git-convert-objects.txt deleted file mode 100644 index 9718abf86d..0000000000 --- a/Documentation/git-convert-objects.txt +++ /dev/null @@ -1,28 +0,0 @@ -git-convert-objects(1) -====================== - -NAME ----- -git-convert-objects - Converts old-style git repository - - -SYNOPSIS --------- -'git-convert-objects' - -DESCRIPTION ------------ -Converts old-style git repository to the latest format - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.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-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index c3922f9238..3f9d2295d3 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -8,7 +8,7 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- -'git-cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +'git-cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-w cvsworkdir] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID DESCRIPTION @@ -16,8 +16,9 @@ DESCRIPTION Exports a commit from GIT to a CVS checkout, making it easier to merge patches from a git repository into a CVS repository. -Execute it from the root of the CVS working copy. GIT_DIR must be defined. -See examples below. +Specify the name of a CVS checkout using the -w switch or execute it +from the root of the CVS working copy. In the latter case GIT_DIR must +be defined. See examples below. It does its best to do the safe thing, it will check that the files are unchanged and up to date in the CVS checkout, and it will not autocommit @@ -61,6 +62,11 @@ OPTIONS -u:: Update affected files from CVS repository before attempting export. +-w:: + Specify the location of the CVS checkout to use for the export. This + option does not require GIT_DIR to be set before execution if the + current directory is within a git repository. + -v:: Verbose. @@ -76,6 +82,12 @@ $ git-cvsexportcommit -v <commit-sha1> $ cvs commit -F .msg <files> ------------ +Merge one patch into CVS (-c and -w options). The working directory is within the Git Repo:: ++ +------------ + $ git-cvsexportcommit -v -c -w ~/project_cvs_checkout <commit-sha1> +------------ + Merge pending patches into CVS automatically -- only if you really know what you are doing:: + ------------ @@ -86,11 +98,11 @@ $ git-cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git-cvsexportcommit Author ------ -Written by Martin Langhoff <martin@catalyst.net.nz> +Written by Martin Langhoff <martin@catalyst.net.nz> and others. Documentation -------------- -Documentation by Martin Langhoff <martin@catalyst.net.nz> +Documentation by Martin Langhoff <martin@catalyst.net.nz> and others. GIT --- diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 201d5daf1a..2808a5ec44 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -75,6 +75,7 @@ and the range notations ("<commit>..<commit>" and OPTIONS ------- +:git-diff: 1 include::diff-options.txt[] <path>...:: @@ -128,7 +129,7 @@ $ git diff topic...master <3> + <1> Changes between the tips of the topic and the master branches. <2> Same as above. -<3> Changes that occured on the master branch since when the topic +<3> Changes that occurred on the master branch since when the topic branch was started off it. Limiting the diff output:: diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 6df8e85004..f1f90cca62 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -100,6 +100,11 @@ In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead. +As a special case for the date-type fields, you may specify a format for +the date by adding one of `:default`, `:relative`, `:short`, `:local`, +`:iso8601` or `:rfc2822` to the end of the fieldname; e.g. +`%(taggerdate:relative)`. + EXAMPLES -------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index f0617efa0a..6fb9429851 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,9 +9,10 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--thread] +'git-format-patch' [-k] [-o <dir> | --stdout] [--thread] [--attach[=<boundary>] | --inline[=<boundary>]] [-s | --signoff] [<common diff options>] + [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] @@ -65,6 +66,7 @@ reference. OPTIONS ------- +:git-format-patch: 1 include::diff-options.txt[] -<n>:: @@ -77,6 +79,9 @@ include::diff-options.txt[] -n|--numbered:: Name output in '[PATCH n/m]' format. +-N|--no-numbered:: + Name output in '[PATCH]' format. + --start-number <n>:: Start numbering the patches at <n> instead of 1. @@ -142,15 +147,16 @@ not add any suffix. CONFIGURATION ------------- -You can specify extra mail header lines to be added to each -message in the repository configuration. You can also specify -new defaults for the subject prefix and file suffix. +You can specify extra mail header lines to be added to each message +in the repository configuration, new defaults for the subject prefix +and file suffix, and number patches when outputting more than one. ------------ [format] headers = "Organization: git-foo\n" subjectprefix = CHANGE suffix = .txt + numbered = auto ------------ diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index c7742ca963..872056ea04 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -8,7 +8,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- -'git-gc' [--prune] [--aggressive] +'git-gc' [--prune] [--aggressive] [--auto] DESCRIPTION ----------- @@ -19,7 +19,8 @@ created from prior invocations of gitlink:git-add[1]. Users are encouraged to run this task on a regular basis within each repository to maintain good disk space utilization and good -operating performance. +operating performance. Some git commands may automatically run +`git-gc`; see the `--auto` flag below for details. OPTIONS ------- @@ -43,6 +44,25 @@ OPTIONS persistent, so this option only needs to be used occasionally; every few hundred changesets or so. +--auto:: + With this option, `git gc` checks whether any housekeeping is + required; if not, it exits without performing any work. + Some git commands run `git gc --auto` after performing + operations that could create many loose objects. ++ +Housekeeping is required if there are too many loose objects or +too many packs in the repository. If the number of loose objects +exceeds the value of the `gc.auto` configuration variable, then +all loose objects are combined into a single pack using +`git-repack -d -l`. Setting the value of `gc.auto` to 0 +disables automatic packing of loose objects. ++ +If the number of packs exceeds the value of `gc.autopacklimit`, +then existing packs (except those marked with a `.keep` file) +are consolidated into a single pack by using the `-A` option of +`git-repack`. Setting `gc.autopacklimit` to 0 disables +automatic consolidation of packs. + Configuration ------------- diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 9afb860381..3a69b719b5 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -8,7 +8,7 @@ git-http-push - Push objects over HTTP/DAV to another repository SYNOPSIS -------- -'git-http-push' [--all] [--force] [--verbose] <url> <ref> [<ref>...] +'git-http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...] DESCRIPTION ----------- @@ -30,6 +30,9 @@ OPTIONS the remote repository can lose commits; use it with care. +--dry-run:: + Do everything except actually send the updates. + --verbose:: Report the list of objects being walked locally and the list of objects successfully sent to the remote repository. diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index a8a7f6f04b..bf5c2bddf4 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -43,7 +43,7 @@ OPTIONS a default name determined from the pack content. If <pack-file> is not specified consider using --keep to prevent a race condition between this process and - gitlink::git-repack[1] . + gitlink::git-repack[1]. --fix-thin:: It is possible for gitlink:git-pack-objects[1] to build diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index cec60ee780..735008c1ab 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -27,7 +27,7 @@ OPTIONS The HTTP daemon command-line that will be executed. Command-line options may be specified here, and the configuration file will be added at the end of the command-line. - Currently, lighttpd and apache2 are the only supported servers. + Currently lighttpd, apache2 and webrick are supported. (Default: lighttpd) -m|--module-path:: 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-ls-files.txt b/Documentation/git-ls-files.txt index 9e454f0a4d..2ec0c0d270 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -15,6 +15,7 @@ SYNOPSIS [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] + [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--abbrev] [--] [<file>]\* @@ -77,6 +78,10 @@ OPTIONS read additional exclude patterns that apply only to the directory and its subdirectories in <file>. +--exclude-standard:: + Add the standard git exclusions: .git/info/exclude, .gitignore + in each directory, and the user's global exclusion file. + --error-unmatch:: If any <file> does not appear in the index, treat this as an error (return 1). diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 17e9f10c65..b726ddfe12 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -40,7 +40,7 @@ If "git-merge-index" is called with multiple <file>s (or -a) then it processes them in turn only stopping if merge returns a non-zero exit code. -Typically this is run with the a script calling git's imitation of +Typically this is run with a script calling git's imitation of the merge command from the RCS package. A sample script called "git-merge-one-file" is included in the diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 827838f7d0..eabd7ef33f 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -59,6 +59,10 @@ merge.verbosity:: above outputs debugging information. The default is level 2. Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable. +branch.<name>.mergeoptions:: + Sets default options for merging into branch <name>. The syntax and + supported options are equal to that of git-merge, but option values + containing whitespace characters are currently not supported. HOW MERGE WORKS --------------- diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 6c32c6d18e..a26c260162 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -25,12 +25,18 @@ OPTIONS -t or --tool=<tool>:: Use the merge resolution program specified by <tool>. Valid merge tools are: - kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, and opendiff + kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, and opendiff + If a merge resolution program is not specified, 'git mergetool' will use the configuration variable merge.tool. If the configuration variable merge.tool is not set, 'git mergetool' will pick a suitable default. ++ +You can explicitly provide a full path to the tool by setting the +configuration variable mergetool.<tool>.path. For example, you +can configure the absolute path to kdiff3 by setting +mergetool.kdiff3.path. Otherwise, 'git mergetool' assumes the tool +is available in PATH. Author ------ 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-pack-objects.txt b/Documentation/git-pack-objects.txt index d18259d93f..5237ab0c04 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -169,6 +169,14 @@ base-name:: length, this option typically shrinks the resulting packfile by 3-5 per-cent. +--threads=<n>:: + Specifies the number of threads to spawn when searching for best + delta matches. This requires that pack-objects be compiled with + pthreads otherwise this option is ignored with a warning. + This is meant to reduce packing time on multiprocessor machines. + The required amount of memory for the delta search window is + however multiplied by the number of threads. + --index-version=<version>[,<offset>]:: This is intended to be used by the test suite only. It allows to force the version for the generated pack index, and to force diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 6bc559ddd8..4a68aaba34 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,8 +9,8 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git-push' [--all] [--tags] [--receive-pack=<git-receive-pack>] - [--repo=all] [-f | --force] [-v] [<repository> <refspec>...] +'git-push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] + [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...] DESCRIPTION ----------- @@ -63,6 +63,9 @@ the remote repository. Instead of naming each ref to push, specifies that all refs under `$GIT_DIR/refs/heads/` be pushed. +\--dry-run:: + Do everything except actually send the updates. + \--tags:: All refs under `$GIT_DIR/refs/tags` are pushed, in addition to refspecs explicitly listed on the command @@ -92,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-rebase.txt b/Documentation/git-rebase.txt index dfb8a0da5b..e4326d3322 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -8,8 +8,9 @@ git-rebase - Forward-port local commits to the updated upstream head SYNOPSIS -------- [verse] -'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] [-C<n>] - [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>] +'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] + [-C<n>] [ --whitespace=<option>] [-p | --preserve-merges] + [--onto <newbase>] <upstream> [<branch>] 'git-rebase' --continue | --skip | --abort DESCRIPTION @@ -27,7 +28,10 @@ The current branch is reset to <upstream>, or <newbase> if the `git reset --hard <upstream>` (or <newbase>). The commits that were previously saved into the temporary area are -then reapplied to the current branch, one by one, in order. +then reapplied to the current branch, one by one, in order. Note that +any commits in HEAD which introduce the same textual changes as a commit +in HEAD..<upstream> are omitted (i.e., a patch already accepted upstream +with a different commit message or timestamp will be skipped). It is possible that a merge failure will prevent this process from being completely automatic. You will have to resolve any such merge failure @@ -61,6 +65,26 @@ would be: The latter form is just a short-hand of `git checkout topic` followed by `git rebase master`. +If the upstream branch already contains a change you have made (e.g., +because you mailed a patch which was applied upstream), then that commit +will be skipped. For example, running `git-rebase master` on the +following history (in which A' and A introduce the same set of changes, +but have different committer information): + +------------ + A---B---C topic + / + D---E---A'---F master +------------ + +will result in: + +------------ + B'---C' topic + / + D---E---A'---F master +------------ + Here is how you would transplant a topic branch based on one branch to another, to pretend that you forked the topic branch from the latter branch, using `rebase --onto`. @@ -209,6 +233,10 @@ OPTIONS context exist they all must match. By default no context is ever ignored. +--whitespace=<nowarn|warn|error|error-all|strip>:: + This flag is passed to the `git-apply` program + (see gitlink:git-apply[1]) that applies the patch. + -i, \--interactive:: Make a list of the commits which are about to be rebased. Let the user edit that list before rebasing. This mode can also be used to diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 886bc03c4a..4b263c249c 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,8 @@ SYNOPSIS -------- [verse] 'git-remote' -'git-remote' add [-t <branch>] [-m <branch>] [-f] <name> <url> +'git-remote' add [-t <branch>] [-m <branch>] [-f] [--mirror] <name> <url> +'git-remote' rm <name> 'git-remote' show <name> 'git-remote' prune <name> 'git-remote' update [group] @@ -45,6 +46,15 @@ multiple branches without grabbing all branches. With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set up to point at remote's `<master>` branch instead of whatever branch the `HEAD` at the remote repository actually points at. ++ +In mirror mode, enabled with `--mirror`, the refs will not be stored +in the 'refs/remotes/' namespace, but in 'refs/heads/'. This option +only makes sense in bare repositories. + +'rm':: + +Remove the remote named <name>. All remote tracking branches and +configuration settings for the remote are removed. 'show':: diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 87afa6f8da..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. diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 7cd0e8913e..989fbf3562 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -20,6 +20,7 @@ SYNOPSIS [ \--not ] [ \--all ] [ \--stdin ] + [ \--quiet ] [ \--topo-order ] [ \--parents ] [ \--timestamp ] @@ -34,6 +35,7 @@ SYNOPSIS [ \--pretty | \--header ] [ \--bisect ] [ \--bisect-vars ] + [ \--bisect-all ] [ \--merge ] [ \--reverse ] [ \--walk-reflogs ] @@ -269,6 +271,14 @@ limiting may be applied. In addition to the '<commit>' listed on the command line, read them from the standard input. +--quiet:: + + Don't print anything to standard output. This form of + git-rev-list is primarly meant to allow the caller to + test the exit status to see if a range of objects is fully + connected (or not). It is faster than redirecting stdout + to /dev/null as the output does not have to be formatted. + --cherry-pick:: Omit any commit that introduces the same change as @@ -354,6 +364,21 @@ the expected number of commits to be tested if `bisect_rev` turns out to be bad to `bisect_bad`, and the number of commits we are bisecting right now to `bisect_all`. +--bisect-all:: + +This outputs all the commit objects between the included and excluded +commits, ordered by their distance to the included and excluded +commits. The farthest from them is displayed first. (This is the only +one displayed by `--bisect`.) + +This is useful because it makes it easy to choose a good commit to +test when you want to avoid to test some of them for some reason (they +may not compile for example). + +This option can be used along with `--bisect-vars`, in this case, +after all the sorted commit objects, there will be the same text as if +`--bisect-vars` had been used alone. + -- Commit Ordering diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4758c33dee..329fce0aab 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -23,6 +23,13 @@ distinguish between them. OPTIONS ------- +--parseopt:: + Use `git-rev-parse` in option parsing mode (see PARSEOPT section below). + +--keep-dash-dash:: + Only meaningful in `--parseopt` mode. Tells the option parser to echo + out the first `--` met instead of skipping it. + --revs-only:: Do not output flags and parameters not meant for `git-rev-list` command. @@ -288,10 +295,75 @@ Here are a handful examples: C^@ I J F F^! D G H D F +PARSEOPT +-------- + +In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell +scripts the same facilities C builtins have. It works as an option normalizer +(e.g. splits single switches aggregate values), a bit like `getopt(1)` does. + +It takes on the standard input the specification of the options to parse and +understand, and echoes on the standard output a line suitable for `sh(1)` `eval` +to replace the arguments with normalized ones. In case of error, it outputs +usage on the standard error stream, and exits with code 129. + +Input Format +~~~~~~~~~~~~ + +`git-rev-parse --parseopt` input format is fully text based. It has two parts, +separated by a line that contains only `--`. The lines before the separator +(should be more than one) are used for the usage. +The lines after the separator describe the options. + +Each line of options has this format: + +------------ +<opt_spec><arg_spec>? SP+ help LF +------------ + +`<opt_spec>`:: + its format is the short option character, then the long option name + separated by a comma. Both parts are not required, though at least one + is necessary. `h,help`, `dry-run` and `f` are all three correct + `<opt_spec>`. + +`<arg_spec>`:: + an `<arg_spec>` tells the option parser if the option has an argument + (`=`), an optional one (`?` though its use is discouraged) or none + (no `<arg_spec>` in that case). + +The remainder of the line, after stripping the spaces, is used +as the help associated to the option. + +Blank lines are ignored, and lines that don't match this specification are used +as option group headers (start the line with a space to create such +lines on purpose). + +Example +~~~~~~~ + +------------ +OPTS_SPEC="\ +some-command [options] <args>... + +some-command does foo and bar! +-- +h,help show the help + +foo some nifty option --foo +bar= some cool option --bar with an argument + + An option group Header +C? option C with an optional argument" + +eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?` +------------ + + Author ------ -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> +Written by Linus Torvalds <torvalds@osdl.org> . +Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org> Documentation -------------- 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 16bfd7be22..659215ac72 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -75,6 +75,12 @@ The --cc option must be repeated for each user you want on the cc list. Make git-send-email less verbose. One line per email should be all that is output. +--identity:: + A configuration identity. When given, causes values in the + 'sendemail.<identity>' subsection to take precedence over + values in the 'sendemail' section. The default identity is + the value of 'sendemail.identity'. + --smtp-server:: If set, specifies the outgoing SMTP server to use (e.g. `smtp.example.com` or a raw IP address). Alternatively it can @@ -85,14 +91,29 @@ The --cc option must be repeated for each user you want on the cc list. `/usr/lib/sendmail` if such program is available, or `localhost` otherwise. +--smtp-server-port:: + Specifies a port different from the default port (SMTP + servers typically listen to smtp port 25 and ssmtp port + 465). + +--smtp-user, --smtp-pass:: + Username and password for SMTP-AUTH. Defaults are the values of + the configuration values 'sendemail.smtpuser' and + 'sendemail.smtppass', but see also 'sendemail.identity'. + If not set, authentication is not attempted. + +--smtp-ssl:: + If set, connects to the SMTP server using SSL. + Default is the value of the 'sendemail.smtpssl' configuration value; + if that is unspecified, does not use SSL. + --subject:: Specify the initial subject of the email thread. Only necessary if --compose is also set. If --compose 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. @@ -122,6 +143,13 @@ The --to option must be repeated for each user you want on the to list. CONFIGURATION ------------- +sendemail.identity:: + The default configuration identity. When specified, + 'sendemail.<identity>.<item>' will have higher precedence than + 'sendemail.<item>'. This is useful to declare multiple SMTP + identities and to hoist sensitive authentication information + out of the repository and into the global configuation file. + sendemail.aliasesfile:: To avoid typing long email addresses, point this to one or more email aliases files. You must also supply 'sendemail.aliasfiletype'. @@ -130,6 +158,9 @@ sendemail.aliasfiletype:: Format of the file(s) specified in sendemail.aliasesfile. Must be one of 'mutt', 'mailrc', 'pine', or 'gnus'. +sendemail.to:: + Email address (or alias) to always send to. + sendemail.cccmd:: Command to execute to generate per patch file specific "Cc:"s. @@ -141,7 +172,16 @@ sendemail.chainreplyto:: parameter. sendemail.smtpserver:: - Default smtp server to use. + Default SMTP server to use. + +sendemail.smtpuser:: + Default SMTP-AUTH username. + +sendemail.smtppass:: + Default SMTP-AUTH password. + +sendemail.smtpssl:: + Boolean value specifying the default to the '--smtp-ssl' parameter. Author ------ diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 3271e88183..2fa01d4a3c 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -8,7 +8,7 @@ git-send-pack - Push objects over git protocol to another repository SYNOPSIS -------- -'git-send-pack' [--all] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] +'git-send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] DESCRIPTION ----------- @@ -34,6 +34,9 @@ OPTIONS Instead of explicitly specifying which refs to update, update all heads that locally exist. +\--dry-run:: + Do everything except actually send the updates. + \--force:: Usually, the command refuses to update a remote ref that is not an ancestor of the local ref used to overwrite it. 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-stash.txt b/Documentation/git-stash.txt index 5723bb06f0..c0147b99a2 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -57,7 +57,7 @@ stash@{1}: On master: 9cc0589... Add git-stash show [<stash>]:: - Show the changes recorded in the stash as a diff between the the + Show the changes recorded in the stash as a diff between the stashed state and its original parent. When no `<stash>` is given, shows the latest one. By default, the command shows the diffstat, but it will accept any format known to `git-diff` (e.g., `git-stash show diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c48936fcd..335e973a6a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -21,6 +21,9 @@ add:: repository is cloned at the specified path, added to the changeset and registered in .gitmodules. If no path is specified, the path is deduced from the repository specification. + If the repository url begins with ./ or ../, it is stored as + given but resolved as a relative path from the main project's + url when cloning. status:: Show the status of the submodules. This will print the SHA-1 of the diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index e157c6ab50..918a9928b1 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -193,6 +193,12 @@ Any other arguments are passed directly to `git log' repository (that has been init-ed with git-svn). The -r<revision> option is required for this. +'info':: + Shows information about a file or directory similar to what + `svn info' provides. Does not currently support a -r/--revision + argument. Use the --url option to output only the value of the + 'URL:' field. + -- OPTIONS @@ -404,7 +410,7 @@ section because they affect the 'git-svn-id:' metadata line. BASIC EXAMPLES -------------- -Tracking and contributing to a the trunk of a Subversion-managed project: +Tracking and contributing to the trunk of a Subversion-managed project: ------------------------------------------------------------------------ # Clone a repo (like git clone): diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt deleted file mode 100644 index 71aad8b45b..0000000000 --- a/Documentation/git-svnimport.txt +++ /dev/null @@ -1,179 +0,0 @@ -git-svnimport(1) -================ -v0.1, July 2005 - -NAME ----- -git-svnimport - Import a SVN repository into git - - -SYNOPSIS --------- -[verse] -'git-svnimport' [ -o <branch-for-HEAD> ] [ -h ] [ -v ] [ -d | -D ] - [ -C <GIT_repository> ] [ -i ] [ -u ] [-l limit_rev] - [ -b branch_subdir ] [ -T trunk_subdir ] [ -t tag_subdir ] - [ -s start_chg ] [ -m ] [ -r ] [ -M regex ] - [ -I <ignorefile_name> ] [ -A <author_file> ] - [ -R <repack_each_revs>] [ -P <path_from_trunk> ] - <SVN_repository_URL> [ <path> ] - - -DESCRIPTION ------------ -Imports a SVN repository into git. It will either create a new -repository, or incrementally import into an existing one. - -SVN access is done by the SVN::Perl module. - -git-svnimport assumes that SVN repositories are organized into one -"trunk" directory where the main development happens, "branches/FOO" -directories for branches, and "/tags/FOO" directories for tags. -Other subdirectories are ignored. - -git-svnimport creates a file ".git/svn2git", which is required for -incremental SVN imports. - -OPTIONS -------- --C <target-dir>:: - The GIT repository to import to. If the directory doesn't - exist, it will be created. Default is the current directory. - --s <start_rev>:: - Start importing at this SVN change number. The default is 1. -+ -When importing incrementally, you might need to edit the .git/svn2git file. - --i:: - Import-only: don't perform a checkout after importing. This option - ensures the working directory and index remain untouched and will - not create them if they do not exist. - --T <trunk_subdir>:: - Name the SVN trunk. Default "trunk". - --t <tag_subdir>:: - Name the SVN subdirectory for tags. Default "tags". - --b <branch_subdir>:: - Name the SVN subdirectory for branches. Default "branches". - --o <branch-for-HEAD>:: - The 'trunk' branch from SVN is imported to the 'origin' branch within - the git repository. Use this option if you want to import into a - different branch. - --r:: - Prepend 'rX: ' to commit messages, where X is the imported - subversion revision. - --u:: - Replace underscores in tag names with periods. - --I <ignorefile_name>:: - Import the svn:ignore directory property to files with this - name in each directory. (The Subversion and GIT ignore - syntaxes are similar enough that using the Subversion patterns - directly with "-I .gitignore" will almost always just work.) - --A <author_file>:: - Read a file with lines on the form -+ ------- - username = User's Full Name <email@addr.es> - ------- -+ -and use "User's Full Name <email@addr.es>" as the GIT -author and committer for Subversion commits made by -"username". If encountering a commit made by a user not in the -list, abort. -+ -For convenience, this data is saved to $GIT_DIR/svn-authors -each time the -A option is provided, and read from that same -file each time git-svnimport is run with an existing GIT -repository without -A. - --m:: - Attempt to detect merges based on the commit message. This option - will enable default regexes that try to capture the name source - branch name from the commit message. - --M <regex>:: - Attempt to detect merges based on the commit message with a custom - regex. It can be used with -m to also see the default regexes. - You must escape forward slashes. - --l <max_rev>:: - Specify a maximum revision number to pull. -+ -Formerly, this option controlled how many revisions to pull, -due to SVN memory leaks. (These have been worked around.) - --R <repack_each_revs>:: - Specify how often git repository should be repacked. -+ -The default value is 1000. git-svnimport will do import in chunks of 1000 -revisions, after each chunk git repository will be repacked. To disable -this behavior specify some big value here which is mote than number of -revisions to import. - --P <path_from_trunk>:: - Partial import of the SVN tree. -+ -By default, the whole tree on the SVN trunk (/trunk) is imported. -'-P my/proj' will import starting only from '/trunk/my/proj'. -This option is useful when you want to import one project from a -svn repo which hosts multiple projects under the same trunk. - --v:: - Verbosity: let 'svnimport' report what it is doing. - --d:: - Use direct HTTP requests if possible. The "<path>" argument is used - only for retrieving the SVN logs; the path to the contents is - included in the SVN log. - --D:: - Use direct HTTP requests if possible. The "<path>" argument is used - for retrieving the logs, as well as for the contents. -+ -There's no safe way to automatically find out which of these options to -use, so you need to try both. Usually, the one that's wrong will die -with a 40x error pretty quickly. - -<SVN_repository_URL>:: - The URL of the SVN module you want to import. For local - repositories, use "file:///absolute/path". -+ -If you're using the "-d" or "-D" option, this is the URL of the SVN -repository itself; it usually ends in "/svn". - -<path>:: - The path to the module you want to check out. - --h:: - Print a short usage message and exit. - -OUTPUT ------- -If '-v' is specified, the script reports what it is doing. - -Otherwise, success is indicated the Unix way, i.e. by simply exiting with -a zero exit status. - -Author ------- -Written by Matthias Urlichs <smurf@smurf.noris.de>, with help from -various participants of the git-list <git@vger.kernel.org>. - -Based on a cvs2git script by the same author. - -Documentation --------------- -Documentation by Matthias Urlichs <smurf@smurf.noris.de>. - -GIT ---- -Part of the gitlink:git[7] suite 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/git-tag.txt b/Documentation/git-tag.txt index 990ae4f948..10d3e3fa95 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -112,7 +112,7 @@ You really want to call the new version "X" too, 'even though' others have already seen the old one. So just use "git tag -f" again, as if you hadn't already published the old one. -However, Git does *not* (and it should not)change tags behind +However, Git does *not* (and it should not) change tags behind users back. So if somebody already got the old tag, doing a "git pull" on your tree shouldn't just make them overwrite the old one. @@ -214,6 +214,27 @@ having tracking branches. Again, the heuristic to automatically follow such tags is a good thing. +On Backdating Tags +~~~~~~~~~~~~~~~~~~ + +If you have imported some changes from another VCS and would like +to add tags for major releases of your work, it is useful to be able +to specify the date to embed inside of the tag object. The data in +the tag object affects, for example, the ordering of tags in the +gitweb interface. + +To set the date used in future tag objects, set the environment +variable GIT_AUTHOR_DATE to one or more of the date and time. The +date and time can be specified in a number of ways; the most common +is "YYYY-MM-DD HH:MM". + +An example follows. + +------------ +$ GIT_AUTHOR_DATE="2006-10-02 10:31" git tag -s v1.0.1 +------------ + + Author ------ Written by Linus Torvalds <torvalds@osdl.org>, diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.txt index 10653ff898..a96403cb8c 100644 --- a/Documentation/git-tools.txt +++ b/Documentation/git-tools.txt @@ -22,6 +22,9 @@ Alternative/Augmentative Porcelains providing generally smoother user experience than the "raw" Core GIT itself and indeed many other version control systems. + Cogito is no longer maintained as most of its functionality + is now in core GIT. + - *pg* (http://www.spearce.org/category/projects/scm/pg/) @@ -33,7 +36,7 @@ Alternative/Augmentative Porcelains - *StGit* (http://www.procode.org/stgit/) Stacked GIT provides a quilt-like patch management functionality in the - GIT environment. You can easily manage your patches in the scope of GIT + GIT environment. You can easily manage your patches in the scope of GIT until they get merged upstream. diff --git a/Documentation/git.txt b/Documentation/git.txt index a7cd91acc1..546020100a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -46,7 +46,13 @@ Documentation for older releases are available here: * link:v1.5.3/git.html[documentation for release 1.5.3] * release notes for - link:RelNotes-1.5.3.1.txt[1.5.3.1]. + link:RelNotes-1.5.3.6.txt[1.5.3.6], + link:RelNotes-1.5.3.5.txt[1.5.3.5], + link:RelNotes-1.5.3.4.txt[1.5.3.4], + link:RelNotes-1.5.3.3.txt[1.5.3.3], + link:RelNotes-1.5.3.2.txt[1.5.3.2], + link:RelNotes-1.5.3.1.txt[1.5.3.1], + link:RelNotes-1.5.3.txt[1.5.3]. * release notes for link:RelNotes-1.5.2.5.txt[1.5.2.5], @@ -323,7 +329,7 @@ For a more complete list of ways to spell object names, see File/Directory Structure ------------------------ -Please see link:repository-layout.html[repository layout] document. +Please see the link:repository-layout.html[repository layout] document. Read link:hooks.html[hooks] for more details about each hook. @@ -333,7 +339,7 @@ Higher level SCMs may provide and manage additional information in the Terminology ----------- -Please see link:glossary.html[glossary] document. +Please see the link:glossary.html[glossary] document. Environment Variables diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index cf4ee2ebe5..19bd25f299 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -410,6 +410,23 @@ frotz unspecified ---------------------------------------------------------------- +Creating an archive +~~~~~~~~~~~~~~~~~~~ + +`export-subst` +^^^^^^^^^^^^^^ + +If the attribute `export-subst` is set for a file then git will expand +several placeholders when adding this file to an archive. The +expansion depends on the availability of a commit ID, i.e. if +gitlink:git-archive[1] has been given a tree instead of a commit or a +tag then no replacement will be done. The placeholders are the same +as those for the option `--pretty=format:` of gitlink:git-log[1], +except that they need to be wrapped like this: `$Format:PLACEHOLDERS$` +in the file. E.g. the string `$Format:%H$` will be replaced by the +commit hash. + + GIT --- Part of the gitlink:git[7] suite diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 3f7b1e42b5..fc1874424e 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -52,8 +52,8 @@ GIT Glossary [[def_cherry-picking]]cherry-picking:: In <<def_SCM,SCM>> jargon, "cherry pick" means to choose a subset of changes out of a series of changes (typically commits) and record them - as a new series of changes on top of different codebase. In GIT, this is - performed by "git cherry-pick" command to extract the change introduced + as a new series of changes on top of a different codebase. In GIT, this is + performed by the "git cherry-pick" command to extract the change introduced by an existing <<def_commit,commit>> and to record it based on the tip of the current <<def_branch,branch>> as a new commit. @@ -281,7 +281,7 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_pickaxe]]pickaxe:: The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore routines that help select changes that add or delete a given text - string. With the --pickaxe-all option, it can be used to view the full + string. With the `--pickaxe-all` option, it can be used to view the full <<def_changeset,changeset>> that introduced or removed, say, a particular line of text. See gitlink:git-diff[1]. @@ -301,8 +301,8 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_push]]push:: Pushing a <<def_branch,branch>> means to get the branch's <<def_head_ref,head ref>> from a remote <<def_repository,repository>>, - find out if it is an ancestor to the branch's local - head ref is a direct, and in that case, putting all + find out if it is a direct ancestor to the branch's local + head ref, and in that case, putting all objects, which are <<def_reachable,reachable>> from the local head ref, and which are missing from the remote repository, into the remote @@ -347,7 +347,7 @@ This commit is referred to as a "merge commit", or sometimes just a it as my origin branch head". And `git push $URL refs/heads/master:refs/heads/to-upstream` means "publish my master branch head as to-upstream branch at $URL". See also - gitlink:git-push[1] + gitlink:git-push[1]. [[def_repository]]repository:: A collection of <<def_ref,refs>> together with an diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index c39edc57c4..f110162b01 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -87,6 +87,33 @@ parameter, and is invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of `git-commit`. +post-checkout +----------- + +This hook is invoked when a `git-checkout` is run after having updated the +worktree. The hook is given three parameters: the ref of the previous HEAD, +the ref of the new HEAD (which may or may not have changed), and a flag +indicating whether the checkout was a branch checkout (changing branches, +flag=1) or a file checkout (retrieving a file from the index, flag=0). +This hook cannot affect the outcome of `git-checkout`. + +This hook can be used to perform repository validity checks, auto-display +differences from the previous HEAD if different, or set working dir metadata +properties. + +post-merge +----------- + +This hook is invoked by `git-merge`, which happens when a `git pull` +is done on a local repository. The hook takes a single parameter, a status +flag specifying whether or not the merge being done was a squash merge. +This hook cannot affect the outcome of `git-merge`. + +This hook can be used in conjunction with a corresponding pre-commit hook to +save and restore any form of metadata associated with the working tree +(eg: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl +for an example of how to do this. + [[pre-receive]] pre-receive ----------- 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/merge-options.txt b/Documentation/merge-options.txt index d64c259bb3..9f1fc82550 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -10,6 +10,10 @@ not autocommit, to give the user a chance to inspect and further tweak the merge result before committing. +--commit:: + Perform the merge and commit the result. This option can + be used to override --no-commit. + --squash:: Produce the working tree and index state as if a real merge happened, but do not actually make a commit or @@ -19,6 +23,19 @@ top of the current branch whose effect is the same as merging another branch (or more in case of an octopus). +--no-squash:: + Perform the merge and commit the result. This option can + be used to override --squash. + +--no-ff:: + Generate a merge commit even if the merge resolved as a + fast-forward. + +--ff:: + Do not generate a merge commit if the merge resolved as + a fast-forward, only update the branch pointer. This is + the default behavior of git-merge. + -s <strategy>, \--strategy=<strategy>:: Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. diff --git a/Documentation/urls.txt b/Documentation/urls.txt index e67f9140ab..4f667382ec 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -36,5 +36,11 @@ To sync with a local directory, you can use: - file:///path/to/repo.git/ =============================================================== +ifndef::git-clone[] They are mostly equivalent, except when cloning. See gitlink:git-clone[1] for details. +endif::git-clone[] + +ifdef::git-clone[] +They are equivalent, except the former implies --local option. +endif::git-clone[] diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index c027353337..3661879f1a 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: ------------------------------------------------- @@ -933,7 +933,7 @@ file such that it contained the given content either before or after the commit. You can find out with this: ------------------------------------------------- -$ git log --raw --abbrev=40 --pretty=oneline -- filename | +$ git log --raw --abbrev=40 --pretty=oneline | grep -B 1 `git hash-object filename` ------------------------------------------------- @@ -1374,7 +1374,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 @@ -1502,7 +1502,7 @@ Ensuring good performance ------------------------- On large repositories, git depends on compression to keep the history -information from taking up to much space on disk or in memory. +information from taking up too much space on disk or in memory. This compression is not performed automatically. Therefore you should occasionally run gitlink:git-gc[1]: @@ -1543,7 +1543,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f Dangling objects are not a problem. At worst they may take up a little extra disk space. They can sometimes provide a last-resort method for recovering lost work--see <<dangling-objects>> for details. However, if -you wish, you can remove them with gitlink:git-prune[1] or the --prune +you wish, you can remove them with gitlink:git-prune[1] or the `--prune` option to gitlink:git-gc[1]: ------------------------------------------------- @@ -1562,7 +1562,7 @@ Recovering lost changes Reflogs ^^^^^^^ -Say you modify a branch with gitlink:git-reset[1] --hard, and then +Say you modify a branch with `gitlink:git-reset[1] --hard`, and then realize that the branch was the only reference you had to that point in history. @@ -1574,9 +1574,9 @@ old history using, for example, $ 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, -not just with git log. Some other examples: +This lists the commits reachable from the previous version of the +"master" branch head. This syntax can be used with any git command +that accepts a commit, not just with git log. Some other examples: ------------------------------------------------- $ git show master@{2} # See where the branch pointed 2, @@ -1691,7 +1691,7 @@ $ git pull More generally, a branch that is created from a remote branch will pull by default from that branch. See the descriptions of the branch.<name>.remote and branch.<name>.merge options in -gitlink:git-config[1], and the discussion of the --track option in +gitlink:git-config[1], and the discussion of the `--track` option in gitlink:git-checkout[1], to learn how to control these defaults. In addition to saving you keystrokes, "git pull" also helps you by @@ -1789,7 +1789,7 @@ $ git clone /path/to/repository $ git pull /path/to/other/repository ------------------------------------------------- -or an ssh url: +or an ssh URL: ------------------------------------------------- $ git clone ssh://yourhost/~you/repository @@ -1850,7 +1850,7 @@ Exporting a git repository via the git protocol This is the preferred method. If someone else administers the server, they should tell you what -directory to put the repository in, and what git:// url it will appear +directory to put the repository in, and what git:// URL it will appear at. You can then skip to the section "<<pushing-changes-to-a-public-repository,Pushing changes to a public repository>>", below. @@ -1887,8 +1887,8 @@ $ chmod a+x hooks/post-update gitlink:git-update-server-info[1], and the documentation link:hooks.html[Hooks used by git].) -Advertise the url of proj.git. Anybody else should then be able to -clone or pull from that url, for example with a command line like: +Advertise the URL of proj.git. Anybody else should then be able to +clone or pull from that URL, for example with a command line like: ------------------------------------------------- $ git clone http://yourserver.com/~you/proj.git @@ -1927,7 +1927,7 @@ As with git-fetch, git-push will complain if this does not result in a <<fast-forwards,fast forward>>. Normally this is a sign of something wrong. However, if you are sure you know what you're doing, you may force git-push to perform the update anyway by -proceeding the branch name by a plus sign: +preceding the branch name by a plus sign: ------------------------------------------------- $ git push ssh://yourserver.com/~you/proj.git +master @@ -2047,7 +2047,7 @@ $ git branch --track test origin/master $ git branch --track release origin/master ------------------------------------------------- -These can be easily kept up to date using gitlink:git-pull[1] +These can be easily kept up to date using gitlink:git-pull[1]. ------------------------------------------------- $ git checkout test && git pull @@ -2139,7 +2139,7 @@ changes are in a specific branch, use: $ git log linux..branchname | git-shortlog ------------------------------------------------- -To see whether it has already been merged into the test or release branches +To see whether it has already been merged into the test or release branches, use: ------------------------------------------------- @@ -2152,12 +2152,12 @@ or $ git log release..branchname ------------------------------------------------- -(If this branch has not yet been merged you will see some log entries. +(If this branch has not yet been merged, you will see some log entries. If it has been merged, then there will be no output.) Once a patch completes the great cycle (moving from test to release, then pulled by Linus, and finally coming back into your local -"origin/master" branch) the branch for this change is no longer needed. +"origin/master" branch), the branch for this change is no longer needed. You detect this when the output from: ------------------------------------------------- @@ -2419,7 +2419,7 @@ $ git rebase --continue and git will continue applying the rest of the patches. -At any point you may use the --abort option to abort this process and +At any point you may use the `--abort` option to abort this process and return mywork to the state it had before you started the rebase: ------------------------------------------------- @@ -2486,9 +2486,9 @@ $ git checkout -b mywork-new origin $ gitk origin..mywork & ------------------------------------------------- -And browse through the list of patches in the mywork branch using gitk, +and browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using commit --amend. +cherry-pick, and possibly modifying them as you go using `commit --amend`. The gitlink:git-gui[1] command may also help as it allows you to individually select diff hunks for inclusion in the index (by right-clicking on the diff hunk and choosing "Stage Hunk for Commit"). @@ -2812,7 +2812,7 @@ others: - Git can quickly determine whether two objects are identical or not, just by comparing names. -- Since object names are computed the same way in ever repository, the +- Since object names are computed the same way in every repository, the same content stored in two repositories will always be stored under the same name. - Git can detect errors when it reads an object, by checking that the @@ -2829,7 +2829,7 @@ There are four different types of objects: "blob", "tree", "commit", and "blob" objects into a directory structure. In addition, a tree object can refer to other tree objects, thus creating a directory hierarchy. - A <<def_commit_object,"commit" object>> ties such directory hierarchies - together into a <<def_DAG,directed acyclic graph>> of revisions - each + together into a <<def_DAG,directed acyclic graph>> of revisions--each commit contains the object name of exactly one tree designating the directory hierarchy at the time of the commit. In addition, a commit refers to "parent" commit objects that describe the history of how we @@ -3102,7 +3102,7 @@ There are also other situations that cause dangling objects. For example, a "dangling blob" may arise because you did a "git add" of a file, but then, before you actually committed it and made it part of the bigger picture, you changed something else in that file and committed -that *updated* thing - the old state that you added originally ends up +that *updated* thing--the old state that you added originally ends up not being pointed to by any commit or tree, so it's now a dangling blob object. @@ -3117,7 +3117,7 @@ up pointing to them, so they end up "dangling" in your repository. Generally, dangling objects aren't anything to worry about. They can even be very useful: if you screw something up, the dangling objects can be how you recover your old tree (say, you did a rebase, and realized -that you really didn't want to - you can look at what dangling objects +that you really didn't want to--you can look at what dangling objects you have, and decide to reset your head to some old dangling state). For commits, you can just use: @@ -3161,10 +3161,10 @@ $ git prune ------------------------------------------------ and they'll be gone. But you should only run "git prune" on a quiescent -repository - it's kind of like doing a filesystem fsck recovery: you +repository--it's kind of like doing a filesystem fsck recovery: you don't want to do that while the filesystem is mounted. -(The same is true of "git-fsck" itself, btw - but since +(The same is true of "git-fsck" itself, btw, but since git-fsck never actually *changes* the repository, it just reports on what it found, git-fsck itself is never "dangerous" to run. Running it while somebody is actually changing the repository can cause @@ -3498,9 +3498,10 @@ The Workflow ------------ High-level operations such as gitlink:git-commit[1], -gitlink:git-checkout[1] and git-reset[1] work by moving data between the -working tree, the index, and the object database. Git provides -low-level operations which perform each of these steps individually. +gitlink:git-checkout[1] and gitlink:git-reset[1] work by moving data +between the working tree, the index, and the object database. Git +provides low-level operations which perform each of these steps +individually. Generally, all "git" operations work on the index file. Some operations work *purely* on the index file (showing the current state of the @@ -3555,7 +3556,7 @@ You write your current index file to a "tree" object with the program $ git write-tree ------------------------------------------------- -that doesn't come with any options - it will just write out the +that doesn't come with any options--it will just write out the current index into the set of tree objects that describe that state, and it will return the name of the resulting top-level tree. You can use that tree to re-generate the index at any time by going in the @@ -3566,7 +3567,7 @@ object database -> index ~~~~~~~~~~~~~~~~~~~~~~~~ You read a "tree" file from the object database, and use that to -populate (and overwrite - don't do this if your index contains any +populate (and overwrite--don't do this if your index contains any unsaved state that you might want to restore later!) your current index. Normal operation is just @@ -3614,7 +3615,7 @@ Tying it all together To commit a tree you have instantiated with "git-write-tree", you'd create a "commit" object that refers to that tree and the history -behind it - most notably the "parent" commits that preceded it in +behind it--most notably the "parent" commits that preceded it in history. Normally a "commit" has one parent: the previous state of the tree @@ -3757,7 +3758,7 @@ Once you know the three trees you are going to merge (the one "original" tree, aka the common tree, and the two "result" trees, aka the branches you want to merge), you do a "merge" read into the index. This will complain if it has to throw away your old index contents, so you should -make sure that you've committed those - in fact you would normally +make sure that you've committed those--in fact you would normally always do a merge against your last commit (which should thus match what you have in your current index anyway). @@ -3777,7 +3778,7 @@ Merging multiple trees, continued --------------------------------- Sadly, many merges aren't trivial. If there are files that have -been added.moved or removed, or if both branches have modified the +been added, moved or removed, or if both branches have modified the same file, you will be left with an index tree that contains "merge entries" in it. Such an index tree can 'NOT' be written out to a tree object, and you will have to resolve any such merge clashes using @@ -4029,7 +4030,7 @@ Two things are interesting here: - `get_sha1()` returns 0 on _success_. This might surprise some new Git hackers, but there is a long tradition in UNIX to return different - negative numbers in case of different errors -- and 0 on success. + negative numbers in case of different errors--and 0 on success. - the variable `sha1` in the function signature of `get_sha1()` is `unsigned char \*`, but is actually expected to be a pointer to `unsigned @@ -4134,7 +4135,7 @@ $ git branch new # create branch "new" starting at current HEAD $ git branch -d new # delete branch "new" ----------------------------------------------- -Instead of basing new branch on current HEAD (the default), use: +Instead of basing a new branch on current HEAD (the default), use: ----------------------------------------------- $ git branch new test # branch named "test" |