diff options
Diffstat (limited to 'Documentation')
35 files changed, 1068 insertions, 83 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index ded0e40b97..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)) @@ -87,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) @@ -220,7 +222,9 @@ $(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: diff --git a/Documentation/RelNotes-1.6.0.3.txt b/Documentation/RelNotes-1.6.0.3.txt index 6cf8ae4ea1..ae0577836a 100644 --- a/Documentation/RelNotes-1.6.0.3.txt +++ b/Documentation/RelNotes-1.6.0.3.txt @@ -16,12 +16,17 @@ Fixes since v1.6.0.2 * "git rebase -i" now honors the pre-rebase hook, just like the other rebase implementations "git rebase" and "git rebase -m". +* "git rebase -i" incorrectly aborted when there is no commit to replay. + * Behaviour of "git diff --quiet" was inconsistent with "diff --exit-code" with the output redirected to /dev/null. * "git diff --no-index" on binary files no longer outputs a bogus "diff --git" header line. +* "git diff" hunk header patterns with multiple elements separated by LF + were not used correctly. + * Hunk headers in "git diff" default to using extended regular expressions, fixing some of the internal patterns on non-GNU platforms. @@ -29,6 +34,15 @@ Fixes since v1.6.0.2 * New config "diff.*.xfuncname" exposes extended regular expressions for user specified hunk header patterns. +* "git gc" when ejecting otherwise unreachable objects from packfiles into + loose form leaked memory. + +* "git index-pack" was recently broken and mishandled objects added by + thin-pack completion processing under memory pressure. + +* "git index-pack" was recently broken and misbehaved when run from inside + .git/objects/pack/ directory. + * "git stash apply sash@{1}" was fixed to error out. Prior versions would have applied stash@{0} incorrectly. @@ -42,6 +56,8 @@ Fixes since v1.6.0.2 * "git remote show -v" now displays all URLs of a remote. +* "git checkout -b branch" was confused when branch already existed. + * "git checkout -q" once again suppresses the locally modified file list. * "git clone -q", "git fetch -q" asks remote side to not send @@ -56,9 +72,15 @@ Fixes since v1.6.0.2 * "git merge" once again removes directories after the last file has been removed from it during the merge. +* "git merge" did not allocate enough memory for the structure itself when + enumerating the parents of the resulting commit. + * "git blame -C -C" no longer segfaults while trying to pass blame if it encounters a submodule reference. +* "git rm" incorrectly claimed that you have local modifications when a + path was merely stat-dirty. + * "git svn" fixed to display an error message when 'set-tree' failed, instead of a Perl compile error. @@ -68,10 +90,16 @@ Fixes since v1.6.0.2 * The "git commit" error message when there are still unmerged files present was clarified to match "git write-tree". +* "git init" was confused when core.bare or core.sharedRepository are set + in system or user global configuration file by mistake. When --bare or + --shared is given from the command line, these now override such + settings made outside the repositories. + * Some segfaults due to uncaught NULL pointers were fixed in multiple tools such as apply, reset, update-index. -* Solaris builds now default to OLD_ICONV=1 to avoid compile warnings. +* Solaris builds now default to OLD_ICONV=1 to avoid compile warnings; + Solaris 8 does not define NEEDS_LIBICONV by default. * "Git.pm" tests relied on unnecessarily more recent version of Perl. @@ -87,9 +115,3 @@ Fixes since v1.6.0.2 ("git fetch") is still however supported. Many other documentation updates. - --- -exec >/var/tmp/1 -O=v1.6.0.2-76-gd70b4a8 -echo O=$(git describe maint) -git shortlog --no-merges $O..maint diff --git a/Documentation/RelNotes-1.6.0.4.txt b/Documentation/RelNotes-1.6.0.4.txt new file mode 100644 index 0000000000..fba3f30a89 --- /dev/null +++ b/Documentation/RelNotes-1.6.0.4.txt @@ -0,0 +1,39 @@ +GIT v1.6.0.4 Release Notes +========================== + +Fixes since v1.6.0.3 +-------------------- + +* 'git add -p' said "No changes" when only binary files were changed. + +* 'git archive' did not work correctly in bare repositories. + +* 'git checkout -t -b newbranch' when you are on detached HEAD was broken. + +* when we refuse to detect renames because there are too many new or + deleted files, 'git diff' did not say how many there are. + +* 'git push --mirror' tried and failed to push the stash; there is no + point in sending it to begin with. + +* 'git push' did not update the remote tracking reference if the corresponding + ref on the remote end happened to be already up to date. + +* 'git pull $there $branch:$current_branch' did not work when you were on + a branch yet to be born. + +* when giving up resolving a conflicted merge, 'git reset --hard' failed + to remove new paths from the working tree. + +* 'git send-email' had a small fd leak while scanning directory. + +* 'git status' incorrectly reported a submodule directory as an untracked + directory. + +* 'git svn' used deprecated 'git-foo' form of subcommand invocaition. + +* 'git update-ref -d' to remove a reference did not honor --no-deref option. + +* Plugged small memleaks here and there. + +* Also contains many documentation updates. diff --git a/Documentation/RelNotes-1.6.0.5.txt b/Documentation/RelNotes-1.6.0.5.txt new file mode 100644 index 0000000000..62f95e6bad --- /dev/null +++ b/Documentation/RelNotes-1.6.0.5.txt @@ -0,0 +1,21 @@ +GIT v1.6.0.5 Release Notes +========================== + +Fixes since v1.6.0.4 +-------------------- + +* 'git checkout' used to crash when your HEAD was pointing at a deleted + branch. + +* 'git checkout' from an un-checked-out state did not allow switching out + of the current branch. + +* 'git pack-objects' did not make its best effort to honor --max-pack-size + option when a single first object already busted the given limit and + placed many objects in a single pack. + +* 'make check' cannot be run without sparse; people may have meant to say + 'make test' instead, so suggest that. + +* Many unsafe call to sprintf() style varargs functions are corrected. + diff --git a/Documentation/RelNotes-1.6.1.txt b/Documentation/RelNotes-1.6.1.txt index 906932cfa1..d0e30e95d4 100644 --- a/Documentation/RelNotes-1.6.1.txt +++ b/Documentation/RelNotes-1.6.1.txt @@ -16,13 +16,16 @@ on. * gitk can call out to git-gui to view "git blame" output; git-gui in turn can run gitk from its blame view. -(portability) +* Various git-gui updates including updated translations. + +* Various gitweb updates from repo.or.cz installation. -* ... +(portability) -(documentation) +* A few test scripts used nonportable "grep" that did not work well on + some platforms, e.g. Solaris. -* ... +* Sample pre-auto-gc script has OS X support. (performance) @@ -35,6 +38,14 @@ on. * 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 @@ -42,35 +53,77 @@ on. 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 and - HTML contents. +* "git diff" learned to put more sensible hunk headers for Python, + HTML and ObjC contents. * "git diff" learned to vary the a/ vs b/ prefix depending on what are being compared, controlled by diff.mnemonicprefix configuration. +* "git diff" learned --dirstat-by-file to count changed files, not number + of lines, when summarizing the global picture. + +* "git diff" hunk header pattern for ObjC has been added. + +* 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. @@ -94,21 +147,50 @@ on. * "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 ------------------ @@ -124,6 +206,11 @@ release, unless otherwise noted. 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 @@ -135,6 +222,6 @@ release, unless otherwise noted. -- exec >/var/tmp/1 -O=v1.6.0.2-295-g34a5d35 +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 a1e9100f9e..f0295c60f5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -456,3 +456,30 @@ This should help you to submit patches inline using KMail. 5) Back in the compose window: add whatever other text you wish to the message, complete the addressing and subject fields, and press send. + + +Gmail +----- + +Submitting properly formatted patches via Gmail is simple now that +IMAP support is available. First, edit your ~/.gitconfig to specify your +account settings: + +[imap] + folder = "[Gmail]/Drafts" + host = imaps://imap.gmail.com + user = user@gmail.com + pass = p4ssw0rd + port = 993 + sslverify = false + +Next, ensure that your Gmail settings are correct. In "Settings" the +"Use Unicode (UTF-8) encoding for outgoing messages" should be checked. + +Once your commits are ready to send to the mailing list, run the following +command to send the patch emails to your Gmail Drafts folder. + + $ git format-patch -M --stdout origin/master | git imap-send + +Go to your Gmail account, open the Drafts folder, find the patch email, fill +in the To: and CC: fields and send away! diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 40d43b78ee..2da867d2f8 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -40,6 +40,26 @@ endif::doctype-manpage[] </literallayout> {title#}</example> endif::docbook-xsl-172[] + +ifdef::docbook-xsl-172[] +ifdef::doctype-manpage[] +# The following two small workarounds insert a simple paragraph after screen +[listingblock] +<example><title>{title}</title> +<screen> +| +</screen><simpara></simpara> +{title#}</example> + +[verseblock] +<formalpara{id? id="{id}"}><title>{title}</title><para> +{title%}<literallayout{id? id="{id}"}> +{title#}<literallayout> +| +</literallayout><simpara></simpara> +{title#}</para></formalpara> +endif::doctype-manpage[] +endif::docbook-xsl-172[] endif::backend-docbook[] ifdef::doctype-manpage[] 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 da18a5458e..32dcd643d2 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -124,7 +124,9 @@ core.ignoreCygwinFSTricks:: 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. + 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 @@ -640,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 @@ -1185,12 +1188,25 @@ 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, even if that push is forced. This configuration variable is set when initializing a shared repository. +receive.denyCurrentBranch:: + If set to true or "refuse", receive-pack will deny a ref update + to the currently checked out branch of a non-bare repository. + Such a push is potentially dangerous because it brings the HEAD + out of sync with the index and working tree. If set to "warn", + print a warning of such a push to stderr, but allow the push to + proceed. If set to false or "ignore", allow such pushes with no + message. Defaults to "warn". + transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are not set, the value of this variable is used instead. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 400cbb3b1c..aafd3a3941 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -46,6 +46,22 @@ That is, from the left to the right: . path for "dst"; only exists for C or R. . an LF or a NUL when '-z' option is used, to terminate the record. +Possible status letters are: + +- A: addition of a file +- C: copy of a file into a new one +- D: deletion of a file +- M: modification of the contents or mode of a file +- R: renaming of a file +- T: change in the type of the file +- U: file is unmerged (you must complete the merge before it can +be committed) +- X: "unknown" change type (most probably a bug, please report it) + +Status letters C and M are always followed by a score (denoting the +percentage of similarity between the source and target of the move or +copy), and are the only ones to be so. + <sha1> is shown as all 0's if a file is new on the filesystem and it is out of sync with the index. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 7788d4fa4a..c62b45cdba 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -137,7 +137,8 @@ endif::git-format-patch[] --diff-filter=[ACDMRTUXB*]:: Select only files that are Added (`A`), Copied (`C`), Deleted (`D`), Modified (`M`), Renamed (`R`), have their - type (mode) changed (`T`), are Unmerged (`U`), are + type (i.e. regular file, symlink, submodule, ...) changed (`T`), + are Unmerged (`U`), are Unknown (`X`), or have had their pairing Broken (`B`). Any combination of the filter characters may be used. When `*` (All-or-none) is added to the combination, all diff --git a/Documentation/git-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-bisect.txt b/Documentation/git-bisect.txt index c7981efcd9..39034ec7d6 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -26,7 +26,7 @@ on the subcommand: git bisect log git bisect run <cmd>... -This command uses 'git-rev-list --bisect' to help drive the +This command uses 'git rev-list --bisect' to help drive the binary search process to find which change introduced a bug, given an old "good" commit object name and a later "bad" commit object name. @@ -101,7 +101,7 @@ $ git bisect visualize to see the currently remaining suspects in 'gitk'. `visualize` is a bit too long to type and `view` is provided as a synonym. -If 'DISPLAY' environment variable is not set, 'git-log' is used +If 'DISPLAY' environment variable is not set, 'git log' is used instead. You can even give command line options such as `-p` and `--stat`. @@ -215,7 +215,7 @@ tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or work around other problem this bisection is not interested in") applied to the revision being tested. -To cope with such a situation, after the inner 'git-bisect' finds the +To cope with such a situation, after the inner 'git bisect' finds the next revision to test, with the "run" script, you can apply that tweak before compiling, run the real test, and after the test decides if the revision (possibly with the needed tweaks) passed the test, rewind the diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 2b821f2a1d..8c2ac12f5d 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -3,12 +3,14 @@ git-check-attr(1) NAME ---- -git-check-attr - Display gitattributes information. +git-check-attr - Display gitattributes information SYNOPSIS -------- +[verse] 'git check-attr' attr... [--] pathname... +'git check-attr' --stdin [-z] attr... < <list-of-paths> DESCRIPTION ----------- @@ -17,11 +19,68 @@ For every pathname, this command will list if each attr is 'unspecified', OPTIONS ------- +--stdin:: + Read file names from stdin instead of from the command-line. + +-z:: + Only meaningful with `--stdin`; paths are separated with + NUL character instead of LF. + \--:: Interpret all preceding arguments as attributes, and all following arguments as path names. If not supplied, only the first argument will be treated as an attribute. +OUTPUT +------ + +The output is of the form: +<path> COLON SP <attribute> COLON SP <info> LF + +Where <path> is the path of a file being queried, <attribute> is an attribute +being queried and <info> can be either: + +'unspecified';; when the attribute is not defined for the path. +'unset';; when the attribute is defined to false. +'set';; when the attribute is defined to true. +<value>;; when a value has been assigned to the attribute. + +EXAMPLES +-------- + +In the examples, the following '.gitattributes' file is used: +--------------- +*.java diff=java -crlf myAttr +NoMyAttr.java !myAttr +README caveat=unspecified +--------------- + +* Listing a single attribute: +--------------- +$ git check-attr diff org/example/MyClass.java +org/example/MyClass.java: diff: java +--------------- + +* Listing multiple attributes for a file: +--------------- +$ git check-attr crlf diff myAttr -- org/example/MyClass.java +org/example/MyClass.java: crlf: unset +org/example/MyClass.java: diff: java +org/example/MyClass.java: myAttr: set +--------------- + +* Listing attribute for multiple files: +--------------- +$ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java +org/example/MyClass.java: myAttr: set +org/example/NoMyAttr.java: myAttr: unspecified +--------------- + +* Not all values are equally unambiguous: +--------------- +$ git check-attr caveat README +README: caveat: unspecified +--------------- SEE ALSO -------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 82e154de49..168333a588 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -88,7 +88,7 @@ This would tell us to use "hack" as the local branch when branching off of "origin/hack" (or "remotes/origin/hack", or even "refs/remotes/origin/hack"). If the given name has no slash, or the above guessing results in an empty name, the guessing is aborted. You can -exlicitly give a name with '-b' in such a case. +explicitly give a name with '-b' in such a case. --no-track:: Ignore the branch.autosetupmerge configuration variable. 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 eb05b0f49b..2e62165fa9 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -94,7 +94,8 @@ OPTIONS -s:: --signoff:: - Add Signed-off-by line at the end of the commit message. + Add Signed-off-by line by the commiter at the end of the commit + log message. -n:: --no-verify:: @@ -144,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-daemon.txt b/Documentation/git-daemon.txt index b08a08cd95..f1a570a874 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -270,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.txt b/Documentation/git-diff.txt index c53eba557d..a2f192fb75 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -33,6 +33,7 @@ forced by --no-index. commit relative to the named <commit>. Typically you would want comparison with the latest commit, so if you do not give <commit>, it defaults to HEAD. + --staged is a synonym of --cached. 'git diff' [--options] <commit> [--] [<path>...]:: 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-format-patch.txt b/Documentation/git-format-patch.txt index adb4ea7b1b..11a7d77261 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -46,7 +46,8 @@ applies to that command line and you do not get "everything since the beginning of the time". If you want to format everything since project inception to one commit, say "git format-patch \--root <commit>" to make it clear that it is the -latter case. +latter case. If you want to format a single commit, you can do +this with "git format-patch -1 <commit>". By default, each output file is numbered sequentially from 1, and uses the first line of the commit message (massaged for pathname safety) as @@ -58,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 @@ -81,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-log.txt b/Documentation/git-log.txt index 93a2a227c4..34cf4e5811 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -40,6 +40,10 @@ include::diff-options.txt[] --decorate:: Print out the ref names of any commits that are shown. +--source:: + Print out the ref name given on the command line by which each + commit was reached. + --full-diff:: Without this flag, "git log -p <path>..." shows commits that touch the specified paths, and diffs about the same specified diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 8c354bd470..7d4c1a7556 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -109,6 +109,11 @@ base-name:: The default is unlimited, unless the config variable `pack.packSizeLimit` is set. +--honor-pack-keep:: + This flag causes an object already in a local pack that + has a .keep file to be ignored, even if it appears in the + standard input. + --incremental:: This flag causes an object already in a pack ignored even if it appears in the standard input. @@ -116,7 +121,7 @@ base-name:: --local:: This flag is similar to `--incremental`; instead of ignoring all packed objects, it only ignores objects - that are packed and not in the local object store + that are packed and/or not in the local object store (i.e. borrowed from an alternate). --non-empty:: diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 32f0f122e9..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 @@ -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-remote.txt b/Documentation/git-remote.txt index bb99810ec7..fad983e297 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git remote' [-v | --verbose] 'git remote add' [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url> +'git remote rename' <old> <new> 'git remote rm' <name> 'git remote show' [-n] <name> 'git remote prune' [-n | --dry-run] <name> @@ -61,6 +62,15 @@ only makes sense in bare repositories. If a remote uses mirror mode, furthermore, `git push` will always behave as if `\--mirror` was passed. +'rename':: + +Rename the remote named <old> to <new>. All remote tracking branches and +configuration settings for the remote are updated. ++ +In case <old> and <new> are the same, and <old> is a file under +`$GIT_DIR/remotes` or `$GIT_DIR/branches`, the remote is converted to +the configuration file format. + 'rm':: Remove the remote named <name>. All remote tracking branches 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.txt b/Documentation/git.txt index df420aeb33..7e0a041436 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,11 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.6.0.2/git.html[documentation for release 1.6.0.2] +* link:v1.6.0.4/git.html[documentation for release 1.6.0.4] * release notes for + link:RelNotes-1.6.0.4.txt[1.6.0.4], + link:RelNotes-1.6.0.3.txt[1.6.0.3], link:RelNotes-1.6.0.2.txt[1.6.0.2], link:RelNotes-1.6.0.1.txt[1.6.0.1], link:RelNotes-1.6.0.txt[1.6.0]. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 26945593cb..a172baf993 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -163,8 +163,8 @@ few exceptions. Even though... `ident` ^^^^^^^ -When the attribute `ident` is set to a path, git replaces -`$Id$` in the blob object with `$Id:`, followed by +When the attribute `ident` is set for a path, git replaces +`$Id$` in the blob object with `$Id:`, followed by the 40-character hexadecimal blob object name, followed by a dollar sign `$` upon checkout. Any byte sequence that begins with `$Id:` and ends with `$` in the worktree file is replaced @@ -213,10 +213,15 @@ with `crlf`, and then `ident` and fed to `filter`. Generating diff text ~~~~~~~~~~~~~~~~~~~~ -The attribute `diff` affects if 'git-diff' generates textual -patch for the path or just says `Binary files differ`. It also -can affect what line is shown on the hunk header `@@ -k,l +n,m @@` -line. +`diff` +^^^^^^ + +The attribute `diff` affects how 'git' generates diffs for particular +files. It can tell git whether to generate a textual patch for the path +or to treat the path as a binary file. It can also affect what line is +shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an +external command to generate the diff, or ask git to convert binary +files to a text format before generating the diff. Set:: @@ -227,7 +232,8 @@ Set:: Unset:: A path to which the `diff` attribute is unset will - generate `Binary files differ`. + generate `Binary files differ` (or a binary patch, if + binary patches are enabled). Unspecified:: @@ -238,21 +244,21 @@ Unspecified:: String:: - Diff is shown using the specified custom diff driver. - The driver program is given its input using the same - calling convention as used for GIT_EXTERNAL_DIFF - program. This name is also used for custom hunk header - selection. + Diff is shown using the specified diff driver. Each driver may + specify one or more options, as described in the following + section. The options for the diff driver "foo" are defined + by the configuration variables in the "diff.foo" section of the + git config file. -Defining a custom diff driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Defining an external diff driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The definition of a diff driver is done in `gitconfig`, not `gitattributes` file, so strictly speaking this manual page is a wrong place to talk about it. However... -To define a custom diff driver `jcdiff`, add a section to your +To define an external diff driver `jcdiff`, add a section to your `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: ---------------------------------------------------------------- @@ -328,9 +334,49 @@ patterns are available: - `tex` suitable for source code for LaTeX documents. +Performing text diffs of binary files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sometimes it is desirable to see the diff of a text-converted +version of some binary files. For example, a word processor +document can be converted to an ASCII text representation, and +the diff of the text shown. Even though this conversion loses +some information, the resulting diff is useful for human +viewing (but cannot be applied directly). + +The `textconv` config option is used to define a program for +performing such a conversion. The program should take a single +argument, the name of a file to convert, and produce the +resulting text on stdout. + +For example, to show the diff of the exif information of a +file instead of the binary information (assuming you have the +exif tool installed): + +------------------------ +[diff "jpg"] + textconv = exif +------------------------ + +NOTE: The text conversion is generally a one-way conversion; +in this example, we lose the actual image contents and focus +just on the text data. This means that diffs generated by +textconv are _not_ suitable for applying. For this reason, +only `git diff` and the `git log` family of commands (i.e., +log, whatchanged, show) will perform text conversion. `git +format-patch` will never generate this output. If you want to +send somebody a text-converted diff of a binary file (e.g., +because it quickly conveys the changes you have made), you +should generate it separately and send it as a comment _in +addition to_ the usual binary diff that you might send. + + Performing a three-way merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +`merge` +^^^^^^^ + The attribute `merge` affects how three versions of a file is merged when a file-level merge is necessary during `git merge`, and other programs such as `git revert` and `git cherry-pick`. 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/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/rev-list-options.txt b/Documentation/rev-list-options.txt index 0ce916a188..6d7cf6d51f 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -174,6 +174,10 @@ endif::git-rev-list[] Limit the commits output to ones with log message that matches the specified pattern (regular expression). +--all-match:: + Limit the commits output to ones that match all given --grep, + --author and --committer instead of ones that match at least one. + -i:: --regexp-ignore-case:: @@ -281,8 +285,52 @@ See also linkgit:git-reflog[1]. History Simplification ~~~~~~~~~~~~~~~~~~~~~~ -When optional paths are given, 'git-rev-list' simplifies commits with -various strategies, according to the options you have selected. +Sometimes you are only interested in parts of the history, for example the +commits modifying a particular <path>. But there are two parts of +'History Simplification', one part is selecting the commits and the other +is how to do it, as there are various strategies to simplify the history. + +The following options select the commits to be shown: + +<paths>:: + + Commits modifying the given <paths> are selected. + +--simplify-by-decoration:: + + Commits that are referred by some branch or tag are selected. + +Note that extra commits can be shown to give a meaningful history. + +The following options affect the way the simplification is performed: + +Default mode:: + + Simplifies the history to the simplest history explaining the + final state of the tree. Simplest because it prunes some side + branches if the end result is the same (i.e. merging branches + with the same content) + +--full-history:: + + As the default mode but does not prune some history. + +--dense:: + + Only the selected commits are shown, plus some to have a + meaningful history. + +--sparse:: + + All commits in the simplified history are shown. + +--simplify-merges:: + + Additional option to '--full-history' to remove some needless + merges from the resulting history, as there are no selected + commits contributing to this merge. + +A more detailed explanation follows. Suppose you specified `foo` as the <paths>. We shall call commits that modify `foo` !TREESAME, and the rest TREESAME. (In a diff @@ -452,6 +500,14 @@ Note the major differences in `N` and `P` over '\--full-history': removed completely, because it had one parent and is TREESAME. -- +The '\--simplify-by-decoration' option allows you to view only the +big picture of the topology of the history, by omitting commits +that are not referenced by tags. Commits are marked as !TREESAME +(in other words, kept after history simplification rules described +above) if (1) they are referenced by tags, or (2) they change the +contents of the paths given on the command line. All other +commits are marked as TREESAME (subject to be simplified away). + ifdef::git-rev-list[] Bisection Helpers ~~~~~~~~~~~~~~~~~ @@ -462,14 +518,14 @@ Limit output to the one commit object which is roughly halfway between the included and excluded commits. Thus, if ----------------------------------------------------------------------- - $ git-rev-list --bisect foo ^bar ^baz + $ git rev-list --bisect foo ^bar ^baz ----------------------------------------------------------------------- outputs 'midpoint', the output of the two commands ----------------------------------------------------------------------- - $ git-rev-list foo ^midpoint - $ git-rev-list midpoint ^bar ^baz + $ git rev-list foo ^midpoint + $ git rev-list midpoint ^bar ^baz ----------------------------------------------------------------------- would be of roughly the same length. Finding the change which diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index 504ae8a53b..41ec7774f4 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -68,13 +68,22 @@ This file should have the following format: ------------ `<url>` is required; `#<head>` is optional. -When you do not provide a refspec on the command line, -git will use the following refspec, where `<head>` defaults to `master`, -and `<repository>` is the name of this file -you provided in the command line. + +Depending on the operation, git will use one of the following +refspecs, if you don't provide one on the command line. +`<branch>` is the name of this file in `$GIT_DIR/branches` and +`<head>` defaults to `master`. + +git fetch uses: + +------------ + refs/heads/<head>:refs/heads/<branch> +------------ + +git push uses: ------------ - refs/heads/<head>:<repository> + HEAD:refs/heads/<head> ------------ 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 ----------------------------------------------- |