diff options
Diffstat (limited to 'Documentation')
29 files changed, 721 insertions, 228 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 57da6aade..69f7e9b76 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -112,6 +112,14 @@ For C programs: - We try to keep to at most 80 characters per line. + - We try to support a wide range of C compilers to compile git with, + including old ones. That means that you should not use C99 + initializers, even if a lot of compilers grok it. + + - Variables have to be declared at the beginning of the block. + + - NULL pointers shall be written as NULL, not as 0. + - When declaring pointers, the star sides with the variable name, i.e. "char *string", not "char* string" or "char * string". This makes it easier to understand code diff --git a/Documentation/Makefile b/Documentation/Makefile index 361550422..e53d333e5 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -21,6 +21,7 @@ ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. SP_ARTICLES = user-manual +SP_ARTICLES += howto/new-command SP_ARTICLES += howto/revert-branch-rebase SP_ARTICLES += howto/using-merge-subtree SP_ARTICLES += howto/using-signed-tag-in-pull-request @@ -31,7 +32,6 @@ SP_ARTICLES += howto/separating-topic-branches SP_ARTICLES += howto/revert-a-faulty-merge SP_ARTICLES += howto/recover-corrupted-blob-object SP_ARTICLES += howto/rebuild-from-update-hook -SP_ARTICLES += howto/rebuild-from-update-hook SP_ARTICLES += howto/rebase-from-internal-branch SP_ARTICLES += howto/maintain-git API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) @@ -331,7 +331,7 @@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml howto-index.txt: howto-index.sh $(wildcard howto/*.txt) $(QUIET_GEN)$(RM) $@+ $@ && \ - '$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \ + '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \ mv $@+ $@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt diff --git a/Documentation/RelNotes/1.8.0.2.txt b/Documentation/RelNotes/1.8.0.2.txt new file mode 100644 index 000000000..8497e051d --- /dev/null +++ b/Documentation/RelNotes/1.8.0.2.txt @@ -0,0 +1,34 @@ +Git v1.8.0.2 Release Notes +========================== + +Fixes since v1.8.0.1 +-------------------- + + * Various codepaths have workaround for a common misconfiguration to + spell "UTF-8" as "utf8", but it was not used uniformly. Most + notably, mailinfo (which is used by "git am") lacked this support. + + * We failed to mention a file without any content change but whose + permission bit was modified, or (worse yet) a new file without any + content in the "git diff --stat" output. + + * When "--stat-count" hides a diffstat for binary contents, the total + number of added and removed lines at the bottom was computed + incorrectly. + + * When "--stat-count" hides a diffstat for unmerged paths, the total + number of affected files at the bottom of the "diff --stat" output + was computed incorrectly. + + * "diff --shortstat" miscounted the total number of affected files + when there were unmerged paths. + + * "git p4" used to try expanding malformed "$keyword$" that spans + across multiple lines. + + * "git update-ref -d --deref SYM" to delete a ref through a symbolic + ref that points to it did not remove it correctly. + + * Syntax highlighting in "gitweb" was not quite working. + +Also contains other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.8.0.3.txt b/Documentation/RelNotes/1.8.0.3.txt new file mode 100644 index 000000000..92b1e4b36 --- /dev/null +++ b/Documentation/RelNotes/1.8.0.3.txt @@ -0,0 +1,14 @@ +Git v1.8.0.3 Release Notes +========================== + +Fixes since v1.8.0.2 +-------------------- + + * "git log -p -S<string>" did not apply the textconv filter while + looking for the <string>. + + * In the documentation, some invalid example e-mail addresses were + formatted into mailto: links. + +Also contains many documentation updates backported from the 'master' +branch that is preparing for the upcoming 1.8.1 release. diff --git a/Documentation/RelNotes/1.8.1.txt b/Documentation/RelNotes/1.8.1.txt index 34c5b2697..d6f955592 100644 --- a/Documentation/RelNotes/1.8.1.txt +++ b/Documentation/RelNotes/1.8.1.txt @@ -19,7 +19,7 @@ variable in this release. "git branch --set-upstream" is deprecated and may be removed in a relatively distant future. "git branch [-u|--set-upstream-to]" has -been introduced with a saner order of arguments. +been introduced with a saner order of arguments to replace it. Updates since v1.8.0 @@ -27,22 +27,24 @@ Updates since v1.8.0 UI, Workflows & Features - * Command-line completion for tcsh has been added. + * Command-line completion scripts for tcsh and zsh have been added. - * We used to have a workaround for a bug in ancient "less" that - causes it to exit without any output when the terminal is resized. - The bug has been fixed in "less" version 406 (June 2007), and the - workaround has been removed in this release. + * "git-prompt" scriptlet (in contrib/completion) can be told to paint + pieces of the hints in the prompt string in colors. * Some documentation pages that used to ship only in the plain text format are now formatted in HTML as well. - * "git-prompt" scriptlet (in contrib/completion) can be told to paint - pieces of the hints in the prompt string in colors. + * We used to have a workaround for a bug in ancient "less" that + causes it to exit without any output when the terminal is resized. + The bug has been fixed in "less" version 406 (June 2007), and the + workaround has been removed in this release. - * A new configuration variable "diff.context" can be used to - give the default number of context lines in the patch output, to - override the hardcoded default of 3 lines. + * When "git checkout" checks out a branch, it tells the user how far + behind (or ahead) the new branch is relative to the remote tracking + branch it builds upon. The message now also advises how to sync + them up by pushing or pulling. This can be disabled with the + advice.statusHints configuration variable. * "git config --get" used to diagnose presence of multiple definitions of the same variable in the same configuration file as @@ -51,20 +53,43 @@ UI, Workflows & Features API regression but it is expected that nobody will notice it in practice. + * A new configuration variable "diff.context" can be used to + give the default number of context lines in the patch output, to + override the hardcoded default of 3 lines. + * "git format-patch" learned the "--notes=<ref>" option to give notes for the commit after the three-dash lines in its output. + * "git log -p -S<string>" now looks for the <string> after applying + the textconv filter (if defined); earlier it inspected the contents + of the blobs without filtering. + * "git log --grep=<pcre>" learned to honor the "grep.patterntype" configuration set to "perl". - * "git replace -d <object>" now interprets <object>, instead of only - accepting full hex object name. + * "git replace -d <object>" now interprets <object> as an extended + SHA-1 (e.g. HEAD~4 is allowed), instead of only accepting full hex + object name. * "git rm $submodule" used to punt on removing a submodule working tree to avoid losing the repository embedded in it. Because recent git uses a mechanism to separate the submodule repository from the submodule working tree, "git rm" learned to detect this - case and removes the submodule working tree when it is safe. + case and removes the submodule working tree when it is safe to do so. + + * "git send-email" used to prompt for the sender address, even when + the committer identity is well specified (e.g. via user.name and + user.email configuration variables). The command no longer gives + this prompt when not necessary. + + * "git send-email" did not allow non-address garbage strings to + appear after addresses on Cc: lines in the patch files (and when + told to pick them up to find more recipients), e.g. + + Cc: Stable Kernel <stable@k.org> # for v3.2 and up + + The command now strips " # for v3.2 and up" part before adding the + remainder of this line to the list of recipients. * "git submodule add" learned to add a new submodule at the same path as the path where an unrelated submodule was bound to in an @@ -77,7 +102,7 @@ UI, Workflows & Features * "git symbolic-ref" learned the "-d $symref" option to delete the named symbolic ref, which is more intuitive way to spell it than - "update-ref -d --no-deref". + "update-ref -d --no-deref $symref". Foreign Interface @@ -88,15 +113,24 @@ Foreign Interface * The remote helper interface to interact with subversion repositories (one of the GSoC 2012 projects) has been merged. + * A new remote-helper interface for Mercurial has been added to + contrib/remote-helpers. + + * The documentation for git(1) was pointing at a page at an external + site for the list of authors that no longer existed. The link has + been updated to point at an alternative site. + Performance, Internal Implementation, etc. * Compilation on Cygwin with newer header files are supported now. - * The logic to generate the initial advertisement from - "upload-pack" (what is invoked by "git fetch" on the other side - of the connection) to list what refs are available in the - repository has been optimized. + * A couple of low-level implementation updates on MinGW. + + * The logic to generate the initial advertisement from "upload-pack" + (i.e. what is invoked by "git fetch" on the other side of the + connection) to list what refs are available in the repository has + been optimized. * The logic to find set of attributes that match a given path has been optimized. @@ -118,55 +152,44 @@ details). * The configuration parser had an unnecessary hardcoded limit on variable names that was not checked consistently. - (merge 0971e99 bw/config-lift-variable-name-length-limit later to maint). * The "say" function in the test scaffolding incorrectly allowed "echo" to interpret "\a" as if it were a C-string asking for a BEL output. - (merge 7bc0911 jc/test-say-color-avoid-echo-escape later to maint). * "git mergetool" feeds /dev/null as a common ancestor when dealing with an add/add conflict, but p4merge backend cannot handle it. Work it around by passing a temporary empty file. - (merge 3facc60 da/mergetools-p4 later to maint). * "git log -F -E --grep='<ere>'" failed to use the given <ere> pattern as extended regular expression, and instead looked for the string literally. - (merge 727b6fc jc/grep-pcre-loose-ends~1 later to maint). * "git grep -e pattern <tree>" asked the attribute system to read "<tree>:.gitattributes" file in the working tree, which was nonsense. - (merge 55c6168 nd/grep-true-path later to maint). * A symbolic ref refs/heads/SYM was not correctly removed with "git branch -d SYM"; the command removed the ref pointed by SYM instead. - (merge 13baa9f rs/branch-del-symref later to maint). * Update "remote tracking branch" in the documentation to "remote-tracking branch". - (merge a6d3bde mm/maint-doc-remote-tracking later to maint). * "git pull --rebase" run while the HEAD is detached tried to find the upstream branch of the detached HEAD (which by definition does not exist) and emitted unnecessary error messages. - (merge e980765 ph/pull-rebase-detached later to maint). * The refs/replace hierarchy was not mentioned in the repository-layout docs. - (merge 11fbe18 po/maint-refs-replace-docs later to maint). * Various rfc2047 quoting issues around a non-ASCII name on the From: line in the output from format-patch have been corrected. - (merge 25dc8da js/format-2047 later to maint). * Sometimes curl_multi_timeout() function suggested a wrong timeout value when there is no file descriptor to wait on and the http transport ended up sleeping for minutes in select(2) system call. A workaround has been added for this. - (merge 7202b81 sz/maint-curl-multi-timeout later to maint). * For a fetch refspec (or the result of applying wildcard on one), we always want the RHS to map to something inside "refs/" @@ -175,7 +198,6 @@ details). * "git diff -G<pattern>" did not honor textconv filter when looking for changes. - (merge b1c2f57 jk/maint-diff-grep-textconv later to maint). * Some HTTP servers ask for auth only during the actual packing phase (not in ls-remote phase); this is not really a recommended @@ -185,27 +207,35 @@ details). * "git p4" used to try expanding malformed "$keyword$" that spans across multiple lines. - (merge 6b2bf41 pw/maint-p4-rcs-expansion-newline later to maint). * Syntax highlighting in "gitweb" was not quite working. - (merge 048b399 rh/maint-gitweb-highlight-ext later to maint). * RSS feed from "gitweb" had a xss hole in its title output. - (merge 0f0ecf6 jk/maint-gitweb-xss later to maint). * "git config --path $key" segfaulted on "[section] key" (a boolean "true" spelled without "=", not "[section] key = true"). - (merge 962c38e cn/config-missing-path later to maint). * "git checkout -b foo" while on an unborn branch did not say "Switched to a new branch 'foo'" like other cases. - (merge afa8c07 jk/checkout-out-of-unborn later to maint). + + * Various codepaths have workaround for a common misconfiguration to + spell "UTF-8" as "utf8", but it was not used uniformly. Most + notably, mailinfo (which is used by "git am") lacked this support. * We failed to mention a file without any content change but whose permission bit was modified, or (worse yet) a new file without any content in the "git diff --stat" output. - (merge 74faaa1 lt/diff-stat-show-0-lines later to maint). + + * When "--stat-count" hides a diffstat for binary contents, the total + number of added and removed lines at the bottom was computed + incorrectly. + + * When "--stat-count" hides a diffstat for unmerged paths, the total + number of affected files at the bottom of the "diff --stat" output + was computed incorrectly. + + * "diff --shortstat" miscounted the total number of affected files + when there were unmerged paths. * "update-ref -d --deref SYM" to delete a ref through a symbolic ref that points to it did not remove it correctly. - (merge b274a71 jh/update-ref-d-through-symref later to maint). diff --git a/Documentation/RelNotes/1.8.2.txt b/Documentation/RelNotes/1.8.2.txt new file mode 100644 index 000000000..6c85bf4f0 --- /dev/null +++ b/Documentation/RelNotes/1.8.2.txt @@ -0,0 +1,106 @@ +Git v1.8.2 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the upcoming major release (tentatively called 1.8.2), we will +change the behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this. + + +Updates since v1.8.1 +-------------------- + +UI, Workflows & Features + + * Initial ports to QNX and z/OS UNIX System Services have started. + + * Output from the tests is coloured using "green is okay, yellow is + questionable, red is bad and blue is informative" scheme. + +Foreign Interface + + * + +Performance, Internal Implementation, etc. + + * + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.8.1 +------------------ + +Unless otherwise noted, all the fixes since v1.8.1 in the maintenance +track are contained in this release (see release notes to them for +details). + + * An element on GIT_CEILING_DIRECTORIES list that does not name the + real path to a directory (i.e. a symbolic link) could have caused + the GIT_DIR discovery logic to escape the ceiling. + (merge 059b379 mh/ceiling later to maint). + + * t4014, t9502 and t0200 tests had various portability issues that + broke on OpenBSD. + (merge 27f6342 jc/maint-test-portability later to maint). + + * t9020 and t3600 tests had various portability issues. + (merge 5a02966 jc/test-portability later to maint). + + * t9200 runs "cvs init" on a directory that already exists, but a + platform can configure this fail for the current user (e.g. you + need to be in the cvsadmin group on NetBSD 6.0). + (merge 8666df0 jc/test-cvs-no-init-in-existing-dir later to maint). + + * The behaviour visible to the end users was confusing, when they + attempt to kill a process spawned in the editor that was in turn + launched by Git with SIGINT (or SIGQUIT), as Git would catch that + signal and die. We ignore these signals now. + (merge 1250857 pf/editor-ignore-sigint later to maint). + + * After failing to create a temporary file using mkstemp(), failing + pathname was not reported correctly on some platforms. + (merge f7be59b jc/mkstemp-more-careful-error-reporting later to maint). + + * The way "git svn" asked for password using SSH_ASKPASS and + GIT_ASKPASS was not in line with the rest of the system. + (merge e9263e4 ss/svn-prompt later to maint). + + * The --graph code fell into infinite loop when asked to do what the + code did not expect. + (merge 656197a mk/maint-graph-infinity-loop later to maint). + + * http transport was wrong to ask for the username when the + authentication is done by certificate identity. + (merge 75e9a40 rb/http-cert-cred-no-username-prompt later to maint). + + * "git pack-refs" that ran in parallel to another process that + created new refs had a nasty race. + (merge b3f1280 jk/repack-ref-racefix later to maint). + + * After "git add -N" and then writing a tree object out of the + index, the cache-tree data structure got corrupted. + (merge eec3e7e nd/invalidate-i-t-a-cache-tree later to maint). + + * "gitweb", when sorting by age to show repositories with new + activities first, used to sort repositories with absolutely + nothing in it early, which was not very useful. + (merge 28dae18 md/gitweb-sort-by-age later to maint). + + * When a line to be wrapped has a solid run of non space characters + whose length exactly is the wrap width, "git shortlog -w" failed + to add a newline after such a line. + (merge e0db176 sp/shortlog-missing-lf later to maint). + + * Some shells do not behave correctly when IFS is unset; work it + around by explicitly setting it to the default value. + (merge 393050c jc/maint-fbsd-sh-ifs-workaround later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3d8b2fe4d..75935d500 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -9,6 +9,14 @@ Checklist (and a short version for the impatient): - the first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and should skip the full stop + - it is also conventional in most cases to prefix the + first line with "area: " where the area is a filename + or identifier for the general area of the code being + modified, e.g. + . archive: ustar header checksum is computed unsigned + . git-cherry-pick.txt: clarify the use of revision range notation + (if in doubt which identifier to use, run "git log --no-merges" + on the files you are modifying to see the current conventions) - the body should provide a meaningful commit message, which: . explains the problem the change tries to solve, iow, what is wrong with the current code without the change. @@ -119,19 +127,6 @@ in templates/hooks--pre-commit. To help ensure this does not happen, run git diff --check on your changes before you commit. -(1a) Try to be nice to older C compilers - -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. - -Also, variables have to be declared at the beginning of the block -(you can check this with gcc, using the -Wdeclaration-after-statement -option). - -Another thing: NULL pointers shall be written as NULL, not as 0. - - (2) Generate your patch using git tools out of your commits. git based diff tools generate unidiff which is the preferred format. diff --git a/Documentation/config.txt b/Documentation/config.txt index 3a44fd78a..53c4ca1d7 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -140,10 +140,11 @@ advice.*:: can tell Git that you do not need help by setting these to 'false': + -- - pushNonFastForward:: + pushUpdateRejected:: Set this variable to 'false' if you want to disable - 'pushNonFFCurrent', 'pushNonFFDefault', and - 'pushNonFFMatching' simultaneously. + 'pushNonFFCurrent', 'pushNonFFDefault', + 'pushNonFFMatching', and 'pushAlreadyExists' + simultaneously. pushNonFFCurrent:: Advice shown when linkgit:git-push[1] fails due to a non-fast-forward update to the current branch. @@ -158,11 +159,15 @@ advice.*:: 'matching refs' explicitly (i.e. you used ':', or specified a refspec that isn't your current branch) and it resulted in a non-fast-forward error. + pushAlreadyExists:: + Shown when linkgit:git-push[1] rejects an update that + does not qualify for fast-forwarding (e.g., a tag.) statusHints:: Show directions on how to proceed from the current - state in the output of linkgit:git-status[1] and in + state in the output of linkgit:git-status[1], in the template shown when writing commit messages in - linkgit:git-commit[1]. + linkgit:git-commit[1], and in the help message shown + by linkgit:git-checkout[1] when switching branch. commitBeforeMerge:: Advice shown when linkgit:git-merge[1] refuses to merge to avoid overwriting local changes. @@ -1516,6 +1521,14 @@ mailmap.file:: subdirectory, or somewhere outside of the repository itself. See linkgit:git-shortlog[1] and linkgit:git-blame[1]. +mailmap.blob:: + Like `mailmap.file`, but consider the value as a reference to a + blob in the repository. If both `mailmap.file` and + `mailmap.blob` are given, both are parsed, with entries from + `mailmap.file` taking precedence. In a bare repository, this + defaults to `HEAD:.mailmap`. In a non-bare repository, it + defaults to empty. + man.viewer:: Specify the programs that may be used to display help in the 'man' format. See linkgit:git-help[1]. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 89dd63467..4314ad0fb 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -57,8 +57,8 @@ diff.statGraphWidth:: to all commands generating --stat output except format-patch. diff.context:: - Generate diffs with <n> lines of context instead of the default of - 3. This value is overridden by the -U option. + Generate diffs with <n> lines of context instead of the default + of 3. This value is overridden by the -U option. diff.external:: If this config variable is set, diff generation is not diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index f4f7e250c..39f2c5074 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -309,7 +309,11 @@ endif::git-log[] index (i.e. amount of addition/deletions compared to the file's size). For example, `-M90%` means git should consider a delete/add pair to be a rename if more than 90% of the file - hasn't changed. + hasn't changed. Without a `%` sign, the number is to be read as + a fraction, with a decimal point before it. I.e., `-M5` becomes + 0.5, and is thus the same as `-M50%`. Similarly, `-M05` is + the same as `-M5%`. To limit detection to exact renames, use + `-M100%`. -C[<n>]:: --find-copies[=<n>]:: diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index b4d6476ac..6e98bdf14 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -57,14 +57,11 @@ endif::git-pull[] ifndef::git-pull[] -t:: --tags:: - Most of the tags are fetched automatically as branch - heads are downloaded, but tags that do not point at - objects reachable from the branch heads that are being - tracked will not be fetched by this mechanism. This - flag lets all tags and their associated objects be - downloaded. The default behavior for a remote may be - specified with the remote.<name>.tagopt setting. See - linkgit:git-config[1]. + This is a short-hand for giving "refs/tags/*:refs/tags/*" + refspec from the command line, to ask all tags to be fetched + and stored locally. Because this acts as an explicit + refspec, the default refspecs (configured with the + remote.$name.fetch variable) are overridden and not used. --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 7958a4700..6f04d22f5 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -21,18 +21,34 @@ or the specified tree. If no paths are given, 'git checkout' will also update `HEAD` to set the specified branch as the current branch. -'git checkout' [<branch>]:: +'git checkout' <branch>:: + To prepare for working on <branch>, switch to it by updating + the index and the files in the working tree, and by pointing + HEAD at the branch. Local modifications to the files in the + working tree are kept, so that they can be committed to the + <branch>. ++ +If <branch> is not found but there does exist a tracking branch in +exactly one remote (call it <remote>) with a matching name, treat as +equivalent to ++ +------------ +$ git checkout -b <branch> --track <remote>/<branch> +------------ ++ +You could omit <branch>, in which case the command degenerates to +"check out the current branch", which is a glorified no-op with a +rather expensive side-effects to show only the tracking information, +if exists, for the current branch. + 'git checkout' -b|-B <new_branch> [<start point>]:: -'git checkout' [--detach] [<commit>]:: - This form switches branches by updating the index, working - tree, and HEAD to reflect the specified branch or commit. -+ -If `-b` is given, a new branch is created as if linkgit:git-branch[1] -were called and then checked out; in this case you can -use the `--track` or `--no-track` options, which will be passed to -'git branch'. As a convenience, `--track` without `-b` implies branch -creation; see the description of `--track` below. + Specifying `-b` causes a new branch to be created as if + linkgit:git-branch[1] were called and then checked out. In + this case you can use the `--track` or `--no-track` options, + which will be passed to 'git branch'. As a convenience, + `--track` without `-b` implies branch creation; see the + description of `--track` below. + If `-B` is given, <new_branch> is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of @@ -45,6 +61,21 @@ $ git checkout <branch> that is to say, the branch is not reset/created unless "git checkout" is successful. +'git checkout' --detach [<branch>]:: +'git checkout' <commit>:: + + Prepare to work on top of <commit>, by detaching HEAD at it + (see "DETACHED HEAD" section), and updating the index and the + files in the working tree. Local modifications to the files + in the working tree are kept, so that the resulting working + tree will be the state recorded in the commit plus the local + modifications. ++ +Passing `--detach` forces this behavior in the case of a <branch> (without +the option, giving a branch name to the command would check out the branch, +instead of detaching HEAD at it), or the current commit, +if no <branch> is specified. + 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...:: When <paths> or `--patch` are given, 'git checkout' does *not* diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index f8d081911..f8c06013f 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git diff' [options] [<commit>] [--] [<path>...] 'git diff' [options] --cached [<commit>] [--] [<path>...] 'git diff' [options] <commit> <commit> [--] [<path>...] +'git diff' [options] <blob> <blob> 'git diff' [options] [--no-index] [--] <path> <path> DESCRIPTION @@ -55,6 +56,11 @@ directories. This behavior can be forced by --no-index. This is to view the changes between two arbitrary <commit>. +'git diff' [options] <blob> <blob>:: + + This form is to view the differences between the raw + contents of two blob objects. + 'git diff' [--options] <commit>..<commit> [--] [<path>...]:: This is synonymous to the previous form. If <commit> on @@ -72,8 +78,7 @@ directories. This behavior can be forced by --no-index. Just in case if you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the last two forms that use ".." notations, can be any -<tree>. The third form ('git diff <commit> <commit>') can also -be used to compare two <blob> objects. +<tree>. For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 959e4d3ae..68bca1a29 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -427,7 +427,7 @@ they made it. Here `<name>` is the person's display name (for example ``Com M Itter'') and `<email>` is the person's email address -(``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) +(``\cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) and greater-than (\x3e) symbols. These are required to delimit the email address from the other fields in the line. Note that `<name>` and `<email>` are free-form and may contain any sequence @@ -562,8 +562,12 @@ A `<path>` string must use UNIX-style directory separators (forward slash `/`), may contain any byte other than `LF`, and must not start with double quote (`"`). -If an `LF` or double quote must be encoded into `<path>` shell-style -quoting should be used, e.g. `"path/with\n and \" in it"`. +A path can use C-style string quoting; this is accepted in all cases +and mandatory if the filename starts with double quote or contains +`LF`. In C-style quoting, the complete name should be surrounded with +double quotes, and any `LF`, backslash, or double quote characters +must be escaped by preceding them with a backslash (e.g., +`"path/with\n, \\ and \" in it"`). The value of `<path>` must be in canonical form. That is it must not: diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 585dac40b..08a185db7 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -167,7 +167,7 @@ log.showroot:: `git log -p` output would be shown without a diff attached. The default is `true`. -mailmap.file:: +mailmap.*:: See linkgit:git-shortlog[1]. notes.displayRef:: diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 6d19d59ce..c964b796b 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -51,10 +51,11 @@ be named. If `:`<dst> is omitted, the same ref as <src> will be updated. + The object referenced by <src> is used to update the <dst> reference -on the remote side, but by default this is only allowed if the -update can fast-forward <dst>. By having the optional leading `+`, -you can tell git to update the <dst> ref even when the update is not a -fast-forward. This does *not* attempt to merge <src> into <dst>. See +on the remote side. By default this is only allowed if <dst> is not +a tag (annotated or lightweight), and then only if it can fast-forward +<dst>. By having the optional leading `+`, you can tell git to update +the <dst> ref even if it is not allowed by default (e.g., it is not a +fast-forward.) This does *not* attempt to merge <src> into <dst>. See EXAMPLES below for details. + `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. @@ -385,11 +386,23 @@ the ones in the examples below) can be configured as the default for A handy way to push the current branch to the same name on the remote. -`git push origin master:satellite/master dev:satellite/dev`:: +`git push mothership master:satellite/master dev:satellite/dev`:: Use the source ref that matches `master` (e.g. `refs/heads/master`) to update the ref that matches `satellite/master` (most probably - `refs/remotes/satellite/master`) in the `origin` repository, then + `refs/remotes/satellite/master`) in the `mothership` repository; do the same for `dev` and `satellite/dev`. ++ +This is to emulate `git fetch` run on the `mothership` using `git +push` that is run in the opposite direction in order to integrate +the work done on `satellite`, and is often necessary when you can +only make connection in one way (i.e. satellite can ssh into +mothership but mothership cannot initiate connection to satellite +because the latter is behind a firewall or does not run sshd). ++ +After running this `git push` on the `satellite` machine, you would +ssh into the `mothership` and run `git merge` there to complete the +emulation of `git pull` that were run on `mothership` to pull changes +made on `satellite`. `git push origin HEAD:master`:: Push the current branch to the remote ref matching `master` in the diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 5ce4cda8e..6d696e0f9 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -35,6 +35,37 @@ transport protocols, such as 'git-remote-http', 'git-remote-https', 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities 'fetch', 'option', and 'push'. +INVOCATION +---------- + +Remote helper programs are invoked with one or (optionally) two +arguments. The first argument specifies a remote repository as in git; +it is either the name of a configured remote or a URL. The second +argument specifies a URL; it is usually of the form +'<transport>://<address>', but any arbitrary string is possible. +The 'GIT_DIR' environment variable is set up for the remote helper +and can be used to determine where to store additional data or from +which directory to invoke auxiliary git commands. + +When git encounters a URL of the form '<transport>://<address>', where +'<transport>' is a protocol that it cannot handle natively, it +automatically invokes 'git remote-<transport>' with the full URL as +the second argument. If such a URL is encountered directly on the +command line, the first argument is the same as the second, and if it +is encountered in a configured remote, the first argument is the name +of that remote. + +A URL of the form '<transport>::<address>' explicitly instructs git to +invoke 'git remote-<transport>' with '<address>' as the second +argument. If such a URL is encountered directly on the command line, +the first argument is '<address>', and if it is encountered in a +configured remote, the first argument is the name of that remote. + +Additionally, when a configured remote has 'remote.<name>.vcs' set to +'<transport>', git explicitly invokes 'git remote-<transport>' with +'<name>' as the first argument. If set, the second argument is +'remote.<name>.url'; otherwise, the second argument is omitted. + INPUT FORMAT ------------ @@ -57,67 +88,17 @@ Each remote helper is expected to support only a subset of commands. The operations a helper supports are declared to git in the response to the `capabilities` command (see COMMANDS, below). -'option':: - For specifying settings like `verbosity` (how much output to - write to stderr) and `depth` (how much history is wanted in the - case of a shallow clone) that affect how other commands are - carried out. - -'connect':: - For fetching and pushing using git's native packfile protocol - that requires a bidirectional, full-duplex connection. - -'push':: - For listing remote refs and pushing specified objects from the - local object store to remote refs. - -'fetch':: - For listing remote refs and fetching the associated history to - the local object store. - -'import':: - For listing remote refs and fetching the associated history as - a fast-import stream. - -'refspec' <refspec>:: - This modifies the 'import' capability, allowing the produced - fast-import stream to modify refs in a private namespace - instead of writing to refs/heads or refs/remotes directly. - It is recommended that all importers providing the 'import' - capability use this. -+ -A helper advertising the capability -`refspec refs/heads/*:refs/svn/origin/branches/*` -is saying that, when it is asked to `import refs/heads/topic`, the -stream it outputs will update the `refs/svn/origin/branches/topic` -ref. -+ -This capability can be advertised multiple times. The first -applicable refspec takes precedence. The left-hand of refspecs -advertised with this capability must cover all refs reported by -the list command. If no 'refspec' capability is advertised, -there is an implied `refspec *:*`. - -'bidi-import':: - The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers - to retrieve information about blobs and trees that already exist in - fast-import's memory. This requires a channel from fast-import to the - remote-helper. - If it is advertised in addition to "import", git establishes a pipe from - fast-import to the remote-helper's stdin. - It follows that git and fast-import are both connected to the - remote-helper's stdin. Because git can send multiple commands to - the remote-helper it is required that helpers that use 'bidi-import' - buffer all 'import' commands of a batch before sending data to fast-import. - This is to prevent mixing commands and fast-import responses on the - helper's stdin. +In the following, we list all defined capabilities and for +each we list which commands a helper with that capability +must provide. Capabilities for Pushing -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ 'connect':: Can attempt to connect to 'git receive-pack' (for pushing), - 'git upload-pack', etc for communication using the - packfile protocol. + 'git upload-pack', etc for communication using + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. + Supported commands: 'connect'. @@ -127,16 +108,26 @@ Supported commands: 'connect'. + Supported commands: 'list for-push', 'push'. -If a helper advertises both 'connect' and 'push', git will use -'connect' if possible and fall back to 'push' if the helper requests -so when connecting (see the 'connect' command under COMMANDS). +'export':: + Can discover remote refs and push specified objects from a + fast-import stream to remote refs. ++ +Supported commands: 'list for-push', 'export'. + +If a helper advertises 'connect', git will use it if possible and +fall back to another capability if the helper requests so when +connecting (see the 'connect' command under COMMANDS). +When choosing between 'push' and 'export', git prefers 'push'. +Other frontends may have some other order of preference. + Capabilities for Fetching -~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^ 'connect':: Can try to connect to 'git upload-pack' (for fetching), 'git receive-pack', etc for communication using the - packfile protocol. + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. + Supported commands: 'connect'. @@ -158,14 +149,27 @@ connecting (see the 'connect' command under COMMANDS). When choosing between 'fetch' and 'import', git prefers 'fetch'. Other frontends may have some other order of preference. +Miscellaneous capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +'option':: + For specifying settings like `verbosity` (how much output to + write to stderr) and `depth` (how much history is wanted in the + case of a shallow clone) that affect how other commands are + carried out. + 'refspec' <refspec>:: - This modifies the 'import' capability. + This modifies the 'import' capability, allowing the produced + fast-import stream to modify refs in a private namespace + instead of writing to refs/heads or refs/remotes directly. + It is recommended that all importers providing the 'import' + capability use this. + -A helper advertising +A helper advertising the capability `refspec refs/heads/*:refs/svn/origin/branches/*` -in its capabilities is saying that, when it handles -`import refs/heads/topic`, the stream it outputs will update the -`refs/svn/origin/branches/topic` ref. +is saying that, when it is asked to `import refs/heads/topic`, the +stream it outputs will update the `refs/svn/origin/branches/topic` +ref. + This capability can be advertised multiple times. The first applicable refspec takes precedence. The left-hand of refspecs @@ -173,36 +177,33 @@ advertised with this capability must cover all refs reported by the list command. If no 'refspec' capability is advertised, there is an implied `refspec *:*`. -INVOCATION ----------- +'bidi-import':: + This modifies the 'import' capability. + The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers + to retrieve information about blobs and trees that already exist in + fast-import's memory. This requires a channel from fast-import to the + remote-helper. + If it is advertised in addition to "import", git establishes a pipe from + fast-import to the remote-helper's stdin. + It follows that git and fast-import are both connected to the + remote-helper's stdin. Because git can send multiple commands to + the remote-helper it is required that helpers that use 'bidi-import' + buffer all 'import' commands of a batch before sending data to fast-import. + This is to prevent mixing commands and fast-import responses on the + helper's stdin. -Remote helper programs are invoked with one or (optionally) two -arguments. The first argument specifies a remote repository as in git; -it is either the name of a configured remote or a URL. The second -argument specifies a URL; it is usually of the form -'<transport>://<address>', but any arbitrary string is possible. -The 'GIT_DIR' environment variable is set up for the remote helper -and can be used to determine where to store additional data or from -which directory to invoke auxiliary git commands. +'export-marks' <file>:: + This modifies the 'export' capability, instructing git to dump the + internal marks table to <file> when complete. For details, + read up on '--export-marks=<file>' in linkgit:git-fast-export[1]. + +'import-marks' <file>:: + This modifies the 'export' capability, instructing git to load the + marks specified in <file> before processing any input. For details, + read up on '--import-marks=<file>' in linkgit:git-fast-export[1]. -When git encounters a URL of the form '<transport>://<address>', where -'<transport>' is a protocol that it cannot handle natively, it -automatically invokes 'git remote-<transport>' with the full URL as -the second argument. If such a URL is encountered directly on the -command line, the first argument is the same as the second, and if it -is encountered in a configured remote, the first argument is the name -of that remote. -A URL of the form '<transport>::<address>' explicitly instructs git to -invoke 'git remote-<transport>' with '<address>' as the second -argument. If such a URL is encountered directly on the command line, -the first argument is '<address>', and if it is encountered in a -configured remote, the first argument is the name of that remote. -Additionally, when a configured remote has 'remote.<name>.vcs' set to -'<transport>', git explicitly invokes 'git remote-<transport>' with -'<name>' as the first argument. If set, the second argument is -'remote.<name>.url'; otherwise, the second argument is omitted. COMMANDS -------- @@ -212,9 +213,11 @@ Commands are given by the caller on the helper's standard input, one per line. 'capabilities':: Lists the capabilities of the helper, one per line, ending with a blank line. Each capability may be preceded with '*', - which marks them mandatory for git version using the remote - helper to understand (unknown mandatory capability is fatal - error). + which marks them mandatory for git versions using the remote + helper to understand. Any unknown mandatory capability is a + fatal error. ++ +Support for this command is mandatory. 'list':: Lists the refs, one per line, in the format "<value> <name> @@ -224,9 +227,20 @@ Commands are given by the caller on the helper's standard input, one per line. the name; unrecognized attributes are ignored. The list ends with a blank line. + -If 'push' is supported this may be called as 'list for-push' -to obtain the current refs prior to sending one or more 'push' -commands to the helper. +See REF LIST ATTRIBUTES for a list of currently defined attributes. ++ +Supported if the helper has the "fetch" or "import" capability. + +'list for-push':: + Similar to 'list', except that it is used if and only if + the caller wants to the resulting ref list to prepare + push commands. + A helper supporting both push and fetch can use this + to distinguish for which operation the output of 'list' + is going to be used, possibly reducing the amount + of work that needs to be performed. ++ +Supported if the helper has the "push" or "export" capability. 'option' <name> <value>:: Sets the transport helper option <name> to <value>. Outputs a @@ -236,6 +250,8 @@ commands to the helper. for it). Options should be set before other commands, and may influence the behavior of those commands. + +See OPTIONS for a list of currently defined options. ++ Supported if the helper has the "option" capability. 'fetch' <sha1> <name>:: @@ -244,7 +260,7 @@ Supported if the helper has the "option" capability. per line, terminated with a blank line. Outputs a single blank line when all fetch commands in the same batch are complete. Only objects which were reported - in the ref list with a sha1 may be fetched this way. + in the output of 'list' with a sha1 may be fetched this way. + Optionally may output a 'lock <file>' line indicating a file under GIT_DIR/objects/pack which is keeping a pack until refs can be @@ -305,7 +321,23 @@ sequence has to be buffered before starting to send data to fast-import to prevent mixing of commands and fast-import responses on the helper's stdin. + -Supported if the helper has the 'import' capability. +Supported if the helper has the "import" capability. + +'export':: + Instructs the remote helper that any subsequent input is + part of a fast-import stream (generated by 'git fast-export') + containing objects which should be pushed to the remote. ++ +Especially useful for interoperability with a foreign versioning +system. ++ +The 'export-marks' and 'import-marks' capabilities, if specified, +affect this command in so far as they are passed on to 'git +fast-export', which then will load/store a table of marks for +local objects. This can be used to implement for incremental +operations. ++ +Supported if the helper has the "export" capability. 'connect' <service>:: Connects to given service. Standard input and standard output @@ -332,10 +364,9 @@ capabilities reported by the helper. REF LIST ATTRIBUTES ------------------- -'for-push':: - The caller wants to use the ref list to prepare push - commands. A helper might chose to acquire the ref list by - opening a different type of connection to the destination. +The 'list' command produces a list of refs in which each ref +may be followed by a list of attributes. The following ref list +attributes are defined. 'unchanged':: This ref is unchanged since the last import or fetch, although @@ -343,6 +374,10 @@ REF LIST ATTRIBUTES OPTIONS ------- + +The following options are defined and (under suitable circumstances) +set by git if the remote helper has the 'option' capability. + 'option verbosity' <n>:: Changes the verbosity of messages displayed by the helper. A value of 0 for <n> means that processes operate diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt index 2a67d456a..612a625ce 100644 --- a/Documentation/git-remote-testgit.txt +++ b/Documentation/git-remote-testgit.txt @@ -19,7 +19,7 @@ testcase for the remote-helper functionality, and as an example to show remote-helper authors one possible implementation. The best way to learn more is to read the comments and source code in -'git-remote-testgit.py'. +'git-remote-testgit'. SEE ALSO -------- diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 0aa4e20ea..711ffe17a 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -144,7 +144,7 @@ drop [-q|--quiet] [<stash>]:: Remove a single stashed state from the stash list. When no `<stash>` is given, it removes the latest one. i.e. `stash@{0}`, otherwise - `<stash>` must a valid stash log reference of the form + `<stash>` must be a valid stash log reference of the form `stash@{<revision>}`. create:: diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 8b0d3adfe..69decb13b 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -628,10 +628,19 @@ ADVANCED OPTIONS Default: "svn" --follow-parent:: + This option is only relevant if we are tracking branches (using + one of the repository layout options --trunk, --tags, + --branches, --stdlayout). For each tracked branch, try to find + out where its revision was copied from, and set + a suitable parent in the first git commit for the branch. This is especially helpful when we're tracking a directory - that has been moved around within the repository, or if we - started tracking a branch and never tracked the trunk it was - descended from. This feature is enabled by default, use + that has been moved around within the repository. If this + feature is disabled, the branches created by 'git svn' will all + be linear and not share any history, meaning that there will be + no information on where branches were branched off or merged. + However, following long/convoluted histories can take a long + time, so disabling this feature may speed up the cloning + process. This feature is enabled by default, use --no-follow-parent to disable it. + [verse] @@ -739,7 +748,8 @@ for rewriteRoot and rewriteUUID which can be used together. BASIC EXAMPLES -------------- -Tracking and contributing to the trunk of a Subversion-managed project: +Tracking and contributing to the trunk of a Subversion-managed project +(ignoring tags and branches): ------------------------------------------------------------------------ # Clone a repo (like git clone): @@ -764,8 +774,10 @@ Tracking and contributing to an entire Subversion-managed project (complete with a trunk, tags and branches): ------------------------------------------------------------------------ -# Clone a repo (like git clone): - git svn clone http://svn.example.com/project -T trunk -b branches -t tags +# Clone a repo with standard SVN directory layout (like git clone): + git svn clone http://svn.example.com/project --stdlayout +# Or, if the repo uses a non-standard directory layout: + git svn clone http://svn.example.com/project -T tr -b branch -t tag # View all branches and tags you have cloned: git branch -r # Create a new branch in SVN @@ -830,6 +842,52 @@ inside git back upstream to SVN users. Therefore it is advised that users keep history as linear as possible inside git to ease compatibility with SVN (see the CAVEATS section below). +HANDLING OF SVN BRANCHES +------------------------ +If 'git svn' is configured to fetch branches (and --follow-branches +is in effect), it sometimes creates multiple git branches for one +SVN branch, where the addtional branches have names of the form +'branchname@nnn' (with nnn an SVN revision number). These additional +branches are created if 'git svn' cannot find a parent commit for the +first commit in an SVN branch, to connect the branch to the history of +the other branches. + +Normally, the first commit in an SVN branch consists +of a copy operation. 'git svn' will read this commit to get the SVN +revision the branch was created from. It will then try to find the +git commit that corresponds to this SVN revision, and use that as the +parent of the branch. However, it is possible that there is no suitable +git commit to serve as parent. This will happen, among other reasons, +if the SVN branch is a copy of a revision that was not fetched by 'git +svn' (e.g. because it is an old revision that was skipped with +'--revision'), or if in SVN a directory was copied that is not tracked +by 'git svn' (such as a branch that is not tracked at all, or a +subdirectory of a tracked branch). In these cases, 'git svn' will still +create a git branch, but instead of using an existing git commit as the +parent of the branch, it will read the SVN history of the directory the +branch was copied from and create appropriate git commits. This is +indicated by the message "Initializing parent: <branchname>". + +Additionally, it will create a special branch named +'<branchname>@<SVN-Revision>', where <SVN-Revision> is the SVN revision +number the branch was copied from. This branch will point to the newly +created parent commit of the branch. If in SVN the branch was deleted +and later recreated from a different version, there will be multiple +such branches with an '@'. + +Note that this may mean that multiple git commits are created for a +single SVN revision. + +An example: in an SVN repository with a standard +trunk/tags/branches layout, a directory trunk/sub is created in r.100. +In r.200, trunk/sub is branched by copying it to branches/. 'git svn +clone -s' will then create a branch 'sub'. It will also create new git +commits for r.100 through r.199 and use these as the history of branch +'sub'. Thus there will be two git commits for each revision from r.100 +to r.199 (one containing trunk/, one containing trunk/sub/). Finally, +it will create a branch 'sub@200' pointing to the new parent commit of +branch 'sub' (i.e. the commit for r.200 and trunk/sub/). + CAVEATS ------- @@ -871,6 +929,21 @@ already dcommitted. It is considered bad practice to --amend commits you've already pushed to a remote repository for other users, and dcommit with SVN is analogous to that. +When cloning an SVN repository, if none of the options for describing +the repository layout is used (--trunk, --tags, --branches, +--stdlayout), 'git svn clone' will create a git repository with +completely linear history, where branches and tags appear as separate +directories in the working copy. While this is the easiest way to get a +copy of a complete repository, for projects with many branches it will +lead to a working copy many times larger than just the trunk. Thus for +projects using the standard directory structure (trunk/branches/tags), +it is recommended to clone with option '--stdlayout'. If the project +uses a non-standard structure, and/or if branches and tags are not +required, it is easiest to only clone one directory (typically trunk), +without giving any repository layout options. If the full history with +branches and tags is required, the options '--trunk' / '--branches' / +'--tags' must be used. + When using multiple --branches or --tags, 'git svn' does not automatically handle name collisions (for example, if two branches from different paths have the same name, or if a branch and a tag have the same name). In these cases, @@ -894,6 +967,12 @@ the possible corner cases (git doesn't do it, either). Committing renamed and copied files is fully supported if they're similar enough for git to detect them. +In SVN, it is possible (though discouraged) to commit changes to a tag +(because a tag is just a directory copy, thus technically the same as a +branch). When cloning an SVN repository, 'git svn' cannot know if such a +commit to a tag will happen in the future. Thus it acts conservatively +and imports all SVN tags as branches, prefixing the tag name with 'tags/'. + CONFIGURATION ------------- diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 247534e90..6470cffd3 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -129,7 +129,7 @@ This option is only applicable when listing tags without annotation lines. CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your -committer identity (of the form "Your Name <your@email.address>") to +committer identity (of the form "Your Name <\your@email.address>") to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows: diff --git a/Documentation/git.txt b/Documentation/git.txt index cbe088353..05c0b942b 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,16 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.8.0.1/git.html[documentation for release 1.8.0.1] +* link:v1.8.1/git.html[documentation for release 1.8.1] * release notes for + link:RelNotes/1.8.1.txt[1.8.1]. + +* link:v1.8.0.3/git.html[documentation for release 1.8.0.3] + +* release notes for + link:RelNotes/1.8.0.3.txt[1.8.0.3], + link:RelNotes/1.8.0.2.txt[1.8.0.2], link:RelNotes/1.8.0.1.txt[1.8.0.1], link:RelNotes/1.8.0.txt[1.8.0]. @@ -421,6 +428,11 @@ help ...`. Do not use replacement refs to replace git objects. See linkgit:git-replace[1] for more information. +--literal-pathspecs:: + Treat pathspecs literally, rather than as glob patterns. This is + equivalent to setting the `GIT_LITERAL_PATHSPECS` environment + variable to `1`. + GIT COMMANDS ------------ @@ -649,6 +661,7 @@ git so take care if using Cogito etc. If the 'GIT_DIR' environment variable is set then it specifies a path to use instead of the default `.git` for the base of the repository. + The '--git-dir' command-line option also sets this value. 'GIT_WORK_TREE':: Set the path to the working tree. The value will not be @@ -788,6 +801,16 @@ for further details. as a file path and will try to write the trace messages into it. +GIT_LITERAL_PATHSPECS:: + Setting this variable to `1` will cause git to treat all + pathspecs literally, rather than as glob patterns. For example, + running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search + for commits that touch the path `*.c`, not any paths that the + glob `*.c` matches. You might want this if you are feeding + literal paths to git (e.g., paths previously given to you by + `git ls-tree`, `--raw` diff output, etc). + + Discussion[[Discussion]] ------------------------ @@ -868,8 +891,10 @@ Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the git mailing list -<git@vger.kernel.org>. For a more complete list of contributors, see -http://git-scm.com/about. If you have a clone of git.git itself, the +<git@vger.kernel.org>. http://www.ohloh.net/p/git/contributors/summary +gives you a more complete list of contributors. + +If you have a clone of git.git itself, the output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you the authors for specific parts of the project. diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt new file mode 100644 index 000000000..36502f671 --- /dev/null +++ b/Documentation/howto/new-command.txt @@ -0,0 +1,104 @@ +From: Eric S. Raymond <esr@thyrsus.com> +Abstract: This is how-to documentation for people who want to add extension + commands to git. It should be read alongside api-builtin.txt. +Content-type: text/asciidoc + +How to integrate new subcommands +================================ + +This is how-to documentation for people who want to add extension +commands to git. It should be read alongside api-builtin.txt. + +Runtime environment +------------------- + +git subcommands are standalone executables that live in the git exec +path, normally /usr/lib/git-core. The git executable itself is a +thin wrapper that knows where the subcommands live, and runs them by +passing command-line arguments to them. + +(If "git foo" is not found in the git exec path, the wrapper +will look in the rest of your $PATH for it. Thus, it's possible +to write local git extensions that don't live in system space.) + +Implementation languages +------------------------ + +Most subcommands are written in C or shell. A few are written in +Perl. + +While we strongly encourage coding in portable C for portability, +these specific scripting languages are also acceptable. We won't +accept more without a very strong technical case, as we don't want +to broaden the git suite's required dependencies. Import utilities, +surgical tools, remote helpers and other code at the edges of the +git suite are more lenient and we allow Python (and even Tcl/tk), +but they should not be used for core functions. + +This may change in the future. Especially Python is not allowed in +core because we need better Python integration in the git Windows +installer before we can be confident people in that environment +won't experience an unacceptably large loss of capability. + +C commands are normally written as single modules, named after the +command, that link a collection of functions called libgit. Thus, +your command 'git-foo' would normally be implemented as a single +"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main +binary); this organization makes it easy for people reading the code +to find things. + +See the CodingGuidelines document for other guidance on what we consider +good practice in C and shell, and api-builtin.txt for the support +functions available to built-in commands written in C. + +What every extension command needs +---------------------------------- + +You must have a man page, written in asciidoc (this is what git help +followed by your subcommand name will display). Be aware that there is +a local asciidoc configuration and macros which you should use. It's +often helpful to start by cloning an existing page and replacing the +text content. + +You must have a test, written to report in TAP (Test Anything Protocol). +Tests are executables (usually shell scripts) that live in the 't' +subdirectory of the tree. Each test name begins with 't' and a sequence +number that controls where in the test sequence it will be executed; +conventionally the rest of the name stem is that of the command +being tested. + +Read the file t/README to learn more about the conventions to be used +in writing tests, and the test support library. + +Integrating a command +--------------------- + +Here are the things you need to do when you want to merge a new +subcommand into the git tree. + +1. Don't forget to sign off your patch! + +2. Append your command name to one of the variables BUILTIN_OBJS, +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON. + +3. Drop its test in the t directory. + +4. If your command is implemented in an interpreted language with a +p-code intermediate form, make sure .gitignore in the main directory +includes a pattern entry that ignores such files. Python .pyc and +.pyo files will already be covered. + +5. If your command has any dependency on a particular version of +your language, document it in the INSTALL file. + +6. There is a file command-list.txt in the distribution main directory +that categorizes commands by type, so they can be listed in appropriate +subsections in the documentation's summary command list. Add an entry +for yours. To understand the categories, look at git-cmmands.txt +in the main directory. + +7. Give the maintainer one paragraph to include in the RelNotes file +to describe the new feature; a good place to do so is in the cover +letter [PATCH 0/n]. + +That's all there is to it. diff --git a/Documentation/mailmap.txt b/Documentation/mailmap.txt index 288f04e70..4a8c27652 100644 --- a/Documentation/mailmap.txt +++ b/Documentation/mailmap.txt @@ -1,5 +1,6 @@ If the file `.mailmap` exists at the toplevel of the repository, or at -the location pointed to by the mailmap.file configuration option, it +the location pointed to by the mailmap.file or mailmap.blob +configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses. @@ -46,7 +47,7 @@ Jane Doe <jane@desktop.(none)> Joe R. Developer <joe@example.com> ------------ -Note how there is no need for an entry for <jane@laptop.(none)>, because the +Note how there is no need for an entry for `<jane@laptop.(none)>`, because the real name of that author is already correct. Example 2: Your repository contains commits from the following diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index d9eddedc7..105f18a6f 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -144,7 +144,11 @@ The placeholders are: - '%Cgreen': switch color to green - '%Cblue': switch color to blue - '%Creset': reset color -- '%C(...)': color specification, as described in color.branch.* config option +- '%C(...)': color specification, as described in color.branch.* config option; + adding `auto,` at the beginning will emit color only when colors are + enabled for log output (by `color.diff`, `color.ui`, or `--color`, and + respecting the `auto` settings of the former if we are going to a + terminal) - '%m': left, right or boundary mark - '%n': newline - '%%': a raw '%' diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt index d6fc90ac7..18142b6d2 100644 --- a/Documentation/technical/api-history-graph.txt +++ b/Documentation/technical/api-history-graph.txt @@ -33,11 +33,11 @@ The following utility functions are wrappers around `graph_next_line()` and They can all be called with a NULL graph argument, in which case no graph output will be printed. -* `graph_show_commit()` calls `graph_next_line()` until it returns non-zero. - This prints all graph lines up to, and including, the line containing this - commit. Output is printed to stdout. The last line printed does not contain - a terminating newline. This should not be called if the commit line has - already been printed, or it will loop forever. +* `graph_show_commit()` calls `graph_next_line()` and + `graph_is_commit_finished()` until one of them return non-zero. This prints + all graph lines up to, and including, the line containing this commit. + Output is printed to stdout. The last line printed does not contain a + terminating newline. * `graph_show_oneline()` calls `graph_next_line()` and prints the result to stdout. The line printed does not contain a terminating newline. diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt index af7cc2e39..730cfacf7 100644 --- a/Documentation/technical/api-index-skel.txt +++ b/Documentation/technical/api-index-skel.txt @@ -11,5 +11,3 @@ documents them. //////////////////////////////////////////////////////////////// // table of contents end //////////////////////////////////////////////////////////////// - -2007-11-24 diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 7386bcab3..20be34883 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -82,14 +82,6 @@ Functions call free() on the util members of any items that have to be deleted. Preserve the order of the items that are retained. -`string_list_longest_prefix`:: - - Return the longest string within a string_list that is a - prefix (in the sense of prefixcmp()) of the specified string, - or NULL if no such prefix exists. This function does not - require the string_list to be sorted (it does a linear - search). - `print_string_list`:: Dump a string_list to stdout, useful mainly for debugging purposes. It diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 57d6f915b..732415483 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -161,8 +161,9 @@ GIT index format this span of index as a tree. An entry can be in an invalidated state and is represented by having - -1 in the entry_count field. In this case, there is no object name - and the next entry starts immediately after the newline. + a negative number in the entry_count field. In this case, there is no + object name and the next entry starts immediately after the newline. + When writing an invalid entry, -1 should always be used as entry_count. The entries are written out in the top-down, depth-first order. The first entry represents the root level of the repository, followed by the |