diff options
Diffstat (limited to 'Documentation')
31 files changed, 686 insertions, 327 deletions
diff --git a/Documentation/RelNotes-1.6.0.3.txt b/Documentation/RelNotes-1.6.0.3.txt new file mode 100644 index 0000000000..c0f037d6db --- /dev/null +++ b/Documentation/RelNotes-1.6.0.3.txt @@ -0,0 +1,120 @@ +GIT v1.6.0.3 Release Notes +========================== + +Fixes since v1.6.0.2 +-------------------- + +* "git archive --format=zip" did not honor core.autocrlf while + --format=tar did. + +* Continuing "git rebase -i" was very confused when the user left modified + files in the working tree while resolving conflicts. + +* Continuing "git rebase -i" was also very confused when the user left + some staged changes in the index after "edit". + +* "git rebase -i" now honors the pre-rebase hook, just like the + other rebase implementations "git rebase" and "git rebase -m". + +* "git rebase -i" incorrectly aborted when there is no commit to replay. + +* Behaviour of "git diff --quiet" was inconsistent with "diff --exit-code" + with the output redirected to /dev/null. + +* "git diff --no-index" on binary files no longer outputs a bogus + "diff --git" header line. + +* "git diff" hunk header patterns with multiple elements separated by LF + were not used correctly. + +* "git gc" when ejecting otherwise unreachable objects from packfiles into + loose form leaked memory. + +* Hunk headers in "git diff" default to using extended regular + expressions, fixing some of the internal patterns on non-GNU + platforms. + +* New config "diff.*.xfuncname" exposes extended regular expressions + for user specified hunk header patterns. + +* "git index-pack" was recently broken and mishandled objects added by + thin-pack completion processing under memory pressure. + +* "git stash apply sash@{1}" was fixed to error out. Prior versions + would have applied stash@{0} incorrectly. + +* "git stash apply" now offers a better suggestion on how to continue + if the working tree is currently dirty. + +* "git for-each-ref --format=%(subject)" fixed for commits with no + no newline in the message body. + +* "git remote" fixed to protect printf from user input. + +* "git remote show -v" now displays all URLs of a remote. + +* "git checkout -b branch" was confused when branch already existed. + +* "git checkout -q" once again suppresses the locally modified file list. + +* "git clone -q", "git fetch -q" asks remote side to not send + progress messages, actually making their output quiet. + +* Cross-directory renames are no longer used when creating packs. This + allows more graceful behavior on filesystems like sshfs. + +* Stale temporary files under $GIT_DIR/objects/pack are now cleaned up + automatically by "git prune". + +* "git merge" once again removes directories after the last file has + been removed from it during the merge. + +* "git merge" did not allocate enough memory for the structure itself when + enumerating the parents of the resulting commit. + +* "git blame -C -C" no longer segfaults while trying to pass blame if + it encounters a submodule reference. + +* "git rm" incorrectly claimed that you have local modifications when a + path was merely stat-dirty. + +* "git svn" fixed to display an error message when 'set-tree' failed, + instead of a Perl compile error. + +* "git submodule" fixed to handle checking out a different commit + than HEAD after initializing the submodule. + +* The "git commit" error message when there are still unmerged + files present was clarified to match "git write-tree". + +* "git init" was confused when core.bare or core.sharedRepository are set + in system or user global configuration file by mistake. When --bare or + --shared is given from the command line, these now override such + settings made outside the repositories. + +* Some segfaults due to uncaught NULL pointers were fixed in multiple + tools such as apply, reset, update-index. + +* Solaris builds now default to OLD_ICONV=1 to avoid compile warnings; + Solaris 8 does not define NEEDS_LIBICONV by default. + +* "Git.pm" tests relied on unnecessarily more recent version of Perl. + +* "gitweb" triggered undef warning on commits without log messages. + +* "gitweb" triggered undef warnings on missing trees. + +* "gitweb" now removes PATH_INFO from its URLs so users don't have + to manually set the URL in the gitweb configuration. + +* Bash completion removed support for legacy "git-fetch", "git-push" + and "git-pull" as these are no longer installed. Dashless form + ("git fetch") is still however supported. + +Many other documentation updates. + +-- +exec >/var/tmp/1 +O=v1.6.0.2-110-gf07c3c5 +echo O=$(git describe maint) +git shortlog --no-merges $O..maint diff --git a/Documentation/RelNotes-1.6.1.txt b/Documentation/RelNotes-1.6.1.txt index 609d4ca562..afd1150eaa 100644 --- a/Documentation/RelNotes-1.6.1.txt +++ b/Documentation/RelNotes-1.6.1.txt @@ -16,13 +16,16 @@ on. * gitk can call out to git-gui to view "git blame" output; git-gui in turn can run gitk from its blame view. -(portability) +* Various git-gui updates including updated translations. + +* Various gitweb updates from repo.or.cz installation. -* ... +(portability) -(documentation) +* A few test scripts used nonportable "grep" that did not work well on + some platforms, e.g. Solaris. -* ... +* Sample pre-auto-gc script has OS X support. (performance) @@ -32,27 +35,74 @@ on. * Most of the test scripts (but not the ones that try to run servers) can be run in parallel. +* Bash completion of refnames in a repository with massive number of + refs has been optimized. + +* Cygwin port uses native stat/lstat implementations when applicable, + which leads to improved performance. + +* "git push" pays attention to alternate repositories to avoid sending + unnecessary objects. + +* "git svn" can rebuild an out-of-date rev_map file. + (usability, bells and whistles) +* When you mistype a command name, git helpfully suggests what it guesses + you might have meant to say. help.autocorrect configuration can be set + to a non-zero value to accept the suggestion when git can uniquely + guess. + +* "git add -N path..." adds the named paths as an empty blob, so that + subsequent "git diff" will show a diff as if they are creation events. + +* "git apply" learned --include=paths option, similar to the existing + --exclude=paths option. + +* "git bisect" is careful about a user mistake and suggests testing of + merge base first when good is not a strict ancestor of bad. + * "git checkout --track origin/hack" used to be a syntax error. It now DWIMs to create a corresponding local branch "hack", i.e. acts as if you said "git checkout --track -b hack origin/hack". +* "git checkout --ours/--theirs" can be used to check out one side of a + conflicting merge during conflict resolution. + +* "git checkout -m" can be used to recreate the initial conflicted state + during conflict resolution. + * "git cherry-pick" can also utilize rerere for conflict resolution. * "git commit --author=$name" can look up author name from existing commits. +* output from "git commit" has been reworded in a more concise and yet + more informative way. + * "git count-objects" reports the on-disk footprint for packfiles and their corresponding idx files. * "git daemon" learned --max-connections=<count> option. -* "git diff" learned to mimick --suppress-blank-empty from GNU diff via a +* "git diff" learned to mimic --suppress-blank-empty from GNU diff via a configuration option. -* "git diff" learned to put more sensible hunk headers for Python and - HTML contents. +* "git diff" learned to put more sensible hunk headers for Python, + HTML and ObjC contents. + +* "git diff" learned to vary the a/ vs b/ prefix depending on what are + being compared, controlled by diff.mnemonicprefix configuration. + +* "git diff" learned --dirstat-by-file to count changed files, not number + of lines, when summarizing the global picture. + +* "git diff" hunk header pattern for ObjC has been added. + +* "git for-each-ref" learned "refname:short" token that gives an + unambiguously abbreviated refname. + +* "git grep" learned to accept -z similar to GNU grep. * "git help" learned to use GIT_MAN_VIEWER environment variable before using "man" program. @@ -68,6 +118,9 @@ on. * "git log" learned --simplify-merges, a milder variant of --full-history; "gitk --simplify-merges" is easier to view than with --full-history. +* "git log --pretty=format:" learned "%d" format element that inserts + names of tags that point at the commit. + * "git merge --squash" and "git merge --no-ff" into an unborn branch are noticed as user errors. @@ -83,12 +136,18 @@ on. * "git submodule sync" subcommands allows you to update the origin URL recorded in submodule directories from the toplevel .gitmodules file. +* "git svn branch" can create new branches on the other end. + (internal) * "git hash-object" learned to lie about the path being hashed, so that correct gitattributes processing can be done while hashing contents stored in a temporary file. +* various callers of git-merge-recursive avoid forking it as an external + process. + + Fixes since v1.6.0 ------------------ @@ -101,9 +160,14 @@ release, unless otherwise noted. is a path in it). * "git diff --stdin" used to take two trees on a line and compared them, - but we droppped support for such a use case long time ago. This has + but we dropped support for such a use case long time ago. This has been resurrected. +* Giving 3 or more tree-ish to "git diff" is supposed to show the combined + diff from second and subsequent trees to the first one. b75271d ("git + diff <tree>{3,}": do not reverse order of arguments, 2008-10-10) needs + to be cherry-picked to 'maint'. + * "git filter-branch" failed to rewrite a tag name with slashes in it. * "git push --tags --all $there" failed with generic usage message without @@ -115,6 +179,6 @@ release, unless otherwise noted. -- exec >/var/tmp/1 -O=v1.6.0.1-266-gaf9552f +O=v1.6.0.2-553-g58e0fa5 echo O=$(git describe master) git shortlog --no-merges $O..master ^maint diff --git a/Documentation/config.txt b/Documentation/config.txt index 922ac7b44d..29369d051b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -117,6 +117,17 @@ core.fileMode:: the working copy are ignored; useful on broken filesystems like FAT. See linkgit:git-update-index[1]. True by default. +core.ignoreCygwinFSTricks:: + This option is only used by Cygwin implementation of Git. If false, + the Cygwin stat() and lstat() functions are used. This may be useful + if your repository consists of a few separate directories joined in + one hierarchy using Cygwin mount. If true, Git uses native Win32 API + whenever it is possible and falls back to Cygwin functions only to + handle symbol links. The native mode is more than twice faster than + normal Cygwin l/stat() functions. True by default, unless core.filemode + is true, in which case ignoreCygwinFSTricks is ignored as Cygwin's + POSIX emulation is required to support core.filemode. + core.trustctime:: If false, the ctime differences between the index and the working copy are ignored; useful when the inode change time @@ -363,8 +374,17 @@ core.pager:: variable. Note that git sets the `LESS` environment variable to `FRSX` if it is unset when it runs the pager. One can change these settings by setting the - `LESS` variable to some other value or by giving the - `core.pager` option a value such as "`less -+FRSX`". + `LESS` variable to some other value. Alternately, + these settings can be overridden on a project or + global basis by setting the `core.pager` option. + Setting `core.pager` has no affect on the `LESS` + environment variable behaviour above, so if you want + to override git's default settings this way, you need + to be explicit. For example, to disable the S option + in a backward compatible manner, set `core.pager` + to "`less -+$LESS -FRX`". This will be passed to the + shell by git, which will translate the final command to + "`LESS=FRSX less -+FRSX -FRX`". core.whitespace:: A comma separated list of common whitespace problems to @@ -585,6 +605,22 @@ diff.external:: you want to use an external diff program only on a subset of your files, you might want to use linkgit:gitattributes[5] instead. +diff.mnemonicprefix:: + If set, 'git-diff' uses a prefix pair that is different from the + standard "a/" and "b/" depending on what is being compared. When + this configuration is in effect, reverse diff output also swaps + the order of the prefixes: +'git-diff';; + compares the (i)ndex and the (w)ork tree; +'git-diff HEAD';; + compares a (c)ommit and the (w)ork tree; +'git diff --cached';; + compares a (c)ommit and the (i)ndex; +'git-diff HEAD:file1 file2';; + compares an (o)bject and a (w)ork tree entity; +'git diff --no-index a b';; + compares two non-git things (1) and (2). + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the 'git-diff' option '-l'. @@ -606,10 +642,11 @@ fetch.unpackLimit:: `transfer.unpackLimit` is used instead. format.numbered:: - A boolean which can enable sequence numbers in patch subjects. - Setting this option to "auto" will enable it only if there is - more than one patch. See --numbered option in - linkgit:git-format-patch[1]. + A boolean which can enable or disable sequence numbers in patch + subjects. It defaults to "auto" which enables it only if there + is more than one patch. It can be enabled or disabled for all + messages by setting it to "true" or "false". See --numbered + option in linkgit:git-format-patch[1]. format.headers:: Additional email headers to include in a patch to be submitted @@ -902,6 +939,14 @@ man.<tool>.path:: Override the path for the given tool that may be used to display help in the 'man' format. See linkgit:git-help[1]. +merge.conflictstyle:: + Specify the style in which conflicted hunks are written out to + working tree files upon merge. The default is "merge", which + shows `<<<<<<<` conflict marker, change made by one side, + `=======` marker, change made by the other side, and then + `>>>>>>>` marker. An alternate style, "diff3", adds `|||||||` + marker and the original text before `=======` marker. + mergetool.<tool>.path:: Override the path for the given tool. This is useful in case your tool is not in the PATH. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 6e268326da..c62b45cdba 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -65,6 +65,9 @@ endif::git-format-patch[] can be set with "--dirstat=limit". Changes in a child directory is not counted for the parent directory, unless "--cumulative" is used. +--dirstat-by-file[=limit]:: + Same as --dirstat, but counts changed files instead of lines. + --summary:: Output a condensed summary of extended header information such as creations, renames and mode changes. @@ -134,7 +137,8 @@ endif::git-format-patch[] --diff-filter=[ACDMRTUXB*]:: Select only files that are Added (`A`), Copied (`C`), Deleted (`D`), Modified (`M`), Renamed (`R`), have their - type (mode) changed (`T`), are Unmerged (`U`), are + type (i.e. regular file, symlink, submodule, ...) changed (`T`), + are Unmerged (`U`), are Unknown (`X`), or have had their pairing Broken (`B`). Any combination of the filter characters may be used. When `*` (All-or-none) is added to the combination, all diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index feb51f124a..e726510ab1 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -14,7 +14,8 @@ SYNOPSIS [--allow-binary-replacement | --binary] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached] [--whitespace=<nowarn|warn|fix|error|error-all>] - [--exclude=PATH] [--directory=<root>] [--verbose] [<patch>...] + [--exclude=PATH] [--include=PATH] [--directory=<root>] + [--verbose] [<patch>...] DESCRIPTION ----------- @@ -137,6 +138,17 @@ discouraged. be useful when importing patchsets, where you want to exclude certain files or directories. +--include=<path-pattern>:: + Apply changes to files matching the given path pattern. This can + be useful when importing patchsets, where you want to include certain + files or directories. ++ +When --exclude and --include patterns are used, they are examined in the +order they appear on the command line, and the first match determines if a +patch to each path is used. A patch to a path that does not match any +include/exclude pattern is used by default if there is no include pattern +on the command line, and ignored if there is any include pattern. + --whitespace=<action>:: When applying a patch, detect a new or modified line that has whitespace errors. What are considered whitespace errors is diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 2b821f2a1d..256659a6b0 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -8,7 +8,9 @@ git-check-attr - Display gitattributes information. SYNOPSIS -------- +[verse] 'git check-attr' attr... [--] pathname... +'git check-attr' --stdin [-z] attr... < <list-of-paths> DESCRIPTION ----------- @@ -17,11 +19,68 @@ For every pathname, this command will list if each attr is 'unspecified', OPTIONS ------- +--stdin:: + Read file names from stdin instead of from the command-line. + +-z:: + Only meaningful with `--stdin`; paths are separated with + NUL character instead of LF. + \--:: Interpret all preceding arguments as attributes, and all following arguments as path names. If not supplied, only the first argument will be treated as an attribute. +OUTPUT +------ + +The output is of the form: +<path> COLON SP <attribute> COLON SP <info> LF + +Where <path> is the path of a file being queried, <attribute> is an attribute +being queried and <info> can be either: + +'unspecified';; when the attribute is not defined for the path. +'unset';; when the attribute is defined to false. +'set';; when the attribute is defined to true. +<value>;; when a value has been assigned to the attribute. + +EXAMPLES +-------- + +In the examples, the following '.gitattributes' file is used: +--------------- +*.java diff=java -crlf myAttr +NoMyAttr.java !myAttr +README caveat=unspecified +--------------- + +* Listing a single attribute: +--------------- +$ git check-attr diff org/example/MyClass.java +org/example/MyClass.java: diff: java +--------------- + +* Listing multiple attributes for a file: +--------------- +$ git check-attr crlf diff myAttr -- org/example/MyClass.java +org/example/MyClass.java: crlf: unset +org/example/MyClass.java: diff: java +org/example/MyClass.java: myAttr: set +--------------- + +* Listing attribute for multiple files: +--------------- +$ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java +org/example/MyClass.java: myAttr: set +org/example/NoMyAttr.java: myAttr: unspecified +--------------- + +* Not all values are equally unambiguous: +--------------- +$ git check-attr caveat README +README: caveat: unspecified +--------------- SEE ALSO -------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index be54a0299f..168333a588 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>] -'git checkout' [<tree-ish>] [--] <paths>... +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... DESCRIPTION ----------- @@ -27,14 +27,20 @@ the first namespace level. When <paths> are given, this command does *not* switch branches. It updates the named paths in the working tree from -the index file (i.e. it runs `git checkout-index -f -u`), or -from a named commit. In -this case, the `-f` and `-b` options are meaningless and giving +the index file, or from a named commit. In +this case, the `-b` options is meaningless and giving either of them results in an error. <tree-ish> argument can be used to specify a specific tree-ish (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. +The index may contain unmerged entries after a failed merge. By +default, if you try to check out such an entry from the index, the +checkout operation will fail and nothing will be checked out. +Using -f will ignore these unmerged entries. The contents from a +specific side of the merge can be checked out of the index by +using --ours or --theirs. With -m, changes made to the working tree +file can be discarded to recreate the original conflicted merge result. OPTIONS ------- @@ -42,8 +48,17 @@ OPTIONS Quiet, suppress feedback messages. -f:: - Proceed even if the index or the working tree differs - from HEAD. This is used to throw away local changes. + When switching branches, proceed even if the index or the + working tree differs from HEAD. This is used to throw away + local changes. ++ +When checking out paths from the index, do not fail upon unmerged +entries; instead, unmerged entries are ignored. + +--ours:: +--theirs:: + When checking out paths from the index, check out stage #2 + ('ours') or #3 ('theirs') for unmerged paths. -b:: Create a new branch named <new_branch> and start it at @@ -73,7 +88,7 @@ This would tell us to use "hack" as the local branch when branching off of "origin/hack" (or "remotes/origin/hack", or even "refs/remotes/origin/hack"). If the given name has no slash, or the above guessing results in an empty name, the guessing is aborted. You can -exlicitly give a name with '-b' in such a case. +explicitly give a name with '-b' in such a case. --no-track:: Ignore the branch.autosetupmerge configuration variable. @@ -84,7 +99,9 @@ exlicitly give a name with '-b' in such a case. based sha1 expressions such as "<branchname>@\{yesterday}". -m:: - If you have local modifications to one or more files that +--merge:: + When switching branches, + if you have local modifications to one or more files that are different between the current branch and the branch to which you are switching, the command refuses to switch branches in order to preserve your modifications in context. @@ -96,6 +113,16 @@ When a merge conflict happens, the index entries for conflicting paths are left unmerged, and you need to resolve the conflicts and mark the resolved paths with `git add` (or `git rm` if the merge should result in deletion of the path). ++ +When checking out paths from the index, this option lets you recreate +the conflicted merge in the specified paths. + +--conflict=<style>:: + The same as --merge option above, but changes the way the + conflicting hunks are presented, overriding the + merge.conflictstyle configuration variable. Possible values are + "merge" (default) and "diff3" (in addition to what is shown by + "merge" style, shows the original contents). <new_branch>:: Name for the new branch. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 0e14e732fd..95f08b9114 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -90,6 +90,11 @@ then the cloned repository will become corrupt. Operate quietly. This flag is also passed to the `rsync' command when given. +--verbose:: +-v:: + Display the progressbar, even in case the standard output is not + a terminal. + --no-checkout:: -n:: No checkout of HEAD is performed after the clone is complete. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index eeba58df2b..2e62165fa9 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -94,7 +94,8 @@ OPTIONS -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add Signed-off-by line by the commiter at the end of the commit + log message. -n:: --no-verify:: diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c4dbc2ae34..3d79f05995 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -18,6 +18,9 @@ shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit. +By default (without --all or --tags) `git describe` only shows +annotated tags. For more information about creating annotated tags +see the -a and -s options to linkgit:git-tag[1]. OPTIONS ------- @@ -26,11 +29,13 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. + found in `.git/refs/`. This option enables matching + any known branch, remote branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. + found in `.git/refs/tags`. This option enables matching + a lightweight (non-annotated) tag. --contains:: Instead of finding the tag that predates the commit, find diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index ebd7c5fbb3..5061d3e4e7 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -74,6 +74,7 @@ For all objects, the following names can be used: refname:: The name of the ref (the part after $GIT_DIR/). + For a non-ambiguous short name of the ref append `:short`. objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index adb4ea7b1b..ac36ce8717 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -58,8 +58,10 @@ output, unless the --stdout option is specified. If -o is specified, output files are created in <dir>. Otherwise they are created in the current working directory. -If -n is specified, instead of "[PATCH] Subject", the first line -is formatted as "[PATCH n/m] Subject". +By default, the subject of a single patch is "[PATCH] First Line" and +the subject when multiple patches are output is "[PATCH n/m] First +Line". To force 1/1 to be added for a single patch, use -n. To omit +patch numbers from the subject, use -N If given --thread, 'git-format-patch' will generate In-Reply-To and References headers to make the second and subsequent patch mails appear @@ -81,7 +83,7 @@ include::diff-options.txt[] -n:: --numbered:: - Name output in '[PATCH n/m]' format. + Name output in '[PATCH n/m]' format, even with a single patch. -N:: --no-numbered:: diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index fa4d133c1b..553da6cbb1 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -15,6 +15,7 @@ SYNOPSIS [-E | --extended-regexp] [-G | --basic-regexp] [-F | --fixed-strings] [-n] [-l | --files-with-matches] [-L | --files-without-match] + [-z | --null] [-c | --count] [--all-match] [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> @@ -94,6 +95,11 @@ OPTIONS For better compatibility with 'git-diff', --name-only is a synonym for --files-with-matches. +-z:: +--null:: + Output \0 instead of the character that normally follows a + file name. + -c:: --count:: Instead of showing every matched line, show the number of diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 0446bad7e5..93a2a227c4 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -8,7 +8,7 @@ git-log - Show commit logs SYNOPSIS -------- -'git log' <option>... +'git log' [<options>] [<since>..<until>] [[\--] <path>...] DESCRIPTION ----------- @@ -57,8 +57,11 @@ include::diff-options.txt[] Note that only message is considered, if also a diff is shown its size is not included. -<path>...:: - Show only commits that affect any of the specified paths. +[\--] <path>...:: + Show only commits that affect any of the specified paths. To + prevent confusion with options and branch names, paths may need + to be prefixed with "\-- " to separate them from options or + refnames. include::rev-list-options.txt[] diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 685e1fed58..1f30830d46 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -119,6 +119,71 @@ When there are conflicts, these things happen: same and the index entries for them stay as they were, i.e. matching `HEAD`. +HOW CONFLICTS ARE PRESENTED +--------------------------- + +During a merge, the working tree files are updated to reflect the result +of the merge. Among the changes made to the common ancestor's version, +non-overlapping ones (that is, you changed an area of the file while the +other side left that area intact, or vice versa) are incorporated in the +final result verbatim. When both sides made changes to the same area, +however, git cannot randomly pick one side over the other, and asks you to +resolve it by leaving what both sides did to that area. + +By default, git uses the same style as that is used by "merge" program +from the RCS suite to present such a conflicted hunk, like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +======= +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +The area a pair of conflicting changes happened is marked with markers +"`<<<<<<<`", "`=======`", and "`>>>>>>>`". The part before the "`=======`" +is typically your side, and the part after it is typically their side. + +The default format does not show what the original said in the conflicted +area. You cannot tell how many lines are deleted and replaced with the +Barbie's remark by your side. The only thing you can tell is that your +side wants to say it is hard and you'd prefer to go shopping, while the +other side wants to claim it is easy. + +An alternative style can be used by setting the "merge.conflictstyle" +configuration variable to "diff3". In "diff3" style, the above conflict +may look like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +||||||| +Conflict resolution is hard. +======= +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +In addition to the "`<<<<<<<`", "`=======`", and "`>>>>>>>`" markers, it uses +another "`|||||||`" marker that is followed by the original text. You can +tell that the original just stated a fact, and your side simply gave in to +that statement and gave up, while the other side tried to have a more +positive attitude. You can sometimes come up with a better resolution by +viewing the original. + + +HOW TO RESOLVE CONFLICTS +------------------------ + After seeing a conflict, you can do two things: * Decide not to merge. The only clean-up you need are to reset diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 54f1dab38d..da6055d4b8 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -8,7 +8,7 @@ git-prune - Prune all unreachable objects from the object database SYNOPSIS -------- -'git-prune' [-n] [--expire <expire>] [--] [<head>...] +'git-prune' [-n] [-v] [--expire <expire>] [--] [<head>...] DESCRIPTION ----------- @@ -34,6 +34,9 @@ OPTIONS Do not remove anything; just report what it would remove. +-v:: + Report all removed objects. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 45c96435fa..6150b1b959 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] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] - [--repo=all] [-f | --force] [-v | --verbose] +'git push' [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] + [--repo=<repository>] [-f | --force] [-v | --verbose] [<repository> <refspec>...] DESCRIPTION @@ -101,9 +101,23 @@ nor in any Push line of the corresponding remotes file---see below). This flag disables the check. This can cause the remote repository to lose commits; use it with care. ---repo=<repo>:: - When no repository is specified the command defaults to - "origin"; this overrides it. +--repo=<repository>:: + This option is only relevant if no <repository> argument is + passed in the invocation. In this case, 'git-push' derives the + remote name from the current branch: If it tracks a remote + branch, then that remote repository is pushed to. Otherwise, + the name "origin" is used. For this latter case, this option + can be used to override the name "origin". In other words, + the difference between these two commands ++ +-------------------------- +git push public #1 +git push --repo=public #2 +-------------------------- ++ +is that #1 always pushes to "public" whereas #2 pushes to "public" +only if the current branch does not track a remote branch. This is +useful if you write an alias or script around 'git-push'. --thin:: --no-thin:: diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 6f4b9b017f..7160fa1536 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -160,7 +160,10 @@ Here are the "carry forward" rules: 0 nothing nothing nothing (does not happen) 1 nothing nothing exists use M 2 nothing exists nothing remove path from index - 3 nothing exists exists use M + 3 nothing exists exists, use M if "initial checkout" + H == M keep index otherwise + exists fail + H != M clean I==H I==M ------------------ @@ -207,6 +210,12 @@ you picked it up via e-mail in a patch form), `git diff-index merge, but it would not show in `git diff-index --cached $M` output after two-tree merge. +Case #3 is slightly tricky and needs explanation. The result from this +rule logically should be to remove the path if the user staged the removal +of the path and then switching to a new branch. That however will prevent +the initial checkout from happening, so the rule is modified to use M (new +tree) only when the contents of the index is empty. Otherwise the removal +of the path is kept as long as $H and $M are the same. 3-Way Merge ~~~~~~~~~~~ diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 35cae59cf9..c8ad86a56f 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git rebase' [-i | --interactive] [-v | --verbose] [-m | --merge] - [-s <strategy> | --strategy=<strategy>] + [-s <strategy> | --strategy=<strategy>] [--no-verify] [-C<n>] [ --whitespace=<option>] [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>] 'git rebase' --continue | --skip | --abort @@ -92,7 +92,7 @@ branch to another, to pretend that you forked the topic branch from the latter branch, using `rebase --onto`. First let's assume your 'topic' is based on branch 'next'. -For example feature developed in 'topic' depends on some +For example, a feature developed in 'topic' depends on some functionality which is found in 'next'. ------------ @@ -103,9 +103,9 @@ functionality which is found in 'next'. o---o---o topic ------------ -We would want to make 'topic' forked from branch 'master', -for example because the functionality 'topic' branch depend on -got merged into more stable 'master' branch, like this: +We want to make 'topic' forked from branch 'master'; for example, +because the functionality on which 'topic' depends was merged into the +more stable 'master' branch. We want our tree to look like this: ------------ o---o---o---o---o master @@ -232,6 +232,9 @@ OPTIONS --verbose:: Display a diffstat of what changed upstream since the last rebase. +--no-verify:: + This option bypasses the pre-rebase hook. See also linkgit:githooks[5]. + -C<n>:: Ensure at least <n> lines of surrounding context match before and after each change. When fewer lines of surrounding @@ -250,8 +253,7 @@ OPTIONS -p:: --preserve-merges:: - Instead of ignoring merges, try to recreate them. This option - only works in interactive mode. + Instead of ignoring merges, try to recreate them. include::merge-strategies.txt[] diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 38ac60947b..bbe1485a97 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -60,7 +60,7 @@ OPTIONS linkgit:git-pack-objects[1]. -f:: - Pass the `--no-reuse-delta` option to 'git-pack-objects'. See + Pass the `--no-reuse-object` option to `git-pack-objects`, see linkgit:git-pack-objects[1]. -q:: diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index fd1de92e34..1c9cc28895 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -32,9 +32,9 @@ SYNOPSIS [ \--cherry-pick ] [ \--encoding[=<encoding>] ] [ \--(author|committer|grep)=<pattern> ] - [ \--regexp-ignore-case | \-i ] - [ \--extended-regexp | \-E ] - [ \--fixed-strings | \-F ] + [ \--regexp-ignore-case | -i ] + [ \--extended-regexp | -E ] + [ \--fixed-strings | -F ] [ \--date={local|relative|default|iso|rfc|short} ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 3c3e1b0e77..82f505686e 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -11,7 +11,6 @@ SYNOPSIS 'git send-email' [options] <file|directory> [... file|directory] - DESCRIPTION ----------- Takes the patches given on the command line and emails them out. @@ -20,12 +19,16 @@ The header of the email is configurable by command line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information. + OPTIONS ------- -The options available are: + +Composing +~~~~~~~~~ --bcc:: - Specify a "Bcc:" value for each email. + Specify a "Bcc:" value for each email. Default is the value of + 'sendemail.bcc'. + The --bcc option must be repeated for each user you want on the bcc list. @@ -34,22 +37,6 @@ The --bcc option must be repeated for each user you want on the bcc list. + The --cc option must be repeated for each user you want on the cc list. ---cc-cmd:: - Specify a command to execute once per patch file which - should generate patch file specific "Cc:" entries. - Output of this command must be single email address per line. - Default is the value of 'sendemail.cccmd' configuration value. - ---chain-reply-to:: ---no-chain-reply-to:: - If this is set, each email will be sent as a reply to the previous - email sent. If disabled with "--no-chain-reply-to", all emails after - the first will be sent as replies to the first email sent. When using - this, it is recommended that the first file given be an overview of the - entire patch series. - Default is the value of the 'sendemail.chainreplyto' configuration - value; if that is unspecified, default to --chain-reply-to. - --compose:: Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an introductory message for the patch series. @@ -66,22 +53,47 @@ The --cc option must be repeated for each user you want on the cc list. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---signed-off-by-cc:: ---no-signed-off-by-cc:: - If this is set, add emails found in Signed-off-by: or Cc: lines to the - cc list. - Default is the value of 'sendemail.signedoffcc' configuration value; - if that is unspecified, default to --signed-off-by-cc. +--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. + +--to:: + Specify the primary recipient of the emails generated. Generally, this + will be the upstream maintainer of the project involved. Default is the + value of the 'sendemail.to' configuration value; if that is unspecified, + this will be prompted for. ++ +The --to option must be repeated for each user you want on the to list. ---quiet:: - 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'. +Sending +~~~~~~~ + +--envelope-sender:: + Specify the envelope sender used to send the emails. + This is useful if your default address is not the address that is + subscribed to a list. If you use the sendmail binary, you must have + suitable privileges for the -f parameter. Default is the value of + the 'sendemail.envelopesender' configuration variable; if that is + unspecified, choosing the envelope sender is left to your MTA. + +--smtp-encryption:: + Specify the encryption to use, either 'ssl' or 'tls'. Any other + value reverts to plain SMTP. Default is the value of + 'sendemail.smtpencryption'. + +--smtp-pass:: + Password for SMTP-AUTH. The argument is optional: If no + argument is specified, then the empty string is used as + the password. Default is the value of 'sendemail.smtppass', + however '--smtp-pass' always overrides this value. ++ +Furthermore, passwords need not be specified in configuration files +or on the command line. If a username has been specified (with +'--smtp-user' or a 'sendemail.smtpuser'), but no password has been +specified (with '--smtp-pass' or 'sendemail.smtppass'), then the +user is prompted for a password while the input is masked for privacy. --smtp-server:: If set, specifies the outgoing SMTP server to use (e.g. @@ -96,61 +108,44 @@ The --cc option must be repeated for each user you want on the cc list. --smtp-server-port:: Specifies a port different from the default port (SMTP servers typically listen to smtp port 25 and ssmtp port - 465). + 465). This can be set with 'sendemail.smtpserverport'. + +--smtp-ssl:: + Legacy alias for '--smtp-encryption ssl'. --smtp-user:: - Username for SMTP-AUTH. In place of this option, the following - configuration variables can be specified: -+ --- - * sendemail.smtpuser - * sendemail.<identity>.smtpuser (see sendemail.identity). --- -+ -However, --smtp-user always overrides these variables. -+ -If a username is not specified (with --smtp-user or a -configuration variable), then authentication is not attempted. + Username for SMTP-AUTH. Default is the value of 'sendemail.smtpuser'; + if a username is not specified (with '--smtp-user' or 'sendemail.smtpuser'), + then authentication is not attempted. ---smtp-pass:: - Password for SMTP-AUTH. The argument is optional: If no - argument is specified, then the empty string is used as - the password. -+ -In place of this option, the following configuration variables -can be specified: -+ --- - * sendemail.smtppass - * sendemail.<identity>.smtppass (see sendemail.identity). --- -+ -However, --smtp-pass always overrides these variables. -+ -Furthermore, passwords need not be specified in configuration files -or on the command line. If a username has been specified (with ---smtp-user or a configuration variable), but no password has been -specified (with --smtp-pass or a configuration variable), then the -user is prompted for a password while the input is masked for privacy. ---smtp-encryption:: - Specify the encryption to use, either 'ssl' or 'tls'. Any other - value reverts to plain SMTP. Default is the value of - 'sendemail.smtpencryption'. +Automating +~~~~~~~~~~ ---smtp-ssl:: - Legacy alias for '--smtp-encryption=ssl'. +--cc-cmd:: + Specify a command to execute once per patch file which + should generate patch file specific "Cc:" entries. + Output of this command must be single email address per line. + Default is the value of 'sendemail.cccmd' configuration value. ---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. +--[no-]chain-reply-to:: + If this is set, each email will be sent as a reply to the previous + email sent. If disabled with "--no-chain-reply-to", all emails after + the first will be sent as replies to the first email sent. When using + this, it is recommended that the first file given be an overview of the + entire patch series. Default is the value of the 'sendemail.chainreplyto' + configuration value; if that is unspecified, default to --chain-reply-to. + +--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'. ---suppress-from:: ---no-suppress-from:: - 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. +--[no-]signed-off-by-cc:: + If this is set, add emails found in Signed-off-by: or Cc: lines to the + cc list. Default is the value of 'sendemail.signedoffbycc' configuration + value; if that is unspecified, default to --signed-off-by-cc. --suppress-cc:: Specify an additional category of recipients to suppress the @@ -163,44 +158,43 @@ user is prompted for a password while the input is masked for privacy. if that is unspecified, default to 'self' if --suppress-from is specified, as well as 'sob' if --no-signed-off-cc is specified. ---thread:: ---no-thread:: +--[no-]suppress-from:: + 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. + +--[no-]thread:: If this is set, the In-Reply-To header will be set on each email sent. If disabled with "--no-thread", no emails will have the In-Reply-To - header set. - Default is the value of the 'sendemail.thread' configuration value; - if that is unspecified, default to --thread. + header set. Default is the value of the 'sendemail.thread' configuration + value; if that is unspecified, default to --thread. + + +Administering +~~~~~~~~~~~~~ --dry-run:: Do everything except actually send the emails. ---envelope-sender:: - Specify the envelope sender used to send the emails. - This is useful if your default address is not the address that is - subscribed to a list. If you use the sendmail binary, you must have - suitable privileges for the -f parameter. - Default is the value of the 'sendemail.envelopesender' configuration - variable; if that is unspecified, choosing the envelope sender is left - to your MTA. +--quiet:: + Make git-send-email less verbose. One line per email should be + all that is output. ---to:: - Specify the primary recipient of the emails generated. - Generally, this will be the upstream maintainer of the - project involved. - Default is the value of the 'sendemail.to' configuration value; - if that is unspecified, this will be prompted for. +--[no-]validate:: + Perform sanity checks on patches. + Currently, validation means the following: + -The --to option must be repeated for each user you want on the to list. +-- + * Warn of patches that contain lines longer than 998 characters; this + is due to SMTP limits as described by http://www.ietf.org/rfc/rfc2821.txt. +-- ++ +Default is the value of 'sendemail.validate'; if this is not set, +default to '--validate'. 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 configuration file. sendemail.aliasesfile:: To avoid typing long email addresses, point this to one or more @@ -210,38 +204,6 @@ 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. - -sendemail.bcc:: - Email address (or alias) to always bcc. - -sendemail.chainreplyto:: - Boolean value specifying the default to the '--chain_reply_to' - parameter. - -sendemail.smtpserver:: - Default SMTP server to use. - -sendemail.smtpserverport:: - Default SMTP server port to use. - -sendemail.smtpuser:: - Default SMTP-AUTH username. - -sendemail.smtppass:: - Default SMTP-AUTH password. - -sendemail.smtpencryption:: - Default encryption method. Use 'ssl' for SSL (and specify an - appropriate port), or 'tls' for TLS. Takes precedence over - 'smtpssl' if both are specified. - -sendemail.smtpssl:: - Legacy boolean that sets 'smtpencryption=ssl' if enabled. Author ------ @@ -250,10 +212,12 @@ Written by Ryan Anderson <ryan@michonline.com> git-send-email is originally based upon send_lots_of_email.pl by Greg Kroah-Hartman. + Documentation -------------- Documentation by Ryan Anderson + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 1e644ca6dc..84c8f3cde0 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -149,6 +149,22 @@ and have no uncommitted changes. is very strongly discouraged. -- +'branch':: + Create a branch in the SVN repository. + +-m;; +--message;; + Allows to specify the commit message. + +-t;; +--tag;; + Create a tag by using the tags_subdir instead of the branches_subdir + specified during git svn init. + +'tag':: + Create a tag in the SVN repository. This is a shorthand for + 'branch -t'. + 'log':: This should make it easy to look up svn log messages when svn users refer to -r/--revision numbers. @@ -372,7 +388,8 @@ Passed directly to 'git-rebase' when using 'dcommit' if a -n:: --dry-run:: -This can be used with the 'dcommit' and 'rebase' commands. +This can be used with the 'dcommit', 'rebase', 'branch' and 'tag' +commands. For 'dcommit', print out the series of git arguments that would show which diffs would be committed to SVN. @@ -381,6 +398,9 @@ For 'rebase', display the local branch associated with the upstream svn repository associated with the current branch and the URL of svn repository that will be fetched from. +For 'branch' and 'tag', display the urls that will be used for copying when +creating the branch or tag. + -- ADVANCED OPTIONS @@ -473,7 +493,7 @@ Tracking and contributing to the trunk of a Subversion-managed project: ------------------------------------------------------------------------ # Clone a repo (like git clone): - git svn clone http://svn.foo.org/project/trunk + git svn clone http://svn.example.com/project/trunk # Enter the newly cloned directory: cd trunk # You should be on master branch, double-check with git-branch @@ -495,9 +515,11 @@ Tracking and contributing to an entire Subversion-managed project ------------------------------------------------------------------------ # Clone a repo (like git clone): - git svn clone http://svn.foo.org/project -T trunk -b branches -t tags + git svn clone http://svn.example.com/project -T trunk -b branches -t tags # View all branches and tags you have cloned: git branch -r +# Create a new branch in SVN + git svn branch waldo # Reset your master to trunk (or any other branch, replacing 'trunk' # with the appropriate name): git reset --hard remotes/trunk @@ -514,7 +536,7 @@ have each person clone that repository with 'git-clone': ------------------------------------------------------------------------ # Do the initial import on a server - ssh server "cd /pub && git svn clone http://svn.foo.org/project + ssh server "cd /pub && git svn clone http://svn.example.com/project # Clone locally - make sure the refs/remotes/ space matches the server mkdir project cd project @@ -523,7 +545,7 @@ have each person clone that repository with 'git-clone': git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' git fetch # Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) - git svn init http://svn.foo.org/project + git svn init http://svn.example.com/project # Pull the latest changes from Subversion git svn rebase ------------------------------------------------------------------------ diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 7f7a45b2ea..278cf73527 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -26,6 +26,7 @@ The following browsers (or commands) are currently supported: * lynx * dillo * open (this is the default under Mac OS X GUI) +* start (this is the default under MinGW) Custom commands may also be specified. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 6f3551dc82..26945593cb 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -270,31 +270,31 @@ See linkgit:git[1] for details. Defining a custom hunk-header ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Each group of changes (called "hunk") in the textual diff output +Each group of changes (called a "hunk") in the textual diff output is prefixed with a line of the form: @@ -k,l +n,m @@ TEXT -The text is called 'hunk header', and by default a line that -begins with an alphabet, an underscore or a dollar sign is used, -which matches what GNU 'diff -p' output uses. This default -selection however is not suited for some contents, and you can -use customized pattern to make a selection. +This is called a 'hunk header'. The "TEXT" portion is by default a line +that begins with an alphabet, an underscore or a dollar sign; this +matches what GNU 'diff -p' output uses. This default selection however +is not suited for some contents, and you can use a customized pattern +to make a selection. -First in .gitattributes, you would assign the `diff` attribute +First, in .gitattributes, you would assign the `diff` attribute for paths. ------------------------ *.tex diff=tex ------------------------ -Then, you would define "diff.tex.funcname" configuration to +Then, you would define a "diff.tex.xfuncname" configuration to specify a regular expression that matches a line that you would -want to appear as the hunk header, like this: +want to appear as the hunk header "TEXT", like this: ------------------------ [diff "tex"] - funcname = "^\\(\\\\\\(sub\\)*section{.*\\)$" + xfuncname = "^(\\\\(sub)*section\\{.*)$" ------------------------ Note. A single level of backslashes are eaten by the @@ -315,6 +315,8 @@ patterns are available: - `java` suitable for source code in the Java language. +- `objc` suitable for source code in the Objective-C language. + - `pascal` suitable for source code in the Pascal/Delphi language. - `php` suitable for source code in the PHP language. diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 2bdbc3d4f6..e8041bc08f 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -36,11 +36,25 @@ files: - 'git-diff-tree' compares contents of two "tree" objects; -In all of these cases, the commands themselves compare -corresponding paths in the two sets of files. The result of -comparison is passed from these commands to what is internally -called "diffcore", in a format similar to what is output when -the -p option is not used. E.g. +In all of these cases, the commands themselves first optionally limit +the two sets of files by any pathspecs given on their command-lines, +and compare corresponding paths in the two resulting sets of files. + +The pathspecs are used to limit the world diff operates in. They remove +the filepairs outside the specified sets of pathnames. E.g. If the +input set of filepairs included: + +------------------------------------------------ +:100644 100644 bcd1234... 0123456... M junkfile +------------------------------------------------ + +but the command invocation was `git diff-files myfile`, then the +junkfile entry would be removed from the list because only "myfile" +is under consideration. + +The result of comparison is passed from these commands to what is +internally called "diffcore", in a format similar to what is output +when the -p option is not used. E.g. ------------------------------------------------ in-place edit :100644 100644 bcd1234... 0123456... M file0 @@ -52,9 +66,8 @@ unmerged :000000 000000 0000000... 0000000... U file6 The diffcore mechanism is fed a list of such comparison results (each of which is called "filepair", although at this point each of them talks about a single file), and transforms such a list -into another list. There are currently 6 such transformations: +into another list. There are currently 5 such transformations: -- diffcore-pathspec - diffcore-break - diffcore-rename - diffcore-merge-broken @@ -62,38 +75,14 @@ into another list. There are currently 6 such transformations: - diffcore-order These are applied in sequence. The set of filepairs 'git-diff-{asterisk}' -commands find are used as the input to diffcore-pathspec, and -the output from diffcore-pathspec is used as the input to the +commands find are used as the input to diffcore-break, and +the output from diffcore-break is used as the input to the next transformation. The final result is then passed to the output routine and generates either diff-raw format (see Output format sections of the manual for 'git-diff-{asterisk}' commands) or diff-patch format. -diffcore-pathspec: For Ignoring Files Outside Our Consideration ---------------------------------------------------------------- - -The first transformation in the chain is diffcore-pathspec, and -is controlled by giving the pathname parameters to the -'git-diff-{asterisk}' commands on the command line. The pathspec is used -to limit the world diff operates in. It removes the filepairs -outside the specified set of pathnames. E.g. If the input set -of filepairs included: - ------------------------------------------------- -:100644 100644 bcd1234... 0123456... M junkfile ------------------------------------------------- - -but the command invocation was `git diff-files myfile`, then the -junkfile entry would be removed from the list because only "myfile" -is under consideration. - -Implementation note. For performance reasons, 'git-diff-tree' -uses the pathname parameters on the command line to cull set of -filepairs it feeds the diffcore mechanism itself, and does not -use diffcore-pathspec, but the end result is the same. - - diffcore-break: For Splitting Up "Complete Rewrites" ---------------------------------------------------- diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 046a2a7fe7..5faaaa5fed 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -87,12 +87,12 @@ default log message, and before the editor is started. It takes one to three parameters. The first is the name of the file that the commit log message. The second is the source of the commit -message, and can be: `message` (if a `\-m` or `\-F` option was -given); `template` (if a `\-t` option was given or the +message, and can be: `message` (if a `-m` or `-F` option was +given); `template` (if a `-t` option was given or the configuration option `commit.template` is set); `merge` (if the commit is a merge or a `.git/MERGE_MSG` file exists); `squash` (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by -a commit SHA1 (if a `\-c`, `\-C` or `\--amend` option was given). +a commit SHA1 (if a `-c`, `-C` or `\--amend` option was given). If the exit status is non-zero, 'git-commit' will abort. @@ -130,6 +130,13 @@ parameter, and is invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of 'git-commit'. +pre-rebase +---------- + +This hook is called by 'git-rebase' and can be used to prevent a branch +from getting rebased. + + post-checkout ----------- diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index 660904686c..bab0f34b45 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -32,22 +32,27 @@ Initialized empty Git repository in .git/ $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" -Created initial commit 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 +[master (root-commit)] created 54196cc: "initial commit" + 1 files changed, 1 insertions(+), 0 deletions(-) create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" -Created commit c4d59f390b9cfd4318117afde11d601c1085f241 +[master] created c4d59f3: "add emphasis" + 1 files changed, 1 insertions(+), 1 deletions(-) ------------------------------------------------ -What are the 40 digits of hex that git responded to the commit with? +What are the 7 digits of hex that git responded to the commit with? We saw in part one of the tutorial that commits have names like this. It turns out that every object in the git history is stored under -such a 40-digit hex name. That name is the SHA1 hash of the object's +a 40-digit hex name. That name is the SHA1 hash of the object's contents; among other things, this ensures that git will never store the same data twice (since identical data is given an identical SHA1 name), and that the contents of a git object will never change (since -that would change the object's name as well). +that would change the object's name as well). The 7 char hex strings +here are simply the abbreviation of such 40 character long strings. +Abbreviations can be used everywhere where the 40 character strings +can be used, so long as they are unambiguous. It is expected that the content of the commit object you created while following the example above generates a different SHA1 hash than diff --git a/Documentation/howto/rebase-and-edit.txt b/Documentation/howto/rebase-and-edit.txt deleted file mode 100644 index 554909fe08..0000000000 --- a/Documentation/howto/rebase-and-edit.txt +++ /dev/null @@ -1,79 +0,0 @@ -Date: Sat, 13 Aug 2005 22:16:02 -0700 (PDT) -From: Linus Torvalds <torvalds@osdl.org> -To: Steve French <smfrench@austin.rr.com> -cc: git@vger.kernel.org -Subject: Re: sending changesets from the middle of a git tree -Abstract: In this article, Linus demonstrates how a broken commit - in a sequence of commits can be removed by rewinding the head and - reapplying selected changes. - -On Sat, 13 Aug 2005, Linus Torvalds wrote: - -> That's correct. Same things apply: you can move a patch over, and create a -> new one with a modified comment, but basically the _old_ commit will be -> immutable. - -Let me clarify. - -You can entirely _drop_ old branches, so commits may be immutable, but -nothing forces you to keep them. Of course, when you drop a commit, you'll -always end up dropping all the commits that depended on it, and if you -actually got somebody else to pull that commit you can't drop it from -_their_ repository, but undoing things is not impossible. - -For example, let's say that you've made a mess of things: you've committed -three commits "old->a->b->c", and you notice that "a" was broken, but you -want to save "b" and "c". What you can do is - - # Create a branch "broken" that is the current code - # for reference - git branch broken - - # Reset the main branch to three parents back: this - # effectively undoes the three top commits - git reset HEAD^^^ - git checkout -f - - # Check the result visually to make sure you know what's - # going on - gitk --all - - # Re-apply the two top ones from "broken" - # - # First "parent of broken" (aka b): - git-diff-tree -p broken^ | git-apply --index - git commit --reedit=broken^ - - # Then "top of broken" (aka c): - git-diff-tree -p broken | git-apply --index - git commit --reedit=broken - -and you've now re-applied (and possibly edited the comments) the two -commits b/c, and commit "a" is basically gone (it still exists in the -"broken" branch, of course). - -Finally, check out the end result again: - - # Look at the new commit history - gitk --all - -to see that everything looks sensible. - -And then, you can just remove the broken branch if you decide you really -don't want it: - - # remove 'broken' branch - git branch -d broken - - # Prune old objects if you're really really sure - git prune - -And yeah, I'm sure there are other ways of doing this. And as usual, the -above is totally untested, and I just wrote it down in this email, so if -I've done something wrong, you'll have to figure it out on your own ;) - - Linus -- -To unsubscribe from this list: send the line "unsubscribe git" in -the body of a message to majordomo@vger.kernel.org -More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 388d4925e6..f18d33e00b 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -116,6 +116,7 @@ The placeholders are: - '%cr': committer date, relative - '%ct': committer date, UNIX timestamp - '%ci': committer date, ISO 8601 format +- '%d': ref names, like the --decorate option of linkgit:git-log[1] - '%e': encoding - '%s': subject - '%b': body diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 75aa5d4923..82e9e831b6 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -30,7 +30,7 @@ Functions start_command() followed by finish_command(). Takes a pointer to a `struct child_process` that specifies the details. -`run_command_v_opt`, `run_command_v_opt_cd`, `run_command_v_opt_cd_env`:: +`run_command_v_opt`, `run_command_v_opt_cd_env`:: Convenience functions that encapsulate a sequence of start_command() followed by finish_command(). The argument argv |