diff options
Diffstat (limited to 'Documentation')
38 files changed, 864 insertions, 186 deletions
diff --git a/Documentation/RelNotes/1.7.6.1.txt b/Documentation/RelNotes/1.7.6.1.txt index 95905e48f8..42e46ab17f 100644 --- a/Documentation/RelNotes/1.7.6.1.txt +++ b/Documentation/RelNotes/1.7.6.1.txt @@ -12,6 +12,8 @@ Fixes since v1.7.6 though the actual error was that "unexecutable" was found but did not have a proper she-bang line to be executed. + * Error exits from $PAGER were silently ignored. + * "git checkout -b <branch>" was confused when attempting to create a branch whose name ends with "-g" followed by hexadecimal digits, and refused to work. @@ -21,9 +23,16 @@ Fixes since v1.7.6 * "git diff --cc" learned to correctly ignore binary files. + * "git diff -c/--cc" mishandled a deletion that resolves a conflict, and + looked in the working tree instead. + * "git fast-export" forgot to quote pathnames with unsafe characters in its output. + * "git fetch" over smart-http transport used to abort when the + repository was updated between the initial connection and the + subsequent object transfer. + * "git fetch" did not recurse into submodules in subdirectories. * "git ls-tree" did not error out when asked to show a corrupt tree. @@ -31,6 +40,8 @@ Fixes since v1.7.6 * "git pull" without any argument left an extra whitespace after the command name in its reflog. + * "git push --quiet" was not really quiet. + * "git rebase -i -p" incorrectly dropped commits from side branches. * "git reset [<commit>] paths..." did not reset the index entry correctly diff --git a/Documentation/RelNotes/1.7.6.2.txt b/Documentation/RelNotes/1.7.6.2.txt new file mode 100644 index 0000000000..67ae414965 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.2.txt @@ -0,0 +1,8 @@ +Git v1.7.6.2 Release Notes +========================== + +Fixes since v1.7.6.1 +-------------------- + + * v1.7.6.1 broke "git push --quiet"; it used to be a no-op against an old + version of Git running on the other end, but v1.7.6.1 made it abort. diff --git a/Documentation/RelNotes/1.7.6.3.txt b/Documentation/RelNotes/1.7.6.3.txt new file mode 100644 index 0000000000..95971831b9 --- /dev/null +++ b/Documentation/RelNotes/1.7.6.3.txt @@ -0,0 +1,24 @@ +Git v1.7.6.3 Release Notes +========================== + +Fixes since v1.7.6.2 +-------------------- + + * "git -c var=value subcmd" misparsed the custom configuration when + value contained an equal sign. + + * "git fetch" had a major performance regression, wasting many + needless cycles in a repository where there is no submodules + present. This was especially bad, when there were many refs. + + * "git reflog $refname" did not default to the "show" subcommand as + the documentation advertised the command to do. + + * "git reset" did not leave meaningful log message in the reflog. + + * "git status --ignored" did not show ignored items when there is no + untracked items. + + * "git tag --contains $commit" was unnecessarily inefficient. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.6.4.txt b/Documentation/RelNotes/1.7.6.4.txt new file mode 100644 index 0000000000..e19acac2da --- /dev/null +++ b/Documentation/RelNotes/1.7.6.4.txt @@ -0,0 +1,32 @@ +Git v1.7.6.4 Release Notes +========================== + +Fixes since v1.7.6.3 +-------------------- + + * The error reporting logic of "git am" when the command is fed a file + whose mail-storage format is unknown was fixed. + + * "git branch --set-upstream @{-1} foo" did not expand @{-1} correctly. + + * "git check-ref-format --print" used to parrot a candidate string that + began with a slash (e.g. /refs/heads/master) without stripping it, to make + the result a suitably normalized string the caller can append to "$GIT_DIR/". + + * "git clone" failed to clone locally from a ".git" file that itself + is not a directory but is a pointer to one. + + * "git clone" from a local repository that borrows from another + object store using a relative path in its objects/info/alternates + file did not adjust the alternates in the resulting repository. + + * "git describe --dirty" did not refresh the index before checking the + state of the working tree files. + + * "git ls-files ../$path" that is run from a subdirectory reported errors + incorrectly when there is no such path that matches the given pathspec. + + * "git mergetool" could loop forever prompting when nothing can be read + from the standard input. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.7.txt b/Documentation/RelNotes/1.7.7.txt index 28214e2721..7655cccfaa 100644 --- a/Documentation/RelNotes/1.7.7.txt +++ b/Documentation/RelNotes/1.7.7.txt @@ -8,7 +8,7 @@ Updates since v1.7.6 * Interix, Cygwin and Minix ports got updated. - * A handful of patches to update git-p4 (in contrib/). + * Various updates to git-p4 (in contrib/), fast-import, and git-svn. * Gitweb learned to read from /etc/gitweb-common.conf when it exists, before reading from gitweb_config.perl or from /etc/gitweb.conf @@ -19,65 +19,97 @@ Updates since v1.7.6 functions can compress or uncompress more than 4GB data in one call on platforms with 64-bit long, which has been corrected. - * "git am" learned to pass "--exclude=<path>" option through to underlying + * Git now recognizes loose objects written by other implementations that + use a non-standard window size for zlib deflation (e.g. Agit running on + Android with 4kb window). We used to reject anything that was not + deflated with 32kb window. + + * Interaction between the use of pager and coloring of the output has + been improved, especially when a command that is not built-in was + involved. + + * "git am" learned to pass the "--exclude=<path>" option through to underlying "git apply". - * You can now feed many empty lines before feeding a mbox file to + * You can now feed many empty lines before feeding an mbox file to "git am". * "git archive" can be told to pass the output to gzip compression and produce "archive.tar.gz". - * "git bisect" can be used in a bare repository (provided if the test + * "git bisect" can be used in a bare repository (provided that the test you perform per each iteration does not need a working tree, of course). + * The length of abbreviated object names in "git branch -v" output + now honors the core.abbrev configuration variable. + * "git check-attr" can take relative paths from the command line. - * "git check-attr" learned "--all" option to list the attributes for a + * "git check-attr" learned an "--all" option to list the attributes for a given path. * "git checkout" (both the code to update the files upon checking out a - different branch, the code to checkout specific set of files) learned + different branch and the code to checkout a specific set of files) learned to stream the data from object store when possible, without having to - read the entire contents of a file in memory first. An earlier round + read the entire contents of a file into memory first. An earlier round of this code that is not in any released version had a large leak but now it has been plugged. - * "git clone" can now take "--config key=value" option to set the + * "git clone" can now take a "--config key=value" option to set the repository configuration options that affect the initial checkout. * "git commit <paths>..." now lets you feed relative pathspecs that - refer outside your current subdirectory. + refer to outside your current subdirectory. - * "git diff --stat" learned --stat-count option to limit the output of - diffstat report. + * "git diff --stat" learned a --stat-count option to limit the output of + a diffstat report. - * "git diff" learned "--histogram" option, to use a different diff + * "git diff" learned a "--histogram" option to use a different diff generation machinery stolen from jgit, which might give better performance. + * "git diff" had a weird worst case behaviour that can be triggered + when comparing files with potentially many places that could match. + * "git fetch", "git push" and friends no longer show connection - errors for addresses that couldn't be connected when at least one + errors for addresses that couldn't be connected to when at least one address succeeds (this is arguably a regression but a deliberate one). - * "git grep" learned --break and --heading options, to let users mimic - output format of "ack". + * "git grep" learned "--break" and "--heading" options, to let users mimic + the output format of "ack". - * "git grep" learned "-W" option that shows wider context using the same + * "git grep" learned a "-W" option that shows wider context using the same logic used by "git diff" to determine the hunk header. + * Invoking the low-level "git http-fetch" without "-a" option (which + git itself never did---normal users should not have to worry about + this) is now deprecated. + + * The "--decorate" option to "git log" and its family learned to + highlight grafted and replaced commits. + * "git rebase master topci" no longer spews usage hints after giving - "fatal: no such branch: topci" error message. + the "fatal: no such branch: topci" error message. - * "git stash" learned --include-untracked option. + * The recursive merge strategy implementation got a fairly large + fix for many corner cases that may rarely happen in real world + projects (it has been verified that none of the 16000+ merges in + the Linux kernel history back to v2.6.12 is affected with the + corner case bugs this update fixes). + + * "git stash" learned an "--include-untracked option". * "git submodule update" used to stop at the first error updating a submodule; it now goes on to update other submodules that can be updated, and reports the ones with errors at the end. - * "git upload-pack" and "git receive-pack" learned to pretend only a + * "git push" can be told with the "--recurse-submodules=check" option to + refuse pushing of the supermodule, if any of its submodules' + commits hasn't been pushed out to their remotes. + + * "git upload-pack" and "git receive-pack" learned to pretend that only a subset of the refs exist in a repository. This may help a site to put many tiny repositories into one repository (this would not be useful for larger repositories as repacking would be problematic). @@ -86,7 +118,7 @@ Updates since v1.7.6 that is more efficient in reading objects in packfiles. * test scripts for gitweb tried to run even when CGI-related perl modules - are not installed; it now exits early when they are unavailable. + are not installed; they now exit early when the latter are unavailable. Also contains various documentation updates and minor miscellaneous changes. @@ -95,28 +127,8 @@ changes. Fixes since v1.7.6 ------------------ -Unless otherwise noted, all the fixes in 1.7.6.X maintenance track are +Unless otherwise noted, all fixes in the 1.7.6.X maintenance track are included in this release. - * Error exits from $PAGER were silently ignored. - (merge fc1b56f cb/maint-exec-error-report later). - - * "git diff -c/--cc" mishandled a deletion that resolves a conflict, and - looked in the working tree instead. - (merge 9969454 jc/maint-combined-diff-work-tree later). - - * "git fetch" over smart-http transport used to abort when the - repository was updated between the initial connection and the - subsequent object transfer. - (merge 051e400 jc/maint-smart-http-race-upload-pack later). - - * "git push --quiet" was not really quiet. - (merge 0d086b8 cb/maint-quiet-push later). - --- -exec >/var/tmp/1 -echo O=$(git describe master) -O=v1.7.6-548-g324b6b1 -git log --first-parent --oneline $O..master -echo -git shortlog --no-merges ^maint ^$O master + * "git branch -m" and "git checkout -b" incorrectly allowed the tip + of the branch that is currently checked out updated. diff --git a/Documentation/RelNotes/1.7.8.txt b/Documentation/RelNotes/1.7.8.txt new file mode 100644 index 0000000000..3c247cc231 --- /dev/null +++ b/Documentation/RelNotes/1.7.8.txt @@ -0,0 +1,107 @@ +Git v1.7.8 Release Notes (draft) +================================ + +Updates since v1.7.7 +-------------------- + + * The build procedure has been taught to take advantage of computed + dependency automatically when the complier supports it. + + * The date parser now accepts timezone designators that lack minutes + part and also has a colon between "hh:mm". + + * "git am" learned how to read from patches generated by Hg. + + * "git branch" learned an explicit --list option to ask for branches + listed, optionally with a glob matching pattern to limit its output. + + * "git check-attr" learned "--cached" option to look at .gitattributes + files from the index, not from the working tree. + + * Variants of "git cherry-pick" and "git revert" that take multiple + commits learned to "--continue". + + * "git fetch" learned to honor transfer.fsckobjects configuration to + validate the objects that were received from the other end, just like + "git receive-pack" (the receiving end of "git push") does. + + * "git fetch" makes sure that the set of objects it received from the + other end actually completes the history before updating the refs. + "git receive-pack" (the receiving end of "git push") learned to do the + same. + + * "git for-each-ref" learned "%(contents:subject)", "%(contents:body)" + and "%(contents:signature)". The last one is useful for signed tags. + + * "git ls-remote" learned to respond to "-h"(elp) requests. + + * "git send-email" learned to respond to "-h"(elp) requests. + + * "git stash" learned "--include-untracked" option to stash away + untracked/ignored cruft from the working tree. + + * "mediawiki" remote helper can interact with (surprise!) MediaWiki + with "git fetch" & "git push". + + * "gitweb" leaked unescaped control characters from syntax hiliter + outputs. + + +Fixes since v1.7.7 +------------------ + +Unless otherwise noted, all fixes in the 1.7.7.X maintenance track are +included in this release. + + * "git diff $tree $path" used to apply the pathspec at the output stage, + reading the whole tree, wasting resources. + (merge 2f88c1970 jc/diff-index-unpack later to maint). + + * The code to check for updated submodules during a "git fetch" of the + superproject had an unnecessary quadratic loop. + (merge 6859de45 jk/maint-fetch-submodule-check-fix later to maint). + + * "git fetch" from a large bundle did not enable the progress output. + (merge be042aff jc/maint-bundle-too-quiet later to maint). + + * When "git fsck --lost-and-found" found that an empty blob object in the + object store is unreachable, it incorrectly reported an error after + writing the lost blob out successfully. + (merge eb726f2d jc/maint-fsck-fwrite-size-check later to maint). + + * "git filter-branch" did not refresh the index before checking that the + working tree was clean. + (merge 5347a50f jk/filter-branch-require-clean-work-tree later to maint). + + * "git grep $tree" when run with multiple threads had an unsafe access to + the object database that should have been protected with mutex. + (merge 8cb5775b2 nm/grep-object-sha1-lock later to maint). + + * The "--ancestry-path" option to "git log" and friends misbehaved in a + history with complex criss-cross merges and showed an uninteresting + side history as well. + (merge c05b988a6 bk/ancestry-path later to maint). + + * "git merge" did not understand ":/<pattern>" as a way to name a commit. + + * Tests with --valgrind failed to find "mergetool" scriptlets. + (merge ee0d7bf92 tr/mergetool-valgrind later to maint). + + * "git patch-id" miscomputed the patch-id in a patch that has a line longer + than 1kB. + (merge b9ab810b ms/patch-id-with-overlong-line later to maint). + + * When an "exec" insn failed after modifying the index and/or the working + tree during "rebase -i", we now check and warn that the changes need to + be cleaned up. + (merge 1686519a mm/rebase-i-exec-edit later to maint). + +--- +it=master +exec >/var/tmp/1 +O=v1.7.7 +O=v1.7.7-137-g2e49dab +echo O=$(git describe --always $it) +git log --first-parent --oneline --reverse ^$O $it +echo +git shortlog --no-merges ^$O $it diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 938eccf2a5..0dbf2c9843 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -134,8 +134,7 @@ 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 (git, Cogito, and StGIT included) generate -unidiff which is the preferred format. +git based diff tools generate unidiff which is the preferred format. You do not have to be afraid to use -M option to "git diff" or "git format-patch", if your patch involves file renames. The diff --git a/Documentation/config.txt b/Documentation/config.txt index 0658ffb889..03296b7eb8 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -147,7 +147,7 @@ advice.*:: core.fileMode:: If false, the executable bit differences between the index and - the working copy are ignored; useful on broken filesystems like FAT. + the working tree are ignored; useful on broken filesystems like FAT. See linkgit:git-update-index[1]. + The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] @@ -179,7 +179,7 @@ is created. core.trustctime:: If false, the ctime differences between the index and the - working copy are ignored; useful when the inode change time + working tree are ignored; useful when the inode change time is regularly modified by something outside Git (file system crawlers and some backup systems). See linkgit:git-update-index[1]. True by default. @@ -292,7 +292,7 @@ core.ignoreStat:: If true, commands which modify both the working tree and the index will mark the updated paths with the "assume unchanged" bit in the index. These marked files are then assumed to stay unchanged in the - working copy, until you mark them otherwise manually - Git will not + working tree, until you mark them otherwise manually - Git will not detect the file changes by lstat() calls. This is useful on systems where those are very slow, such as Microsoft Windows. See linkgit:git-update-index[1]. @@ -857,6 +857,13 @@ fetch.recurseSubmodules:: when its superproject retrieves a commit that updates the submodule's reference. +fetch.fsckObjects:: + If it is set to true, git-fetch-pack will check all fetched + objects. It will abort in the case of a malformed object or a + broken link. The result of an abort are only dangling objects. + Defaults to false. If not set, the value of `transfer.fsckObjects` + is used instead. + fetch.unpackLimit:: If the number of objects fetched over the git native transfer is below this @@ -1453,7 +1460,8 @@ notes.rewriteRef:: You may also specify this configuration several times. + Does not have a default value; you must configure this variable to -enable note rewriting. +enable note rewriting. Set it to `refs/notes/commits` to enable +rewriting for the default commit notes. + This setting can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable, which must be a colon separated list of refs or @@ -1595,7 +1603,8 @@ receive.fsckObjects:: If it is set to true, git-receive-pack will check all received objects. It will abort in the case of a malformed object or a broken link. The result of an abort are only dangling objects. - Defaults to false. + Defaults to false. If not set, the value of `transfer.fsckObjects` + is used instead. receive.unpackLimit:: If the number of objects received in a push is below this @@ -1830,6 +1839,11 @@ tar.umask:: archiving user's umask will be used instead. See umask(2) and linkgit:git-archive[1]. +transfer.fsckObjects:: + When `fetch.fsckObjects` or `receive.fsckObjects` are + not set, the value of this variable is used instead. + Defaults to false. + transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are not set, the value of this variable is used instead. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index c50f189827..f46013c91f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git branch' [--color[=<when>] | --no-color] [-r | -a] - [-v [--abbrev=<length> | --no-abbrev]] - [(--merged | --no-merged | --contains) [<commit>]] + [--list] [-v [--abbrev=<length> | --no-abbrev]] + [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> 'git branch' (-d | -D) [-r] <branchname>... @@ -20,7 +20,11 @@ DESCRIPTION With no arguments, existing branches are listed and the current branch will be highlighted with an asterisk. Option `-r` causes the remote-tracking -branches to be listed, and option `-a` shows both. +branches to be listed, and option `-a` shows both. This list mode is also +activated by the `--list` option (see below). +<pattern> restricts the output to matching branches, the pattern is a shell +wildcard (i.e., matched using fnmatch(3)) +Multiple patterns may be given; if any of them matches, the tag is shown. With `--contains`, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the @@ -64,6 +68,7 @@ way to clean up all obsolete remote-tracking branches. OPTIONS ------- -d:: +--delete:: Delete a branch. The branch must be fully merged in its upstream branch, or in `HEAD` if no upstream was set with `--track` or `--set-upstream`. @@ -72,6 +77,7 @@ OPTIONS Delete a branch irrespective of its merged status. -l:: +--create-reflog:: Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@\{yesterday}". @@ -84,6 +90,7 @@ OPTIONS already. Without `-f` 'git branch' refuses to change an existing branch. -m:: +--move:: Move/rename a branch and the corresponding reflog. -M:: @@ -100,20 +107,28 @@ OPTIONS Same as `--color=never`. -r:: +--remotes:: List or delete (if used with -d) the remote-tracking branches. -a:: +--all:: List both remote-tracking branches and local branches. +--list:: + Activate the list mode. `git branch <pattern>` would try to create a branch, + use `git branch --list <pattern>` to list matching branches. + -v:: --verbose:: - Show sha1 and commit subject line for each head, along with + When in list mode, + show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print the name of the upstream branch, as well. --abbrev=<length>:: Alter the sha1's minimum display length in the output listing. - The default value is 7. + The default value is 7 and can be overridden by the `core.abbrev` + config option. --no-abbrev:: Display the full sha1s in the output listing rather than abbreviating them. diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 1f7312a189..5abdbaa51c 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -24,6 +24,9 @@ OPTIONS paths. If this option is used, then 'unspecified' attributes will not be included in the output. +--cached:: + Consider `.gitattributes` in the index only, ignoring the working tree. + --stdin:: Read file names from stdin instead of from the command-line. diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 7cfa3d92ac..2660a842fc 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -9,6 +9,8 @@ SYNOPSIS -------- [verse] 'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>... +'git cherry-pick' --reset +'git cherry-pick' --continue DESCRIPTION ----------- @@ -110,6 +112,10 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. +SEQUENCER SUBCOMMANDS +--------------------- +include::sequencer.txt[] + EXAMPLES -------- `git cherry-pick master`:: diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 974e04ef1a..79fb984144 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -47,12 +47,14 @@ OPTIONS -e <pattern>:: --exclude=<pattern>:: - Specify special exceptions to not be cleaned. Each <pattern> is - the same form as in $GIT_DIR/info/excludes and this option can be - given multiple times. + In addition to those found in .gitignore (per directory) and + $GIT_DIR/info/exclude, also consider these patterns to be in the + set of the ignore rules in effect. -x:: - Don't use the ignore rules. This allows removing all untracked + Don't use the standard ignore rules read from .gitignore (per + directory) and $GIT_DIR/info/exclude, but do still use the ignore + rules given with `-e` options. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with 'git reset') to create a pristine working directory to test a clean build. diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index ebd13be72e..69a1e4af9e 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -93,14 +93,14 @@ OPTIONS Listen on an alternative port. Incompatible with '--inetd' option. --init-timeout=<n>:: - Timeout between the moment the connection is established and the - client request is received (typically a rather low value, since + Timeout (in seconds) between the moment the connection is established + and the client request is received (typically a rather low value, since that should be basically immediate). --timeout=<n>:: - Timeout for specific client sub-requests. This includes the time - it takes for the server to process the sub-request and the time spent - waiting for the next client's request. + Timeout (in seconds) for specific client sub-requests. This includes + the time it takes for the server to process the sub-request and the + time spent waiting for the next client's request. --max-connections=<n>:: Maximum number of concurrent clients, defaults to 32. Set it to diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 2969388880..ec6ef31197 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -425,8 +425,8 @@ Here `<name>` is the person's display name (for example (``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>` is free-form and may contain any sequence of bytes, except -`LT` and `LF`. It is typically UTF-8 encoded. +`<name>` and `<email>` are free-form and may contain any sequence +of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded. The time of the change is specified by `<when>` using the date format that was selected by the \--date-format=<fmt> command line option. @@ -1012,10 +1012,14 @@ force:: (see OPTIONS, above). import-marks:: +import-marks-if-exists:: Like --import-marks except in two respects: first, only one - "feature import-marks" command is allowed per stream; - second, an --import-marks= command-line option overrides - any "feature import-marks" command in the stream. + "feature import-marks" or "feature import-marks-if-exists" + command is allowed per stream; second, an --import-marks= + or --import-marks-if-exists command-line option overrides + any of these "feature" commands in the stream; third, + "feature import-marks-if-exists" like a corresponding + command-line option silently skips a nonexistent file. cat-blob:: ls:: diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 152e695c81..c872b883ba 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -101,9 +101,10 @@ Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. -The first line of the message in a commit and tag object is -`subject`, the remaining lines are `body`. The whole message -is `contents`. +The complete message in a commit and tag object is `contents`. +Its first line is `contents:subject`, the remaining lines +are `contents:body` and the optional GPG signature +is `contents:signature`. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index d13c9b23f7..6ea9be775c 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -166,15 +166,22 @@ will want to ensure that threading is disabled for `git send-email`. --to=<email>:: Add a `To:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. + The negated form `--no-to` discards all `To:` headers added so + far (from config or command line). --cc=<email>:: Add a `Cc:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. + The negated form `--no-cc` discards all `Cc:` headers added so + far (from config or command line). --add-header=<header>:: Add an arbitrary header to the email headers. This is in addition to any configured headers, and may be used multiple times. - For example, `--add-header="Organization: git-foo"` + For example, `--add-header="Organization: git-foo"`. + The negated form `--no-add-header` discards *all* (`To:`, + `Cc:`, and custom) headers added so far from config or command + line. --cover-letter:: In addition to the patches, generate a cover letter file diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 4d42073867..070cd1e6ed 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -15,6 +15,9 @@ DESCRIPTION ----------- Downloads a remote git repository via HTTP. +*NOTE*: use of this command without -a is deprecated. The -a +behaviour will become the default in a future release. + OPTIONS ------- commit-id:: diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 6c934660d7..249fc878ec 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -69,10 +69,13 @@ produced by --stat etc. its size is not included. [\--] <path>...:: - Show only commits that affect any of the specified paths. To - prevent confusion with options and branch names, paths may need - to be prefixed with "\-- " to separate them from options or - refnames. + Show only commits that are enough to explain how the files + that match the specified paths came to be. See "History + Simplification" below for details and other simplification + modes. ++ +To prevent confusion with options and branch names, paths may need to +be prefixed with "\-- " to separate them from options or refnames. include::rev-list-options.txt[] diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 6a187f2e23..e8319eac69 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -142,8 +142,9 @@ OPTIONS -C <object>:: --reuse-message=<object>:: - Take the note message from the given blob object (for - example, another note). + Take the given blob object (for example, another note) as the + note message. (Use `git notes copy <object>` instead to + copy notes between objects.) -c <object>:: --reedit-message=<object>:: @@ -285,6 +286,8 @@ $ blob=$(git hash-object -w a.out) $ git notes --ref=built add -C "$blob" HEAD ------------ +(You cannot simply use `git notes --ref=built add -F a.out HEAD` +because that is not binary-safe.) Of course, it doesn't make much sense to display non-text-format notes with 'git log', so if you use such notes, you'll probably need to write some special-purpose tools to do something useful with them. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 49c6e9fa51..aede48877f 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -162,6 +162,12 @@ useful if you write an alias or script around 'git push'. is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. +--recurse-submodules=check:: + Check whether all submodule commits used by the revisions to be + pushed are available on a remote tracking branch. Otherwise the + push will be aborted and the command will exit with non-zero status. + + include::urls-remotes.txt[] OUTPUT diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index c45d53c6e1..1bd0317a42 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -47,7 +47,7 @@ OPTIONS -i:: Usually a merge requires the index file as well as the - files in the working tree are up to date with the + files in the working tree to be up to date with the current head commit, in order not to lose local changes. This flag disables the check with the working tree and is meant to be used when creating a merge of @@ -71,21 +71,21 @@ OPTIONS --aggressive:: Usually a three-way merge by 'git read-tree' resolves the merge for really trivial cases and leaves other - cases unresolved in the index, so that Porcelains can + cases unresolved in the index, so that porcelains can implement different merge policies. This flag makes the - command to resolve a few more cases internally: + command resolve a few more cases internally: + * when one side removes a path and the other side leaves the path unmodified. The resolution is to remove that path. * when both sides remove a path. The resolution is to remove that path. -* when both sides adds a path identically. The resolution +* when both sides add a path identically. The resolution is to add that path. --prefix=<prefix>/:: Keep the current index contents, and read the contents - of named tree-ish under directory at `<prefix>`. The + of the named tree-ish under the directory at `<prefix>`. The original index file cannot have anything at the path - `<prefix>` itself, and have nothing in `<prefix>/` + `<prefix>` itself, nor anything in the `<prefix>/` directory. Note that the `<prefix>/` value must end with a slash. @@ -379,36 +379,36 @@ have finished your work-in-progress), attempt the merge again. Sparse checkout --------------- -"Sparse checkout" allows to sparsely populate working directory. -It uses skip-worktree bit (see linkgit:git-update-index[1]) to tell -Git whether a file on working directory is worth looking at. +"Sparse checkout" allows populating the working directory sparsely. +It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell +Git whether a file in the working directory is worth looking at. -"git read-tree" and other merge-based commands ("git merge", "git -checkout"...) can help maintaining skip-worktree bitmap and working +'git read-tree' and other merge-based commands ('git merge', 'git +checkout'...) can help maintaining the skip-worktree bitmap and working directory update. `$GIT_DIR/info/sparse-checkout` is used to -define the skip-worktree reference bitmap. When "git read-tree" needs -to update working directory, it will reset skip-worktree bit in index +define the skip-worktree reference bitmap. When 'git read-tree' needs +to update the working directory, it resets the skip-worktree bit in the index based on this file, which uses the same syntax as .gitignore files. -If an entry matches a pattern in this file, skip-worktree will be -set on that entry. Otherwise, skip-worktree will be unset. +If an entry matches a pattern in this file, skip-worktree will not be +set on that entry. Otherwise, skip-worktree will be set. Then it compares the new skip-worktree value with the previous one. If -skip-worktree turns from unset to set, it will add the corresponding -file back. If it turns from set to unset, that file will be removed. +skip-worktree turns from set to unset, it will add the corresponding +file back. If it turns from unset to set, that file will be removed. While `$GIT_DIR/info/sparse-checkout` is usually used to specify what -files are in. You can also specify what files are _not_ in, using -negate patterns. For example, to remove file "unwanted": +files are in, you can also specify what files are _not_ in, using +negate patterns. For example, to remove the file `unwanted`: ---------------- * !unwanted ---------------- -Another tricky thing is fully repopulating working directory when you +Another tricky thing is fully repopulating the working directory when you no longer want sparse checkout. You cannot just disable "sparse -checkout" because skip-worktree are still in the index and you working -directory is still sparsely populated. You should re-populate working +checkout" because skip-worktree bits are still in the index and your working +directory is still sparsely populated. You should re-populate the working directory with the `$GIT_DIR/info/sparse-checkout` file content as follows: @@ -416,8 +416,8 @@ follows: * ---------------- -Then you can disable sparse checkout. Sparse checkout support in "git -read-tree" and similar commands is disabled by default. You need to +Then you can disable sparse checkout. Sparse checkout support in 'git +read-tree' and similar commands is disabled by default. You need to turn `core.sparseCheckout` on in order to have sparse checkout support. diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index a3a1d8eea3..b1f7dc643a 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository SYNOPSIS -------- [verse] -'git-receive-pack' [--quiet] <directory> +'git-receive-pack' <directory> DESCRIPTION ----------- @@ -35,9 +35,6 @@ are not fast-forwards. OPTIONS ------- ---quiet:: - Print only error messages. - <directory>:: The repository to sync into. diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 4f83dea5a3..674797cd83 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -24,22 +24,141 @@ output. Because a remote helper runs as an independent process from git, there is no need to re-link git to add a new helper, nor any need to link the helper with the implementation of git. -Every helper must support the "capabilities" command, which git will -use to determine what other commands the helper will accept. Other -commands generally concern facilities like discovering and updating -remote refs, transporting objects between the object database and -the remote repository, and updating the local object store. - -Helpers supporting the 'fetch' capability can discover refs from the -remote repository and transfer objects reachable from those refs to -the local object store. Helpers supporting the 'push' capability can -transfer local objects to the remote repository and update remote refs. +Every helper must support the "capabilities" command, which git +uses to determine what other commands the helper will accept. Those +other commands can be used to discover and update remote refs, +transport objects between the object database and the remote repository, +and update the local object store. Git comes with a "curl" family of remote helpers, that handle various 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'. +INPUT FORMAT +------------ + +Git sends the remote helper a list of commands on standard input, one +per line. The first command is always the 'capabilities' command, in +response to which the remote helper must print a list of the +capabilities it supports (see below) followed by a blank line. The +response to the capabilities command determines what commands Git uses +in the remainder of the command stream. + +The command stream is terminated by a blank line. In some cases +(indicated in the documentation of the relevant commands), this blank +line is followed by a payload in some other protocol (e.g., the pack +protocol), while in others it indicates the end of input. + +Capabilities +~~~~~~~~~~~~ + +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/{asterisk}:refs/svn/origin/branches/{asterisk}` +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 {asterisk}:{asterisk}`. + +Capabilities for Pushing +~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can attempt to connect to 'git receive-pack' (for pushing), + 'git upload-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'push':: + Can discover remote refs and push local commits and the + history leading up to them to new or existing remote refs. ++ +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). + +Capabilities for Fetching +~~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can try to connect to 'git upload-pack' (for fetching), + 'git receive-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'fetch':: + Can discover remote refs and transfer objects reachable from + them to the local object store. ++ +Supported commands: 'list', 'fetch'. + +'import':: + Can discover remote refs and output objects reachable from + them as a stream in fast-import format. ++ +Supported commands: 'list', 'import'. + +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 'fetch' and 'import', git prefers 'fetch'. +Other frontends may have some other order of preference. + +'refspec' <refspec>:: + This modifies the 'import' capability. ++ +A helper advertising +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}` +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. ++ +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 {asterisk}:{asterisk}`. + INVOCATION ---------- @@ -122,7 +241,22 @@ Supported if the helper has the "fetch" capability. 'push' +<src>:<dst>:: Pushes the given local <src> commit or branch to the remote branch described by <dst>. A batch sequence of - one or more push commands is terminated with a blank line. + one or more 'push' commands is terminated with a blank line + (if there is only one reference to push, a single 'push' command + is followed by a blank line). For example, the following would + be two batches of 'push', the first asking the remote-helper + to push the local ref 'master' to the remote ref 'master' and + the local 'HEAD' to the remote 'branch', and the second + asking to push ref 'foo' to ref 'bar' (forced update requested + by the '+'). ++ +------------ +push refs/heads/master:refs/heads/master +push HEAD:refs/heads/branch +\n +push +refs/heads/foo:refs/heads/bar +\n +------------ + Zero or more protocol options may be entered after the last 'push' command, before the batch's terminating blank line. @@ -147,6 +281,11 @@ Supported if the helper has the "push" capability. Especially useful for interoperability with a foreign versioning system. + +Just like 'push', a batch sequence of one or more 'import' is +terminated with a blank line. For each batch of 'import', the remote +helper should produce a fast-import stream terminated by a 'done' +command. ++ Supported if the helper has the "import" capability. 'connect' <service>:: @@ -171,26 +310,6 @@ completing a valid response for the current command. Additional commands may be supported, as may be determined from capabilities reported by the helper. -CAPABILITIES ------------- - -'fetch':: -'option':: -'push':: -'import':: -'connect':: - This helper supports the corresponding command with the same name. - -'refspec' 'spec':: - When using the import command, expect the source ref to have - been written to the destination ref. The earliest applicable - refspec takes precedence. For example - "refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}" means - that, after an "import refs/heads/name", the script has written to - refs/svn/origin/branches/name. If this capability is used at - all, it must cover all refs reported by the list command; if - it is not used, it is effectively "{asterisk}:{asterisk}" - REF LIST ATTRIBUTES ------------------- @@ -243,6 +362,8 @@ SEE ALSO -------- linkgit:git-remote[1] +linkgit:git-remote-testgit[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt new file mode 100644 index 0000000000..2a67d456a3 --- /dev/null +++ b/Documentation/git-remote-testgit.txt @@ -0,0 +1,30 @@ +git-remote-testgit(1) +===================== + +NAME +---- +git-remote-testgit - Example remote-helper + + +SYNOPSIS +-------- +[verse] +git clone testgit::<source-repo> [<destination>] + +DESCRIPTION +----------- + +This command is a simple remote-helper, that is used both as a +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'. + +SEE ALSO +-------- +linkgit:git-remote-helpers[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index b311d59c7c..f3519413e7 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -9,6 +9,8 @@ SYNOPSIS -------- [verse] 'git revert' [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit>... +'git revert' --reset +'git revert' --continue DESCRIPTION ----------- @@ -91,6 +93,10 @@ effect to your index in a row. Pass the merge strategy-specific option through to the merge strategy. See linkgit:git-merge[1] for details. +SEQUENCER SUBCOMMANDS +--------------------- +include::sequencer.txt[] + EXAMPLES -------- `git revert HEAD~3`:: diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index bed9e1f097..bd3eaa69bf 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,7 +9,7 @@ git-send-pack - Push objects over git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--quiet] [--verbose] [--thin] [<host>:]<directory> [<ref>...] +'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] DESCRIPTION ----------- @@ -45,9 +45,6 @@ OPTIONS the remote repository can lose commits; use it with care. ---quiet:: - Print only error messages. - --verbose:: Run verbosely. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index ed5eca1fce..f977e8780b 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -157,6 +157,17 @@ Skip "branches" and "tags" of first level directories;; affecting the working tree; and the 'rebase' command will be able to update the working tree with the latest changes. +--preserve-empty-dirs;; + Create a placeholder file in the local Git repository for each + empty directory fetched from Subversion. This includes directories + that become empty by removing all entries in the Subversion + repository (but not the directory itself). The placeholder files + are also tracked and removed when no longer necessary. + +--placeholder-filename=<filename>;; + Set the name of placeholder files created by --preserve-empty-dirs. + Default: ".gitignore" + 'rebase':: This fetches revisions from the SVN parent of the current HEAD and rebases the current (uncommitted to SVN) work against it. @@ -211,8 +222,17 @@ discouraged. Add the given merge information during the dcommit (e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can store this information (as a property), and svn clients starting from - version 1.5 can make use of it. 'git svn' currently does not use it - and does not set it automatically. + version 1.5 can make use of it. To specify merge information from multiple + branches, use a single space character between the branches + (`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`) ++ +[verse] +config key: svn.pushmergeinfo ++ +This option will cause git-svn to attempt to automatically populate the +svn:mergeinfo property in the SVN repository when possible. Currently, this can +only be done when dcommitting non-fast-forward merges where all parents but the +first have already been pushed into SVN. 'branch':: Create a branch in the SVN repository. @@ -298,7 +318,7 @@ Any other arguments are passed directly to 'git log' Show what revision and author last modified each line of a file. The output of this mode is format-compatible with the output of `svn blame' by default. Like the SVN blame command, - local uncommitted changes in the working copy are ignored; + local uncommitted changes in the working tree are ignored; the version of the file in the HEAD revision is annotated. Unknown arguments are passed directly to 'git blame'. + diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index fb1c0ac694..c83cb13de6 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -43,12 +43,15 @@ GnuPG key for signing. OPTIONS ------- -a:: +--annotate:: Make an unsigned, annotated tag object -s:: +--sign:: Make a GPG-signed tag, using the default e-mail address's key -u <key-id>:: +--local-user=<key-id>:: Make a GPG-signed tag, using the given key -f:: @@ -56,9 +59,11 @@ OPTIONS Replace an existing tag with the given name (instead of failing) -d:: +--delete:: Delete existing tags with the given names. -v:: +--verify:: Verify the gpg signature of the given tag names. -n<num>:: @@ -69,6 +74,7 @@ OPTIONS If the tag is not annotated, the commit message is displayed instead. -l <pattern>:: +--list <pattern>:: List tags with names that match the given pattern (or all if no pattern is given). Running "git tag" without arguments also lists all tags. The pattern is a shell wildcard (i.e., matched @@ -79,6 +85,7 @@ OPTIONS Only list tags which contain the specified commit. -m <msg>:: +--message=<msg>:: Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. @@ -86,6 +93,7 @@ OPTIONS is given. -F <file>:: +--file=<file>:: Take the tag message from the given file. Use '-' to read the message from the standard input. Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index d3931294d1..a3081f4e23 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -264,7 +264,9 @@ tree files, you have to explicitly tell git about it by dropping "assume unchanged" bit, either before or after you modify them. In order to set "assume unchanged" bit, use `--assume-unchanged` -option. To unset, use `--no-assume-unchanged`. +option. To unset, use `--no-assume-unchanged`. To see which files +have the "assume unchanged" bit set, use `git ls-files -v` +(see linkgit:git-ls-files[1]). The command looks at `core.ignorestat` configuration variable. When this is true, paths updated with `git update-index paths...` and @@ -363,7 +365,8 @@ ctime for marking files processed) (see linkgit:git-config[1]). SEE ALSO -------- linkgit:git-config[1], -linkgit:git-add[1] +linkgit:git-add[1], +linkgit:git-ls-files[1] GIT --- diff --git a/Documentation/git.txt b/Documentation/git.txt index 710d750cfd..cbc51d5a94 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,9 +44,18 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.6/git.html[documentation for release 1.7.6] +* link:v1.7.7/git.html[documentation for release 1.7.7] * release notes for + link:RelNotes/1.7.7.txt[1.7.7]. + +* link:v1.7.6.4/git.html[documentation for release 1.7.6.4] + +* release notes for + link:RelNotes/1.7.6.4.txt[1.7.6.4], + link:RelNotes/1.7.6.3.txt[1.7.6.3], + link:RelNotes/1.7.6.2.txt[1.7.6.2], + link:RelNotes/1.7.6.1.txt[1.7.6.1], link:RelNotes/1.7.6.txt[1.7.6]. * link:v1.7.5.4/git.html[documentation for release 1.7.5.4] diff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt index ed8924e856..c6713cf5d7 100644 --- a/Documentation/gitnamespaces.txt +++ b/Documentation/gitnamespaces.txt @@ -5,6 +5,13 @@ NAME ---- gitnamespaces - Git namespaces +SYNOPSIS +-------- +[verse] +GIT_NAMESPACE=<namespace> 'git upload-pack' +GIT_NAMESPACE=<namespace> 'git receive-pack' + + DESCRIPTION ----------- diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index eb3d040783..5c891f1169 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -23,32 +23,25 @@ objects:: Object store associated with this repository. Usually an object store is self sufficient (i.e. all the objects that are referred to by an object found in it are also - found in it), but there are couple of ways to violate - it. + found in it), but there are a few ways to violate it. + -. You could populate the repository by running a commit walker -without `-a` option. Depending on which options are given, you -could have only commit objects without associated blobs and -trees this way, for example. A repository with this kind of -incomplete object store is not suitable to be published to the -outside world but sometimes useful for private repository. -. You also could have an incomplete but locally usable repository -by cloning shallowly. See linkgit:git-clone[1]. -. You can be using `objects/info/alternates` mechanism, or -`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow' +. You could have an incomplete but locally usable repository +by creating a shallow clone. See linkgit:git-clone[1]. +. You could be using the `objects/info/alternates` or +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow' objects from other object stores. A repository with this kind of incomplete object store is not suitable to be published for use with dumb transports but otherwise is OK as long as -`objects/info/alternates` points at the right object stores -it borrows from. +`objects/info/alternates` points at the object stores it +borrows from. objects/[0-9a-f][0-9a-f]:: - Traditionally, each object is stored in its own file. - They are split into 256 subdirectories using the first - two letters from its object name to keep the number of - directory entries `objects` directory itself needs to - hold. Objects found here are often called 'unpacked' - (or 'loose') objects. + A newly created object is stored in its own file. + The objects are splayed over 256 subdirectories using + the first two characters of the sha1 object name to + keep the number of directory entries in `objects` + itself to a manageable number. Objects found + here are often called 'unpacked' (or 'loose') objects. objects/pack:: Packs (files that store many object in compressed form, @@ -85,7 +78,7 @@ objects/info/http-alternates:: refs:: References are stored in subdirectories of this - directory. The 'git prune' command knows to keep + directory. The 'git prune' command knows to preserve objects reachable from refs found in this directory and its subdirectories. @@ -119,16 +112,17 @@ HEAD:: + HEAD can also record a specific commit directly, instead of being a symref to point at the current branch. Such a state -is often called 'detached HEAD', and almost all commands work -identically as normal. See linkgit:git-checkout[1] for -details. +is often called 'detached HEAD.' See linkgit:git-checkout[1] +for details. branches:: A slightly deprecated way to store shorthands to be used - to specify URL to 'git fetch', 'git pull' and 'git push' - commands is to store a file in `branches/<name>` and - give 'name' to these commands in place of 'repository' - argument. + to specify a URL to 'git fetch', 'git pull' and 'git push'. + A file can be stored as `branches/<name>` and then + 'name' can be given to these commands in place of + 'repository' argument. See the REMOTES section in + linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. hooks:: Hooks are customization scripts used by various git @@ -173,9 +167,11 @@ info/exclude:: at it. See also: linkgit:gitignore[5]. remotes:: - Stores shorthands to be used to give URL and default - refnames to interact with remote repository to - 'git fetch', 'git pull' and 'git push' commands. + Stores shorthands for URL and default refnames for use + when interacting with remote repositories via 'git fetch', + 'git pull' and 'git push' commands. See the REMOTES section + in linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. logs:: Records of changes made to refs are stored in this diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index d527b30770..8823a37067 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -176,7 +176,7 @@ by doing the following: - Update "What's cooking" message to review the updates to existing topics, newly added topics and graduated topics. - This step is helped with Meta/UWC script (where Meta/ contains + This step is helped with Meta/cook script (where Meta/ contains a checkout of the 'todo' branch). - Merge topics to 'next'. For each branch whose tip is not @@ -197,10 +197,9 @@ by doing the following: - Nothing is next-worthy; do not do anything. - - Rebase topics that do not have any commit in next yet. This - step is optional but sometimes is worth doing when an old - series that is not in next can take advantage of low-level - framework change that is merged to 'master' already. + - [** OBSOLETE **] Optionally rebase topics that do not have any commit + in next yet, when they can take advantage of low-level framework + change that is merged to 'master' already. $ git rebase master ai/topic @@ -209,7 +208,7 @@ by doing the following: pre-rebase hook to make sure that topics that are already in 'next' are not rebased beyond the merged commit. - - Rebuild "pu" to merge the tips of topics not in 'next'. + - [** OBSOLETE **] Rebuild "pu" to merge the tips of topics not in 'next'. $ git checkout pu $ git reset --hard next @@ -241,7 +240,7 @@ by doing the following: - Fetch html and man branches back from k.org, and push four integration branches and the two documentation branches to - repo.or.cz + repo.or.cz and other mirrors. Some observations to be made. diff --git a/Documentation/sequencer.txt b/Documentation/sequencer.txt new file mode 100644 index 0000000000..3e6df338be --- /dev/null +++ b/Documentation/sequencer.txt @@ -0,0 +1,9 @@ +--reset:: + Forget about the current operation in progress. Can be used + to clear the sequencer state after a failed cherry-pick or + revert. + +--continue:: + Continue the operation in progress using the information in + '.git/sequencer'. Can be used to continue after resolving + conflicts in a failed cherry-pick or revert. diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt new file mode 100644 index 0000000000..49b3d52952 --- /dev/null +++ b/Documentation/technical/api-argv-array.txt @@ -0,0 +1,46 @@ +argv-array API +============== + +The argv-array API allows one to dynamically build and store +NULL-terminated lists. An argv-array maintains the invariant that the +`argv` member always points to a non-NULL array, and that the array is +always NULL-terminated at the element pointed to by `argv[argc]`. This +makes the result suitable for passing to functions expecting to receive +argv from main(), or the link:api-run-command.html[run-command API]. + +The link:api-string-list.html[string-list API] is similar, but cannot be +used for these purposes; instead of storing a straight string pointer, +it contains an item structure with a `util` field that is not compatible +with the traditional argv interface. + +Each `argv_array` manages its own memory. Any strings pushed into the +array are duplicated, and all memory is freed by argv_array_clear(). + +Data Structures +--------------- + +`struct argv_array`:: + + A single array. This should be initialized by assignment from + `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv` + member contains the actual array; the `argc` member contains the + number of elements in the array, not including the terminating + NULL. + +Functions +--------- + +`argv_array_init`:: + Initialize an array. This is no different than assigning from + `ARGV_ARRAY_INIT`. + +`argv_array_push`:: + Push a copy of a string onto the end of the array. + +`argv_array_pushf`:: + Format a string and push it onto the end of the array. This is a + convenience wrapper combining `strbuf_addf` and `argv_array_push`. + +`argv_array_clear`:: + Free all memory associated with the array and return it to the + initial, empty state. diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt new file mode 100644 index 0000000000..dbbea95db7 --- /dev/null +++ b/Documentation/technical/api-ref-iteration.txt @@ -0,0 +1,81 @@ +ref iteration API +================= + + +Iteration of refs is done by using an iterate function which will call a +callback function for every ref. The callback function has this +signature: + + int handle_one_ref(const char *refname, const unsigned char *sha1, + int flags, void *cb_data); + +There are different kinds of iterate functions which all take a +callback of this type. The callback is then called for each found ref +until the callback returns nonzero. The returned value is then also +returned by the iterate function. + +Iteration functions +------------------- + +* `head_ref()` just iterates the head ref. + +* `for_each_ref()` iterates all refs. + +* `for_each_ref_in()` iterates all refs which have a defined prefix and + strips that prefix from the passed variable refname. + +* `for_each_tag_ref()`, `for_each_branch_ref()`, `for_each_remote_ref()`, + `for_each_replace_ref()` iterate refs from the respective area. + +* `for_each_glob_ref()` iterates all refs that match the specified glob + pattern. + +* `for_each_glob_ref_in()` the previous and `for_each_ref_in()` combined. + +* `head_ref_submodule()`, `for_each_ref_submodule()`, + `for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`, + `for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()` + do the same as the functions descibed above but for a specified + submodule. + +* `for_each_rawref()` can be used to learn about broken ref and symref. + +* `for_each_reflog()` iterates each reflog file. + +Submodules +---------- + +If you want to iterate the refs of a submodule you first need to add the +submodules object database. You can do this by a code-snippet like +this: + + const char *path = "path/to/submodule" + if (!add_submodule_odb(path)) + die("Error submodule '%s' not populated.", path); + +`add_submodule_odb()` will return an non-zero value on success. If you +do not do this you will get an error for each ref that it does not point +to a valid object. + +Note: As a side-effect of this you can not safely assume that all +objects you lookup are available in superproject. All submodule objects +will be available the same way as the superprojects objects. + +Example: +-------- + +---- +static int handle_remote_ref(const char *refname, + const unsigned char *sha1, int flags, void *cb_data) +{ + struct strbuf *output = cb_data; + strbuf_addf(output, "%s\n", refname); + return 0; +} + +... + + struct strbuf output = STRBUF_INIT; + for_each_remote_ref(handle_remote_ref, &output); + printf("%s", output.buf); +---- diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-sha1-array.txt new file mode 100644 index 0000000000..4a4bae8109 --- /dev/null +++ b/Documentation/technical/api-sha1-array.txt @@ -0,0 +1,79 @@ +sha1-array API +============== + +The sha1-array API provides storage and manipulation of sets of SHA1 +identifiers. The emphasis is on storage and processing efficiency, +making them suitable for large lists. Note that the ordering of items is +not preserved over some operations. + +Data Structures +--------------- + +`struct sha1_array`:: + + A single array of SHA1 hashes. This should be initialized by + assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains + the actual data. The `nr` member contains the number of items in + the set. The `alloc` and `sorted` members are used internally, + and should not be needed by API callers. + +Functions +--------- + +`sha1_array_append`:: + Add an item to the set. The sha1 will be placed at the end of + the array (but note that some operations below may lose this + ordering). + +`sha1_array_sort`:: + Sort the elements in the array. + +`sha1_array_lookup`:: + Perform a binary search of the array for a specific sha1. + If found, returns the offset (in number of elements) of the + sha1. If not found, returns a negative integer. If the array is + not sorted, this function has the side effect of sorting it. + +`sha1_array_clear`:: + Free all memory associated with the array and return it to the + initial, empty state. + +`sha1_array_for_each_unique`:: + Efficiently iterate over each unique element of the list, + executing the callback function for each one. If the array is + not sorted, this function has the side effect of sorting it. + +Examples +-------- + +----------------------------------------- +void print_callback(const unsigned char sha1[20], + void *data) +{ + printf("%s\n", sha1_to_hex(sha1)); +} + +void some_func(void) +{ + struct sha1_array hashes = SHA1_ARRAY_INIT; + unsigned char sha1[20]; + + /* Read objects into our set */ + while (read_object_from_stdin(sha1)) + sha1_array_append(&hashes, sha1); + + /* Check if some objects are in our set */ + while (read_object_from_stdin(sha1)) { + if (sha1_array_lookup(&hashes, sha1) >= 0) + printf("it's in there!\n"); + + /* + * Print the unique set of objects. We could also have + * avoided adding duplicate objects in the first place, + * but we would end up re-sorting the array repeatedly. + * Instead, this will sort once and then skip duplicates + * in linear time. + */ + sha1_array_for_each_unique(&hashes, print_callback, NULL); +} +----------------------------------------- diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 3f575bdcff..ce24eb96f5 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -29,6 +29,9 @@ member (you need this if you add things later) and you should set the . Can sort an unsorted list using `sort_string_list`. +. Can remove individual items of an unsorted list using + `unsorted_string_list_delete_item`. + . Finally it should free the list using `string_list_clear`. Example: @@ -112,6 +115,13 @@ write `string_list_insert(...)->util = ...;`. The above two functions need to look through all items, as opposed to their counterpart for sorted lists, which performs a binary search. +`unsorted_string_list_delete_item`:: + + Remove an item from a string_list. The `string` pointer of the items + will be freed in case the `strdup_strings` member of the string_list + is set. The third parameter controls if the `util` pointer of the + items should be freed or not. + Data structures --------------- |