diff options
Diffstat (limited to 'Documentation')
42 files changed, 1424 insertions, 314 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 62269e39c4..c34c1cae20 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -6,7 +6,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ gitrepository-layout.txt MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \ - gitdiffcore.txt + gitdiffcore.txt gitworkflows.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) @@ -44,6 +44,7 @@ MANPAGE_XSL = callouts.xsl INSTALL?=install RM ?= rm -f DOC_REF = origin/man +HTML_REF = origin/html infodir?=$(prefix)/share/info MAKEINFO=makeinfo @@ -86,7 +87,9 @@ man7: $(DOC_MAN7) info: git.info gitman.info -install: man +install: install-man + +install-man: man $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir) $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir) $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir) @@ -219,7 +222,12 @@ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt install-webdoc : html sh ./install-webdoc.sh $(WEBDOC_DEST) -quick-install: +quick-install: quick-install-man + +quick-install-man: sh ./install-doc-quick.sh $(DOC_REF) $(DESTDIR)$(mandir) +quick-install-html: + sh ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir) + .PHONY: .FORCE-GIT-VERSION-FILE diff --git a/Documentation/RelNotes-1.6.1.txt b/Documentation/RelNotes-1.6.1.txt new file mode 100644 index 0000000000..d0e30e95d4 --- /dev/null +++ b/Documentation/RelNotes-1.6.1.txt @@ -0,0 +1,227 @@ +GIT v1.6.1 Release Notes +======================== + +Updates since v1.6.0 +-------------------- + +When some commands (e.g. "git log", "git diff") spawn pager internally, we +used to make the pager the parent process of the git command that produces +output. This meant that the exit status of the whole thing comes from the +pager, not the underlying git command. We swapped the order of the +processes around and you will see the exit code from the command from now +on. + +(subsystems) + +* gitk can call out to git-gui to view "git blame" output; git-gui in turn + can run gitk from its blame view. + +* Various git-gui updates including updated translations. + +* Various gitweb updates from repo.or.cz installation. + +(portability) + +* 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) + +* The underlying diff machinery to produce textual output has been + optimized, which would result in faster "git blame" processing. + +* 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 blame" re-encodes the commit metainfo to UTF-8 from i18n.commitEncoding + by default. + +* "git check-attr --stdin" can check attributes for multiple paths. + +* "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 clone" learned to be verbose with -v + +* "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 daemon" exports REMOTE_ADDR to record client address, so that + spawned programs can act differently on it. + +* "git describe --tags" favours closer lightweight tags than farther + annotated tags now. + +* "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, + 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. + +* a "textconv" filter that makes binary files textual form for human + consumption can be specified as an attribute for paths; "git diff" + learnt to make use of it. + +* "git for-each-ref" learned "refname:short" token that gives an + unambiguously abbreviated refname. + +* Auto-numbering of the subject lines is the default for "git + format-patch" now. + +* "git grep" learned to accept -z similar to GNU grep. + +* "git help" learned to use GIT_MAN_VIEWER environment variable before + using "man" program. + +* "git imap-send" can optionally talk SSL. + +* "git index-pack" is more careful against disk corruption while + completing a thin pack. + +* "git log --check" and "git log --exit-code" passes their underlying diff + status with their exit status code. + +* "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. + +* "git merge -s $strategy" can use a custom built strategy if you have a + command "git-merge-$strategy" on your $PATH. + +* "git push" can be told to reject deletion of refs with receive.denyDeletes + configuration. + +* "git rebase" honours pre-rebase hook; use --no-verify to bypass it. + +* "git rebase -p" uses interactive rebase machinery now to preserve the merges. + +* "git reflog expire branch" can be used in place of "git reflog expire + refs/heads/branch". + +* "git remote show $remote" lists remote branches one-per-line now. + +* when giving up resolving a conflicted merge, "git reset --hard" failed + to remove new paths from the working tree. [cherry-pick to 'maint'?] + +* "git submodule foreach" subcommand allows you to iterate over checked + out submodules. + +* "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. + +* "gitweb" can use more saner PATH_INFO based URL. + +(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. + +* Git class defined in "Git.pm" can be subclasses a bit more easily. + +* We used to link GNU regex library as a compatibility layer for some + platforms, but it turns out it is not necessary on most of them. + +* Some path handling routines used fixed number of buffers used alternately + but depending on the call depth, this arrangement led to hard to track + bugs. This issue is being addressed. + + +Fixes since v1.6.0 +------------------ + +All of the fixes in v1.6.0.X maintenance series are included in this +release, unless otherwise noted. + +* "git add" and "git update-index" incorrectly allowed adding S/F when S + is a tracked symlink that points at a directory D that has a path F in + it (we still need to fix a similar nonsense when S is a submodule and F + is a path in it). + +* "git diff --stdin" used to take two trees on a line and compared them, + 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 + telling saying these two options are incompatible. + +* "git log --author/--committer" match used to potentially match the + timestamp part, exposing internal implementation detail. Also these did + not work with --fixed-strings match at all. + +-- +exec >/var/tmp/1 +O=v1.6.0.3-639-ga1a846a +echo O=$(git describe master) +git shortlog --no-merges $O..master ^maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c59edfa6a9..f0295c60f5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -71,7 +71,7 @@ run git diff --check on your changes before you commit. (1a) Try to be nice to older C compilers -We try to support wide range of C compilers to compile +We try to support a wide range of C compilers to compile git with. That means that you should not use C99 initializers, even if a lot of compilers grok it. diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 5428111d73..1ab1b96cf9 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -49,6 +49,13 @@ of lines before or after the line given by <start>. Show the result incrementally in a format designed for machine consumption. +--encoding=<encoding>:: + Specifies the encoding used to output author names + and commit summaries. Setting it to `none` makes blame + output unconverted data. For more information see the + discussion about encoding in the linkgit:git-log[1] + manual page. + --contents <file>:: When <rev> is not specified, the command annotates the changes starting backwards from the working tree copy. diff --git a/Documentation/config.txt b/Documentation/config.txt index 87b028fbc1..965ed746da 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 @@ -581,6 +592,10 @@ diff.autorefreshindex:: affects only 'git-diff' Porcelain, and not lower level 'diff' commands, such as 'git-diff-files'. +diff.suppress-blank-empty:: + A boolean to inhibit the standard behavior of printing a space + before each empty output line. Defaults to false. + diff.external:: If this config variable is set, diff generation is not performed using the internal diff machinery, but using the @@ -590,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'. @@ -611,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 @@ -795,6 +827,15 @@ help.format:: Values 'man', 'info', 'web' and 'html' are supported. 'man' is the default. 'web' and 'html' are the same. +help.autocorrect:: + Automatically correct and execute mistyped commands after + waiting for the given number of deciseconds (0.1 sec). If more + than one command can be deduced from the entered text, nothing + will be executed. If the value of this option is negative, + the corrected command will be executed immediately. If the + value is 0 - the command will be just shown but not executed. + This is the default. + http.proxy:: Override the HTTP proxy, normally configured using the 'http_proxy' environment variable (see linkgit:curl[1]). This can be overridden @@ -898,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. @@ -1139,6 +1188,10 @@ receive.unpackLimit:: especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. +receive.denyDeletes:: + If set to true, git-receive-pack will deny a ref update that deletes + the ref. Use this to prevent such a ref deletion via a push. + receive.denyNonFastForwards:: If set to true, git-receive-pack will deny a ref update which is not a fast forward. Use this to prevent such an update via a push, diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 45885bbbb2..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. @@ -106,9 +109,9 @@ endif::git-format-patch[] --exit-code. --full-index:: - Instead of the first handful characters, show full - object name of pre- and post-image blob on the "index" - line when generating a patch format output. + Instead of the first handful of characters, show the full + pre- and post-image blob object names on the "index" + line when generating patch format output. --binary:: In addition to --full-index, output "binary diff" that diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 2b6d6c8654..6fc20b0baf 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] - [--all | [--update | -u]] [--refresh] [--ignore-errors] [--] - <filepattern>... + [--all | [--update | -u]] [--intent-to-add | -N] + [--refresh] [--ignore-errors] [--] <filepattern>... DESCRIPTION ----------- @@ -92,6 +92,15 @@ OPTIONS and add all untracked files that are not ignored by '.gitignore' mechanism. + +-N:: +--intent-to-add:: + Record only the fact that the path will be added later. An entry + for the path is placed in the index with no content. This is + useful for, among other things, showing the unstaged content of + such files with 'git diff' and commiting them with 'git commit + -a'. + --refresh:: Don't add the file(s), but only refresh their stat() information in the index. 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 4b3c2b0b06..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,6 +19,13 @@ 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 diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 5aa69c0e12..168333a588 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -8,8 +8,8 @@ git-checkout - Checkout a branch or paths to the working tree SYNOPSIS -------- [verse] -'git checkout' [-q] [-f] [[--track | --no-track] -b <new_branch> [-l]] [-m] [<branch>] -'git checkout' [<tree-ish>] [--] <paths>... +'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>] +'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... DESCRIPTION ----------- @@ -21,16 +21,26 @@ specified, <new_branch>. Using -b will cause <new_branch> to be created; in this case you can use the --track or --no-track options, which will be passed to `git branch`. +As a convenience, --track will default to create a branch whose +name is constructed from the specified branch name by stripping +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 ------- @@ -38,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 @@ -59,6 +78,17 @@ OPTIONS 'git-checkout' and 'git-branch' to always behave as if '--no-track' were given. Set it to `always` if you want this behavior when the start-point is either a local or remote branch. ++ +If no '-b' option was given, the name of the new branch will be +derived from the remote branch, by attempting to guess the name +of the branch on remote system. If "remotes/" or "refs/remotes/" +are prefixed, it is stripped away, and then the part up to the +next slash (which would be the nickname of the remote) is removed. +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 +explicitly give a name with '-b' in such a case. --no-track:: Ignore the branch.autosetupmerge configuration variable. @@ -69,7 +99,9 @@ OPTIONS 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. @@ -81,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 79be4f1c00..2e62165fa9 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -75,8 +75,10 @@ OPTIONS read the message from the standard input. --author=<author>:: - Override the author name used in the commit. Use - `A U Thor <author@example.com>` format. + Override the author name used in the commit. You can use the + standard `A U Thor <author@example.com>` format. Otherwise, + an existing commit that matches the given string and its author + name is used. -m <msg>:: --message=<msg>:: @@ -143,6 +145,10 @@ It is a rough equivalent for: ------ but can be used to amend a merge commit. -- ++ +You should understand the implications of rewriting history if you +amend a commit that has already been published. (See the "RECOVERING +FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) -i:: --include:: diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 75a8da1ca9..6bc1c21e62 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -21,8 +21,9 @@ OPTIONS --verbose:: In addition to the number of loose objects and disk space consumed, it reports the number of in-pack - objects, number of packs, and number of objects that can be - removed by running `git prune-packed`. + objects, number of packs, disk space consumed by those packs, + and number of objects that can be removed by running + `git prune-packed`. Author diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 4ba4b75c11..f1a570a874 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -9,8 +9,9 @@ SYNOPSIS -------- [verse] 'git daemon' [--verbose] [--syslog] [--export-all] - [--timeout=n] [--init-timeout=n] [--strict-paths] - [--base-path=path] [--user-path | --user-path=path] + [--timeout=n] [--init-timeout=n] [--max-connections=n] + [--strict-paths] [--base-path=path] [--base-path-relaxed] + [--user-path | --user-path=path] [--interpolated-path=pathtemplate] [--reuseaddr] [--detach] [--pid-file=file] [--enable=service] [--disable=service] @@ -99,6 +100,10 @@ OPTIONS it takes for the server to process the sub-request and time spent waiting for next client's request. +--max-connections:: + Maximum number of concurrent clients, defaults to 32. Set it to + zero for no limit. + --syslog:: Log to syslog instead of stderr. Note that this option does not imply --verbose, thus by default only error conditions will be logged. @@ -265,6 +270,15 @@ selectively enable/disable services per repository:: ---------------------------------------------------------------- +ENVIRONMENT +----------- +'git-daemon' will set REMOTE_ADDR to the IP address of the client +that connected to it, if the IP address is available. REMOTE_ADDR will +be available in the environment of hooks called when +services are performed. + + + Author ------ Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki 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-diff-tree.txt b/Documentation/git-diff-tree.txt index 1fdf20dcc9..5d48664e62 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -49,13 +49,22 @@ include::diff-options.txt[] --stdin:: When '--stdin' is specified, the command does not take <tree-ish> arguments from the command line. Instead, it - reads either one <commit> or a list of <commit> - separated with a single space from its standard input. + reads lines containing either two <tree>, one <commit>, or a + list of <commit> from its standard input. (Use a single space + as separator.) + -When a single commit is given on one line of such input, it compares -the commit with its parents. The following flags further affects its -behavior. The remaining commits, when given, are used as if they are +When two trees are given, it compares the first tree with the second. +When a single commit is given, it compares the commit with its +parents. The remaining commits, when given, are used as if they are parents of the first commit. ++ +When comparing two trees, the ID of both trees (separated by a space +and terminated by a newline) is printed before the difference. When +comparing commits, the ID of the first (or only) commit, followed by a +newline, is printed. ++ +The following flags further affects the behavior when comparing +commits (but not trees). -m:: By default, 'git-diff-tree --stdin' does not show diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index b0e710d5f9..fed6de6a7f 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -36,7 +36,9 @@ the objects and will not converge with the original branch. You will not be able to easily push and distribute the rewritten branch on top of the original branch. Please do not use this command if you do not know the full implications, and avoid using it anyway, if a simple single commit -would suffice to fix your problem. +would suffice to fix your problem. (See the "RECOVERING FROM UPSTREAM +REBASE" section in linkgit:git-rebase[1] for further information about +rewriting published history.) Always verify that the rewritten version is correct: The original refs, if different from the rewritten ones, will be stored in the namespace 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 7426109f62..11a7d77261 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -59,8 +59,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 @@ -82,7 +84,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-hash-object.txt b/Documentation/git-hash-object.txt index ac928e198e..0af40cfb85 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -8,7 +8,9 @@ git-hash-object - Compute object ID and optionally creates a blob from a file SYNOPSIS -------- -'git hash-object' [-t <type>] [-w] [--stdin | --stdin-paths] [--] <file>... +[verse] +'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>... +'git hash-object' [-t <type>] [-w] --stdin-paths < <list-of-paths> DESCRIPTION ----------- @@ -35,6 +37,22 @@ OPTIONS --stdin-paths:: Read file names from stdin instead of from the command-line. +--path:: + Hash object as it were located at the given path. The location of + file does not directly influence on the hash value, but path is + used to determine what git filters should be applied to the object + before it can be placed to the object database, and, as result of + applying filters, the actual blob put into the object database may + differ from the given file. This option is mainly useful for hashing + temporary files located outside of the working directory or files + read from stdin. + +--no-filters:: + Hash the contents as is, ignoring any input filter that would + have been chosen by the attributes mechanism, including crlf + conversion. If the file is read from standard input then this + is always implied, unless the --path option is given. + Author ------ Written by Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index f414583fc4..d9b9c34b3a 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -112,7 +112,9 @@ For example, this configuration: will try to use konqueror first. But this may fail (for example if DISPLAY is not set) and in that case emacs' woman mode will be tried. -If everything fails the 'man' program will be tried anyway. +If everything fails, or if no viewer is configured, the viewer specified +in the GIT_MAN_VIEWER environment variable will be tried. If that +fails too, the 'man' program will be tried anyway. man.<tool>.path ~~~~~~~~~~~~~~~ diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index b3d8da33ee..bd49a0aee8 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -3,7 +3,7 @@ git-imap-send(1) NAME ---- -git-imap-send - Dump a mailbox from stdin into an imap folder +git-imap-send - Send a collection of patches from stdin to an IMAP folder SYNOPSIS @@ -13,9 +13,9 @@ SYNOPSIS DESCRIPTION ----------- -This command uploads a mailbox generated with git-format-patch -into an imap drafts folder. This allows patches to be sent as -other email is sent with mail clients that cannot read mailbox +This command uploads a mailbox generated with 'git-format-patch' +into an IMAP drafts folder. This allows patches to be sent as +other email is when using mail clients that cannot read mailbox files directly. Typical usage is something like: @@ -26,21 +26,75 @@ git format-patch --signoff --stdout --attach origin | git imap-send CONFIGURATION ------------- -'git-imap-send' requires the following values in the repository -configuration file (shown with examples): +To use the tool, imap.folder and either imap.tunnel or imap.host must be set +to appropriate values. + +Variables +~~~~~~~~~ + +imap.folder:: + The folder to drop the mails into, which is typically the Drafts + folder. For example: "INBOX.Drafts", "INBOX/Drafts" or + "[Gmail]/Drafts". Required to use imap-send. + +imap.tunnel:: + Command used to setup a tunnel to the IMAP server through which + commands will be piped instead of using a direct network connection + to the server. Required when imap.host is not set to use imap-send. + +imap.host:: + A URL identifying the server. Use a `imap://` prefix for non-secure + connections and a `imaps://` prefix for secure connections. + Ignored when imap.tunnel is set, but required to use imap-send + otherwise. + +imap.user:: + The username to use when logging in to the server. + +imap.password:: + The password to use when logging in to the server. + +imap.port:: + An integer port number to connect to on the server. + Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. + Ignored when imap.tunnel is set. + +imap.sslverify:: + A boolean to enable/disable verification of the server certificate + used by the SSL/TLS connection. Default is `true`. Ignored when + imap.tunnel is set. + +Examples +~~~~~~~~ + +Using tunnel mode: .......................... [imap] - Folder = "INBOX.Drafts" + folder = "INBOX.Drafts" + tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null" +.......................... +Using direct mode: + +......................... [imap] - Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null" + folder = "INBOX.Drafts" + host = imap://imap.example.com + user = bob + pass = p4ssw0rd +.......................... + +Using direct mode with SSL: +......................... [imap] - Host = imap.server.com - User = bob - Pass = pwd - Port = 143 + folder = "INBOX.Drafts" + host = imaps://imap.example.com + user = bob + pass = p4ssw0rd + port = 123 + sslverify = false .......................... diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 1a7ecbf8f3..2f0c5259e0 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -8,26 +8,81 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- -'git merge-base' [--all] <commit> <commit> +'git merge-base' [--all] <commit> <commit>... DESCRIPTION ----------- -'git-merge-base' finds as good a common ancestor as possible between -the two commits. That is, given two commits A and B, `git merge-base A -B` will output a commit which is reachable from both A and B through -the parent relationship. +'git-merge-base' finds best common ancestor(s) between two commits to use +in a three-way merge. One common ancestor is 'better' than another common +ancestor if the latter is an ancestor of the former. A common ancestor +that does not have any better common ancestor than it is a 'best common +ancestor', i.e. a 'merge base'. Note that there can be more than one +merge bases between two commits. -Given a selection of equally good common ancestors it should not be -relied on to decide in any particular way. - -The 'git-merge-base' algorithm is still in flux - use the source... +Among the two commits to compute their merge bases, one is specified by +the first commit argument on the command line; the other commit is a +(possibly hypothetical) commit that is a merge across all the remaining +commits on the command line. As the most common special case, giving only +two commits from the command line means computing the merge base between +the given two commits. OPTIONS ------- --all:: - Output all common ancestors for the two commits instead of - just one. + Output all merge bases for the commits, instead of just one. + +DISCUSSION +---------- + +Given two commits 'A' and 'B', `git merge-base A B` will output a commit +which is reachable from both 'A' and 'B' through the parent relationship. + +For example, with this topology: + + o---o---o---B + / + ---o---1---o---o---o---A + +the merge base between 'A' and 'B' is '1'. + +Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the +merge base between 'A' and an hypothetical commit 'M', which is a merge +between 'B' and 'C'. For example, with this topology: + + o---o---o---o---C + / + / o---o---o---B + / / + ---2---1---o---o---o---A + +the result of `git merge-base A B C` is '1'. This is because the +equivalent topology with a merge commit 'M' between 'B' and 'C' is: + + + o---o---o---o---o + / \ + / o---o---o---o---M + / / + ---2---1---o---o---o---A + +and the result of `git merge-base A M` is '1'. Commit '2' is also a +common ancestor between 'A' and 'M', but '1' is a better common ancestor, +because '2' is an ancestor of '1'. Hence, '2' is not a merge base. + +When the history involves criss-cross merges, there can be more than one +'best' common ancestors between two commits. For example, with this +topology: + + ---1---o---A + \ / + X + / \ + ---2---o---o---B + +both '1' and '2' are merge-base of A and B. Neither one is better than +the other (both are 'best' merge base). When `--all` option is not given, +it is unspecified which best one is output. Author ------ diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 17a15acb07..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 @@ -126,13 +191,25 @@ After seeing a conflict, you can do two things: up working tree changes made by 2. and 3.; 'git-reset --hard' can be used for this. - * Resolve the conflicts. `git diff` would report only the - conflicting paths because of the above 2. and 3. - Edit the working tree files into a desirable shape - ('git mergetool' can ease this task), 'git-add' or 'git-rm' - them, to make the index file contain what the merge result - should be, and run 'git-commit' to commit the result. + * Resolve the conflicts. Git will mark the conflicts in + the working tree. Edit the files into shape and + 'git-add' to the index. 'git-commit' to seal the deal. + +You can work through the conflict with a number of tools: + + * Use a mergetool. 'git mergetool' to launch a graphical + mergetool which will work you through the merge. + + * Look at the diffs. 'git diff' will show a three-way diff, + highlighting changes from both the HEAD and remote versions. + + * Look at the diffs on their own. 'git log --merge -p <path>' + will show diffs first for the HEAD version and then the + remote version. + * Look at the originals. 'git show :1:filename' shows the + common ancestor, 'git show :2:filename' shows the HEAD + version and 'git show :3:filename' shows the remote version. SEE ALSO -------- 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-read-tree.txt b/Documentation/git-read-tree.txt index 309deac23b..7160fa1536 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -212,7 +212,7 @@ 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 swiching to a new branch. That however will prevent +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. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 59c1b021a6..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,18 +253,16 @@ 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[] NOTES ----- -When you rebase a branch, you are changing its history in a way that -will cause problems for anyone who already has a copy of the branch -in their repository and tries to pull updates from you. You should -understand the implications of using 'git-rebase' on a repository that -you share. + +You should understand the implications of using 'git-rebase' on a +repository that you share. See also RECOVERING FROM UPSTREAM REBASE +below. When the git-rebase command is run, it will first execute a "pre-rebase" hook if one exists. You can use this hook to do sanity checks and @@ -396,6 +397,127 @@ consistent (they compile, pass the testsuite, etc.) you should use after each commit, test, and amend the commit if fixes are necessary. +RECOVERING FROM UPSTREAM REBASE +------------------------------- + +Rebasing (or any other form of rewriting) a branch that others have +based work on is a bad idea: anyone downstream of it is forced to +manually fix their history. This section explains how to do the fix +from the downstream's point of view. The real fix, however, would be +to avoid rebasing the upstream in the first place. + +To illustrate, suppose you are in a situation where someone develops a +'subsystem' branch, and you are working on a 'topic' that is dependent +on this 'subsystem'. You might end up with a history like the +following: + +------------ + o---o---o---o---o---o---o---o---o master + \ + o---o---o---o---o subsystem + \ + *---*---* topic +------------ + +If 'subsystem' is rebased against 'master', the following happens: + +------------ + o---o---o---o---o---o---o---o master + \ \ + o---o---o---o---o o'--o'--o'--o'--o' subsystem + \ + *---*---* topic +------------ + +If you now continue development as usual, and eventually merge 'topic' +to 'subsystem', the commits from 'subsystem' will remain duplicated forever: + +------------ + o---o---o---o---o---o---o---o master + \ \ + o---o---o---o---o o'--o'--o'--o'--o'--M subsystem + \ / + *---*---*-..........-*--* topic +------------ + +Such duplicates are generally frowned upon because they clutter up +history, making it harder to follow. To clean things up, you need to +transplant the commits on 'topic' to the new 'subsystem' tip, i.e., +rebase 'topic'. This becomes a ripple effect: anyone downstream from +'topic' is forced to rebase too, and so on! + +There are two kinds of fixes, discussed in the following subsections: + +Easy case: The changes are literally the same.:: + + This happens if the 'subsystem' rebase was a simple rebase and + had no conflicts. + +Hard case: The changes are not the same.:: + + This happens if the 'subsystem' rebase had conflicts, or used + `\--interactive` to omit, edit, or squash commits; or if the + upstream used one of `commit \--amend`, `reset`, or + `filter-branch`. + + +The easy case +~~~~~~~~~~~~~ + +Only works if the changes (patch IDs based on the diff contents) on +'subsystem' are literally the same before and after the rebase +'subsystem' did. + +In that case, the fix is easy because 'git-rebase' knows to skip +changes that are already present in the new upstream. So if you say +(assuming you're on 'topic') +------------ + $ git rebase subsystem +------------ +you will end up with the fixed history +------------ + o---o---o---o---o---o---o---o master + \ + o'--o'--o'--o'--o' subsystem + \ + *---*---* topic +------------ + + +The hard case +~~~~~~~~~~~~~ + +Things get more complicated if the 'subsystem' changes do not exactly +correspond to the ones before the rebase. + +NOTE: While an "easy case recovery" sometimes appears to be successful + even in the hard case, it may have unintended consequences. For + example, a commit that was removed via `git rebase + \--interactive` will be **resurrected**! + +The idea is to manually tell 'git-rebase' "where the old 'subsystem' +ended and your 'topic' began", that is, what the old merge-base +between them was. You will have to find a way to name the last commit +of the old 'subsystem', for example: + +* With the 'subsystem' reflog: after 'git-fetch', the old tip of + 'subsystem' is at `subsystem@\{1}`. Subsequent fetches will + increase the number. (See linkgit:git-reflog[1].) + +* Relative to the tip of 'topic': knowing that your 'topic' has three + commits, the old tip of 'subsystem' must be `topic~3`. + +You can then transplant the old `subsystem..topic` to the new tip by +saying (for the reflog case, and assuming you are on 'topic' already): +------------ + $ git rebase --onto subsystem subsystem@{1} +------------ + +The ripple effect of a "hard case" recovery is especially bad: +'everyone' downstream from 'topic' will now have to perform a "hard +case" recovery too! + + Authors ------ Written by Junio C Hamano <gitster@pobox.com> and diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 6abaeac28c..52aab5e680 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -82,7 +82,9 @@ $ git reset --hard HEAD~3 <1> + <1> The last three commits (HEAD, HEAD^, and HEAD~2) were bad and you do not want to ever see them again. Do *not* do this if -you have already given these commits to somebody else. +you have already given these commits to somebody else. (See the +"RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1] for +the implications of doing so.) Undo a commit, making it a topic branch:: + 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-submodule.txt b/Documentation/git-submodule.txt index bf33b0cba0..babaa9bc46 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -14,6 +14,8 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] update [--init] [--] [<path>...] 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] +'git submodule' [--quiet] foreach <command> +'git submodule' [--quiet] sync [--] [<path>...] DESCRIPTION @@ -123,6 +125,30 @@ summary:: in the submodule between the given super project commit and the index or working tree (switched by --cached) are shown. +foreach:: + Evaluates an arbitrary shell command in each checked out submodule. + The command has access to the variables $path and $sha1: + $path is the name of the submodule directory relative to the + superproject, and $sha1 is the commit as recorded in the superproject. + Any submodules defined in the superproject but not checked out are + ignored by this command. Unless given --quiet, foreach prints the name + of each submodule before evaluating the command. + A non-zero return from the command in any submodule causes + the processing to terminate. This can be overridden by adding '|| :' + to the end of the command. ++ +As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will +show the path and currently checked out commit for each submodule. + +sync:: + Synchronizes submodules' remote URL configuration setting + to the value specified in .gitmodules. This is useful when + submodule URLs change upstream and you need to update your local + repositories accordingly. ++ +"git submodule sync" synchronizes all submodules while +"git submodule sync -- A" synchronizes submodule "A" only. + OPTIONS ------- -q:: diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 82d03b4ced..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 @@ -498,6 +518,8 @@ Tracking and contributing to an entire Subversion-managed project 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 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 37fff208ff..eb648418ee 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -314,10 +314,18 @@ patterns are available: - `bibtex` suitable for files with BibTeX coded references. +- `html` suitable for HTML/XHTML documents. + - `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. + +- `python` suitable for source code in the Python language. + - `ruby` suitable for source code in the Ruby language. - `tex` suitable for source code for LaTeX documents. 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/gitworkflows.txt b/Documentation/gitworkflows.txt new file mode 100644 index 0000000000..2b021e3c15 --- /dev/null +++ b/Documentation/gitworkflows.txt @@ -0,0 +1,364 @@ +gitworkflows(7) +=============== + +NAME +---- +gitworkflows - An overview of recommended workflows with git + +SYNOPSIS +-------- +git * + + +DESCRIPTION +----------- + +This document attempts to write down and motivate some of the workflow +elements used for `git.git` itself. Many ideas apply in general, +though the full workflow is rarely required for smaller projects with +fewer people involved. + +We formulate a set of 'rules' for quick reference, while the prose +tries to motivate each of them. Do not always take them literally; +you should value good reasons for your actions higher than manpages +such as this one. + + +SEPARATE CHANGES +---------------- + +As a general rule, you should try to split your changes into small +logical steps, and commit each of them. They should be consistent, +working independently of any later commits, pass the test suite, etc. +This makes the review process much easier, and the history much more +useful for later inspection and analysis, for example with +linkgit:git-blame[1] and linkgit:git-bisect[1]. + +To achieve this, try to split your work into small steps from the very +beginning. It is always easier to squash a few commits together than +to split one big commit into several. Don't be afraid of making too +small or imperfect steps along the way. You can always go back later +and edit the commits with `git rebase \--interactive` before you +publish them. You can use `git stash save \--keep-index` to run the +test suite independent of other uncommitted changes; see the EXAMPLES +section of linkgit:git-stash[1]. + + +MANAGING BRANCHES +----------------- + +There are two main tools that can be used to include changes from one +branch on another: linkgit:git-merge[1] and +linkgit:git-cherry-pick[1]. + +Merges have many advantages, so we try to solve as many problems as +possible with merges alone. Cherry-picking is still occasionally +useful; see "Merging upwards" below for an example. + +Most importantly, merging works at the branch level, while +cherry-picking works at the commit level. This means that a merge can +carry over the changes from 1, 10, or 1000 commits with equal ease, +which in turn means the workflow scales much better to a large number +of contributors (and contributions). Merges are also easier to +understand because a merge commit is a "promise" that all changes from +all its parents are now included. + +There is a tradeoff of course: merges require a more careful branch +management. The following subsections discuss the important points. + + +Graduation +~~~~~~~~~~ + +As a given feature goes from experimental to stable, it also +"graduates" between the corresponding branches of the software. +`git.git` uses the following 'integration branches': + +* 'maint' tracks the commits that should go into the next "maintenance + release", i.e., update of the last released stable version; + +* 'master' tracks the commits that should go into the next release; + +* 'next' is intended as a testing branch for topics being tested for + stability for master. + +There is a fourth official branch that is used slightly differently: + +* 'pu' (proposed updates) is an integration branch for things that are + not quite ready for inclusion yet (see "Integration Branches" + below). + +Each of the four branches is usually a direct descendant of the one +above it. + +Conceptually, the feature enters at an unstable branch (usually 'next' +or 'pu'), and "graduates" to 'master' for the next release once it is +considered stable enough. + + +Merging upwards +~~~~~~~~~~~~~~~ + +The "downwards graduation" discussed above cannot be done by actually +merging downwards, however, since that would merge 'all' changes on +the unstable branch into the stable one. Hence the following: + +.Merge upwards +[caption="Rule: "] +===================================== +Always commit your fixes to the oldest supported branch that require +them. Then (periodically) merge the integration branches upwards into each +other. +===================================== + +This gives a very controlled flow of fixes. If you notice that you +have applied a fix to e.g. 'master' that is also required in 'maint', +you will need to cherry-pick it (using linkgit:git-cherry-pick[1]) +downwards. This will happen a few times and is nothing to worry about +unless you do it very frequently. + + +Topic branches +~~~~~~~~~~~~~~ + +Any nontrivial feature will require several patches to implement, and +may get extra bugfixes or improvements during its lifetime. + +Committing everything directly on the integration branches leads to many +problems: Bad commits cannot be undone, so they must be reverted one +by one, which creates confusing histories and further error potential +when you forget to revert part of a group of changes. Working in +parallel mixes up the changes, creating further confusion. + +Use of "topic branches" solves these problems. The name is pretty +self explanatory, with a caveat that comes from the "merge upwards" +rule above: + +.Topic branches +[caption="Rule: "] +===================================== +Make a side branch for every topic (feature, bugfix, ...). Fork it off +at the oldest integration branch that you will eventually want to merge it +into. +===================================== + +Many things can then be done very naturally: + +* To get the feature/bugfix into an integration branch, simply merge + it. If the topic has evolved further in the meantime, merge again. + (Note that you do not necessarily have to merge it to the oldest + integration branch first. For example, you can first merge a bugfix + to 'next', give it some testing time, and merge to 'maint' when you + know it is stable.) + +* If you find you need new features from the branch 'other' to continue + working on your topic, merge 'other' to 'topic'. (However, do not + do this "just habitually", see below.) + +* If you find you forked off the wrong branch and want to move it + "back in time", use linkgit:git-rebase[1]. + +Note that the last point clashes with the other two: a topic that has +been merged elsewhere should not be rebased. See the section on +RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1]. + +We should point out that "habitually" (regularly for no real reason) +merging an integration branch into your topics -- and by extension, +merging anything upstream into anything downstream on a regular basis +-- is frowned upon: + +.Merge to downstream only at well-defined points +[caption="Rule: "] +===================================== +Do not merge to downstream except with a good reason: upstream API +changes affect your branch; your branch no longer merges to upstream +cleanly; etc. +===================================== + +Otherwise, the topic that was merged to suddenly contains more than a +single (well-separated) change. The many resulting small merges will +greatly clutter up history. Anyone who later investigates the history +of a file will have to find out whether that merge affected the topic +in development. An upstream might even inadvertently be merged into a +"more stable" branch. And so on. + + +Throw-away integration +~~~~~~~~~~~~~~~~~~~~~~ + +If you followed the last paragraph, you will now have many small topic +branches, and occasionally wonder how they interact. Perhaps the +result of merging them does not even work? But on the other hand, we +want to avoid merging them anywhere "stable" because such merges +cannot easily be undone. + +The solution, of course, is to make a merge that we can undo: merge +into a throw-away branch. + +.Throw-away integration branches +[caption="Rule: "] +===================================== +To test the interaction of several topics, merge them into a +throw-away branch. You must never base any work on such a branch! +===================================== + +If you make it (very) clear that this branch is going to be deleted +right after the testing, you can even publish this branch, for example +to give the testers a chance to work with it, or other developers a +chance to see if their in-progress work will be compatible. `git.git` +has such an official throw-away integration branch called 'pu'. + + +DISTRIBUTED WORKFLOWS +--------------------- + +After the last section, you should know how to manage topics. In +general, you will not be the only person working on the project, so +you will have to share your work. + +Roughly speaking, there are two important workflows: merge and patch. +The important difference is that the merge workflow can propagate full +history, including merges, while patches cannot. Both workflows can +be used in parallel: in `git.git`, only subsystem maintainers use +the merge workflow, while everyone else sends patches. + +Note that the maintainer(s) may impose restrictions, such as +"Signed-off-by" requirements, that all commits/patches submitted for +inclusion must adhere to. Consult your project's documentation for +more information. + + +Merge workflow +~~~~~~~~~~~~~~ + +The merge workflow works by copying branches between upstream and +downstream. Upstream can merge contributions into the official +history; downstream base their work on the official history. + +There are three main tools that can be used for this: + +* linkgit:git-push[1] copies your branches to a remote repository, + usually to one that can be read by all involved parties; + +* linkgit:git-fetch[1] that copies remote branches to your repository; + and + +* linkgit:git-pull[1] that does fetch and merge in one go. + +Note the last point. Do 'not' use 'git-pull' unless you actually want +to merge the remote branch. + +Getting changes out is easy: + +.Push/pull: Publishing branches/topics +[caption="Recipe: "] +===================================== +`git push <remote> <branch>` and tell everyone where they can fetch +from. +===================================== + +You will still have to tell people by other means, such as mail. (Git +provides the linkgit:git-request-pull[1] to send preformatted pull +requests to upstream maintainers to simplify this task.) + +If you just want to get the newest copies of the integration branches, +staying up to date is easy too: + +.Push/pull: Staying up to date +[caption="Recipe: "] +===================================== +Use `git fetch <remote>` or `git remote update` to stay up to date. +===================================== + +Then simply fork your topic branches from the stable remotes as +explained earlier. + +If you are a maintainer and would like to merge other people's topic +branches to the integration branches, they will typically send a +request to do so by mail. Such a request looks like + +------------------------------------- +Please pull from + <url> <branch> +------------------------------------- + +In that case, 'git-pull' can do the fetch and merge in one go, as +follows. + +.Push/pull: Merging remote topics +[caption="Recipe: "] +===================================== +`git pull <url> <branch>` +===================================== + +Occasionally, the maintainer may get merge conflicts when he tries to +pull changes from downstream. In this case, he can ask downstream to +do the merge and resolve the conflicts themselves (perhaps they will +know better how to resolve them). It is one of the rare cases where +downstream 'should' merge from upstream. + + +Patch workflow +~~~~~~~~~~~~~~ + +If you are a contributor that sends changes upstream in the form of +emails, you should use topic branches as usual (see above). Then use +linkgit:git-format-patch[1] to generate the corresponding emails +(highly recommended over manually formatting them because it makes the +maintainer's life easier). + +.format-patch/am: Publishing branches/topics +[caption="Recipe: "] +===================================== +* `git format-patch -M upstream..topic` to turn them into preformatted + patch files +* `git send-email --to=<recipient> <patches>` +===================================== + +See the linkgit:git-format-patch[1] and linkgit:git-send-email[1] +manpages for further usage notes. + +If the maintainer tells you that your patch no longer applies to the +current upstream, you will have to rebase your topic (you cannot use a +merge because you cannot format-patch merges): + +.format-patch/am: Keeping topics up to date +[caption="Recipe: "] +===================================== +`git pull --rebase <url> <branch>` +===================================== + +You can then fix the conflicts during the rebase. Presumably you have +not published your topic other than by mail, so rebasing it is not a +problem. + +If you receive such a patch series (as maintainer, or perhaps as a +reader of the mailing list it was sent to), save the mails to files, +create a new topic branch and use 'git-am' to import the commits: + +.format-patch/am: Importing patches +[caption="Recipe: "] +===================================== +`git am < patch` +===================================== + +One feature worth pointing out is the three-way merge, which can help +if you get conflicts: `git am -3` will use index information contained +in patches to figure out the merge base. See linkgit:git-am[1] for +other options. + + +SEE ALSO +-------- +linkgit:gittutorial[7], +linkgit:git-push[1], +linkgit:git-pull[1], +linkgit:git-merge[1], +linkgit:git-rebase[1], +linkgit:git-format-patch[1], +linkgit:git-send-email[1], +linkgit:git-am[1] + +GIT +--- +Part of the linkgit:git[1] suite. 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/i18n.txt b/Documentation/i18n.txt index d2970f8357..2cdacd94cd 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -37,9 +37,9 @@ of `i18n.commitencoding` in its `encoding` header. This is to help other people who look at them later. Lack of this header implies that the commit log message is encoded in UTF-8. -. 'git-log', 'git-show' and friends looks at the `encoding` - header of a commit object, and tries to re-code the log - message into UTF-8 unless otherwise specified. You can +. 'git-log', 'git-show', 'git-blame' and friends look at the + `encoding` header of a commit object, and try to re-code the + log message into UTF-8 unless otherwise specified. You can specify the desired output encoding with `i18n.logoutputencoding` in `.git/config` file, like this: + 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/rev-list-options.txt b/Documentation/rev-list-options.txt index 5df35ce519..966276b169 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -413,6 +413,48 @@ Note that without '\--full-history', this still simplifies merges: if one of the parents is TREESAME, we follow only that one, so the other sides of the merge are never walked. +Finally, there is a fourth simplification mode available: + +--simplify-merges:: + + First, build a history graph in the same way that + '\--full-history' with parent rewriting does (see above). ++ +Then simplify each commit `C` to its replacement `C'` in the final +history according to the following rules: ++ +-- +* Set `C'` to `C`. ++ +* Replace each parent `P` of `C'` with its simplification `P'`. In + the process, drop parents that are ancestors of other parents, and + remove duplicates. ++ +* If after this parent rewriting, `C'` is a root or merge commit (has + zero or >1 parents), a boundary commit, or !TREESAME, it remains. + Otherwise, it is replaced with its only parent. +-- ++ +The effect of this is best shown by way of comparing to +'\--full-history' with parent rewriting. The example turns into: ++ +----------------------------------------------------------------------- + .-A---M---N---O + / / / + I B D + \ / / + `---------' +----------------------------------------------------------------------- ++ +Note the major differences in `N` and `P` over '\--full-history': ++ +-- +* `N`'s parent list had `I` removed, because it is an ancestor of the + other parent `M`. Still, `N` remained because it is !TREESAME. ++ +* `P`'s parent list similarly had `I` removed. `P` was then + removed completely, because it had one parent and is TREESAME. +-- ifdef::git-rev-list[] Bisection Helpers 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 diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 08d1310bf5..645d752c5c 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4356,7 +4356,9 @@ $ git remote show example # get details * remote example URL: git://example.com/project.git Tracked remote branches - master next ... + master + next + ... $ git fetch example # update branches from example $ git branch -r # list all remote branches ----------------------------------------------- |