diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/1.8.1.2.txt | 12 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.8.2.txt | 117 | ||||
| -rw-r--r-- | Documentation/git-check-ignore.txt | 89 | ||||
| -rw-r--r-- | Documentation/git-cvsserver.txt | 37 | ||||
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-p4.txt | 22 | ||||
| -rw-r--r-- | Documentation/git-reset.txt | 18 | ||||
| -rw-r--r-- | Documentation/githooks.txt | 29 | ||||
| -rw-r--r-- | Documentation/gitignore.txt | 6 | ||||
| -rw-r--r-- | Documentation/howto/maintain-git.txt | 347 | ||||
| -rw-r--r-- | Documentation/technical/api-directory-listing.txt | 14 |
11 files changed, 546 insertions, 147 deletions
diff --git a/Documentation/RelNotes/1.8.1.2.txt b/Documentation/RelNotes/1.8.1.2.txt index 76ad0b3d01..5ab7b18906 100644 --- a/Documentation/RelNotes/1.8.1.2.txt +++ b/Documentation/RelNotes/1.8.1.2.txt @@ -4,6 +4,16 @@ Git 1.8.1.2 Release Notes Fixes since v1.8.1.1 -------------------- + * 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. + + * Command line completion for "tcsh" emitted an unwanted space + after completing a single directory name. + + * Command line completion leaked an unnecessary error message while + looking for possible matches with paths in <tree-ish>. + * "git archive" did not record uncompressed size in the header when streaming a zip archive, which confused some implementations of unzip. @@ -11,3 +21,5 @@ Fixes since v1.8.1.1 trailer part, "git send-email" failed to pick up the addresses from there. As e-mail headers field names are case insensitive, this script should follow suit and treat "cc:" and "Cc:" the same way. + +Also contains various documentation fixes. diff --git a/Documentation/RelNotes/1.8.2.txt b/Documentation/RelNotes/1.8.2.txt index f6d15059dc..5c93f32779 100644 --- a/Documentation/RelNotes/1.8.2.txt +++ b/Documentation/RelNotes/1.8.2.txt @@ -15,6 +15,13 @@ 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. +"git push $there tag v1.2.3" used to allow replacing a tag v1.2.3 +that already exists in the repository $there, if the rewritten tag +you are pushing points at a commit that is a decendant of a commit +that the old tag v1.2.3 points at. This was found to be error prone +and starting with this release, any attempt to update an existing +ref under refs/tags/ hierarchy will fail, without "--force". + Updates since v1.8.1 -------------------- @@ -38,11 +45,16 @@ UI, Workflows & Features * Scripts can ask Git that wildcard patterns in pathspecs they give do not have any significance, i.e. take them as literal strings. - * The pathspec code learned to grok "foo/**/bar" as a pattern that - matches "bar" in 0-or-more levels of subdirectory in "foo". + * The patterns in .gitignore and .gitattributes files can have **/, + as a pattern that matches 0 or more levels of subdirectory. + E.g. "foo/**/bar" matches "bar" in "foo" itself or in a + subdirectory of "foo". * "git blame" (and "git diff") learned the "--no-follow" option. + * "git check-ignore" command to help debugging .gitignore files has + been added. + * "git cherry-pick" can be used to replay a root commit to an unborn branch. @@ -72,12 +84,22 @@ UI, Workflows & Features * "git push" now requires "-f" to update a tag, even if it is a fast-forward, as tags are meant to be fixed points. + * "git push" will stop without doing anything if the new "pre-push" + hook exists and exits with a failure. + * When "git rebase" fails to generate patches to be applied (e.g. due to oom), it failed to detect the failure and instead behaved as if there were nothing to do. A workaround to use a temporary file has been applied, but we probably would want to revisit this later, as it hurts the common case of not failing at all. + * Input and preconditions to "git reset" has been loosened where + appropriate. "git reset $fromtree Makefile" requires $fromtree to + be any tree (it used to require it to be a commit), for example. + "git reset" (without options or parameters) used to error out when + you do not have any commits in your history, but it now gives you + an empty index (to match non-existent commit you are not even on). + * "git submodule" started learning a new mode to integrate with the tip of the remote branch (as opposed to integrating with the commit recorded in the superproject's gitlink). @@ -90,6 +112,11 @@ Foreign Interface * A new remote helper to interact with bzr has been added to contrib/. + * "git p4" got various bugfixes around its branch handling. + + * The remote helper to interact with Hg in contrib/ has seen a few + fixes. + Performance, Internal Implementation, etc. @@ -99,13 +126,33 @@ Performance, Internal Implementation, etc. * Matching paths with common forms of pathspecs that contain wildcard characters has been optimized further. + * "git reset" internals has been reworked and should be faster in + general. We tried to be careful not to break any behaviour but + there could be corner cases, especially when running the command + from a conflicted state, that we may have missed. + * The implementation of "imap-send" has been updated to reuse xml - quoting code from http-push codepath. + quoting code from http-push codepath, and lost a lot of unused + code. * There is a simple-minded checker for the test scripts in t/ directory to catch most common mistakes (it is not enabled by default). + * You can build with USE_WILDMATCH=YesPlease to use a replacement + implementation of pattern matching logic used for pathname-like + things, e.g. refnames and paths in the repository. This new + implementation is not expected change the existing behaviour of Git + in this release, except for "git for-each-ref" where you can now + say "refs/**/master" and match with both refs/heads/master and + refs/remotes/origin/master. We plan to use this new implementation + in wider places (e.g. "git ls-files '**/Makefile' may find Makefile + at the top-level, and "git log '**/t*.sh'" may find commits that + touch a shell script whose name begins with "t" at any level) in + future versions of Git, but we are not there yet. By building with + USE_WILDMATCH, using the resulting Git daily and reporting when you + find breakages, you can help us get closer to that goal. + Also contains minor documentation updates and code clean-ups. @@ -120,13 +167,11 @@ 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). * When attempting to read the XDG-style $HOME/.config/git/config and finding that $HOME/.config/git is a file, we gave a wrong error message, instead of treating the case as "a custom config file does not exist there" and moving on. - (merge 8f2bbe4 jn/warn-on-inaccessible-loosen 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 @@ -137,100 +182,105 @@ details). * A child process that was killed by a signal (e.g. SIGINT) was reported in an inconsistent way depending on how the process was spawned by us, with or without a shell in between. - (merge 709ca73 jk/unify-exit-code-by-receiving-signal 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 attribute mechanism didn't allow limiting attributes to be applied to only a single directory itself with "path/" like the - exclude mechanism does. - (merge 94bc671 ja/directory-attrs later to maint). + exclude mechanism does. The initial implementation of this that + was merged to 'maint' and 1.8.1.2 was with a severe performance + degradations and needs to merge a fix-up topic. + (merge 9db9eec nd/fix-directory-attrs-off-by-one later to maint). + + * "git am" did not parse datestamp correctly from Hg generated patch, + when it is run in a locale outside C (or en). + (merge 5185b97 dl/am-hg-locale later to maint). * "git apply" misbehaved when fixing whitespace breakages by removing excess trailing blank lines. - (merge 5de7166 jc/apply-trailing-blank-removal later to maint). * A tar archive created by "git archive" recorded a directory in a way that made NetBSD's implementation of "tar" sometimes unhappy. - (merge 22f0dcd rs/leave-base-name-in-name-field-of-tar later to maint). * "git archive" did not record uncompressed size in the header when streaming a zip archive, which confused some implementations of unzip. - (merge 5ea2c84 rs/zip-with-uncompressed-size-in-the-header later to maint). + + * "git clean" showed what it was going to do, but sometimes end up + finding that it was not allowed to do so, which resulted in a + confusing output (e.g. after saying that it will remove an + untracked directory, it found an embedded git repository there + which it is not allowed to remove). It now performs the actions + and then reports the outcome more faithfully. + (merge f538a91 zk/clean-report-failure later to maint). * When "git clone --separate-git-dir=$over_there" is interrupted, it failed to remove the real location of the $GIT_DIR it created. This was most visible when interrupting a submodule update. - (merge 9be1980 jl/interrupt-clone-remove-separate-git-dir 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). + + * "git clone" used to allow --bare and --separate-git-dir=$there + options at the same time, which was nonsensical. + (merge 95b63f1 nd/clone-no-separate-git-dir-with-bare later to maint). + + * "git rebase --preserve-merges" lost empty merges in recent versions + of Git. + (merge 9869778 ph/rebase-preserve-all-merges later to maint). * "git merge --no-edit" computed who were involved in the work done on the side branch, even though that information is to be discarded without getting seen in the editor. - (merge 9bcbb1c jc/maint-fmt-merge-msg-no-edit-lose-credit later to maint). * "git merge" started calling prepare-commit-msg hook like "git commit" does some time ago, but forgot to pay attention to the exit status of the hook. - (merge 3e4141d ap/merge-stop-at-prepare-commit-msg-failure later to maint). * When users spell "cc:" in lowercase in the fake "header" in the trailer part, "git send-email" failed to pick up the addresses from there. As e-mail headers field names are case insensitive, this script should follow suit and treat "cc:" and "Cc:" the same way. - (merge 6310071 nz/send-email-headers-are-case-insensitive later to maint). * Output from "git status --ignored" showed an unexpected interaction with "--untracked". - (merge a45fb69 ap/status-ignored-in-ignored-directory 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). * "gitweb"'s code to sanitize control characters before passing it to "highlight" filter lost known-to-be-safe control characters by mistake. - (merge 0e901d2 os/gitweb-highlight-uncaptured 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). * Command line completion leaked an unnecessary error message while looking for possible matches with paths in <tree-ish>. - (merge ca87dd6 ds/completion-silence-in-tree-path-probe later to maint). * Command line completion for "tcsh" emitted an unwanted space after completing a single directory name. - (merge 92f1c04 mk/complete-tcsh later to maint). + + * Command line completion code was inadvertently made incompatible with + older versions of bash by using a newer array notation. + (merge 50c5885 bc/fix-array-syntax-for-3.0-in-completion-bash 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). * Some scripted programs written in Python did not get updated when PYTHON_PATH changed. @@ -238,24 +288,21 @@ details). * When autoconf is used, any build on a different commit always ran "config.status --recheck" even when unnecessary. - (merge 1226504 jn/less-reconfigure later to maint). * We have been carrying a translated and long-unmaintained copy of an old version of the tutorial; removed. - (merge 0a85441 ta/remove-stale-translated-tut later to maint). + + * t0050 had tests expecting failures from a bug that was fixed some + time ago. + (merge 336e2e2 tb/t0050-maint 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). * t9020 and t9810 had a few non-portable shell script construct. - (merge 2797914 tb/test-t9020-no-which later to maint). - (merge 6f4e505 tb/test-t9810-no-sed-i later to maint). diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt new file mode 100644 index 0000000000..854e4d0c42 --- /dev/null +++ b/Documentation/git-check-ignore.txt @@ -0,0 +1,89 @@ +git-check-ignore(1) +=================== + +NAME +---- +git-check-ignore - Debug gitignore / exclude files + + +SYNOPSIS +-------- +[verse] +'git check-ignore' [options] pathname... +'git check-ignore' [options] --stdin < <list-of-paths> + +DESCRIPTION +----------- + +For each pathname given via the command-line or from a file via +`--stdin`, show the pattern from .gitignore (or other input files to +the exclude mechanism) that decides if the pathname is excluded or +included. Later patterns within a file take precedence over earlier +ones. + +OPTIONS +------- +-q, --quiet:: + Don't output anything, just set exit status. This is only + valid with a single pathname. + +-v, --verbose:: + Also output details about the matching pattern (if any) + for each given pathname. + +--stdin:: + Read file names from stdin instead of from the command-line. + +-z:: + The output format is modified to be machine-parseable (see + below). If `--stdin` is also given, input paths are separated + with a NUL character instead of a linefeed character. + +OUTPUT +------ + +By default, any of the given pathnames which match an ignore pattern +will be output, one per line. If no pattern matches a given path, +nothing will be output for that path; this means that path will not be +ignored. + +If `--verbose` is specified, the output is a series of lines of the form: + +<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname> + +<pathname> is the path of a file being queried, <pattern> is the +matching pattern, <source> is the pattern's source file, and <linenum> +is the line number of the pattern within that source. If the pattern +contained a `!` prefix or `/` suffix, it will be preserved in the +output. <source> will be an absolute path when referring to the file +configured by `core.excludesfile`, or relative to the repository root +when referring to `.git/info/exclude` or a per-directory exclude file. + +If `-z` is specified, the pathnames in the output are delimited by the +null character; if `--verbose` is also specified then null characters +are also used instead of colons and hard tabs: + +<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL> + + +EXIT STATUS +----------- + +0:: + One or more of the provided paths is ignored. + +1:: + None of the provided paths are ignored. + +128:: + A fatal error was encountered. + +SEE ALSO +-------- +linkgit:gitignore[5] +linkgit:gitconfig[5] +linkgit:git-ls-files[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 88d814af0e..940c2ba66a 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -359,6 +359,43 @@ Operations supported All the operations required for normal use are supported, including checkout, diff, status, update, log, add, remove, commit. + +Most CVS command arguments that read CVS tags or revision numbers +(typically -r) work, and also support any git refspec +(tag, branch, commit ID, etc). +However, CVS revision numbers for non-default branches are not well +emulated, and cvs log does not show tags or branches at +all. (Non-main-branch CVS revision numbers superficially resemble CVS +revision numbers, but they actually encode a git commit ID directly, +rather than represent the number of revisions since the branch point.) + +Note that there are two ways to checkout a particular branch. +As described elsewhere on this page, the "module" parameter +of cvs checkout is interpreted as a branch name, and it becomes +the main branch. It remains the main branch for a given sandbox +even if you temporarily make another branch sticky with +cvs update -r. Alternatively, the -r argument can indicate +some other branch to actually checkout, even though the module +is still the "main" branch. Tradeoffs (as currently +implemented): Each new "module" creates a new database on disk with +a history for the given module, and after the database is created, +operations against that main branch are fast. Or alternatively, +-r doesn't take any extra disk space, but may be significantly slower for +many operations, like cvs update. + +If you want to refer to a git refspec that has characters that are +not allowed by CVS, you have two options. First, it may just work +to supply the git refspec directly to the appropriate CVS -r argument; +some CVS clients don't seem to do much sanity checking of the argument. +Second, if that fails, you can use a special character escape mechanism +that only uses characters that are valid in CVS tags. A sequence +of 4 or 5 characters of the form (underscore (`"_"`), dash (`"-"`), +one or two characters, and dash (`"-"`)) can encode various characters based +on the one or two letters: `"s"` for slash (`"/"`), `"p"` for +period (`"."`), `"u"` for underscore (`"_"`), or two hexadecimal digits +for any byte value at all (typically an ASCII number, or perhaps a part +of a UTF-8 encoded character). + Legacy monitoring operations are not supported (edit, watch and related). Exports and tagging (tags and branches) are not supported at this stage. diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index db55a4e0bb..f2e08d11c1 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -117,7 +117,7 @@ returns an empty string instead. As a special case for the date-type fields, you may specify a format for the date by adding one of `:default`, `:relative`, `:short`, `:local`, -`:iso8601` or `:rfc2822` to the end of the fieldname; e.g. +`:iso8601`, `:rfc2822` or `:raw` to the end of the fieldname; e.g. `%(taggerdate:relative)`. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index beff6229c8..f70ef9ded2 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -112,6 +112,11 @@ will be fetched and consulted first during a 'git p4 sync'. Since importing directly from p4 is considerably slower than pulling changes from a git remote, this can be useful in a multi-developer environment. +If there are multiple branches, doing 'git p4 sync' will automatically +use the "BRANCH DETECTION" algorithm to try to partition new changes +into the right branch. This can be overridden with the '--branch' +option to specify just a single branch to update. + Rebase ~~~~~~ @@ -173,9 +178,11 @@ subsequent 'sync' operations. --branch <branch>:: Import changes into given branch. If the branch starts with - 'refs/', it will be used as is, otherwise the path 'refs/heads/' - will be prepended. The default branch is 'master'. If used - with an initial clone, no HEAD will be checked out. + 'refs/', it will be used as is. Otherwise if it does not start + with 'p4/', that prefix is added. The branch is assumed to + name a remote tracking, but this can be modified using + '--import-local', or by giving a full ref name. The default + branch is 'master'. + This example imports a new remote "p4/proj2" into an existing git repository: @@ -287,6 +294,11 @@ These options can be used to modify 'git p4 submit' behavior. to bypass the prompt, causing conflicting commits to be automatically skipped, or to quit trying to apply commits, without prompting. +--branch <branch>:: + After submitting, sync this named branch instead of the default + p4/master. See the "Sync options" section above for more + information. + Rebase options ~~~~~~~~~~~~~~ These options can be used to modify 'git p4 rebase' behavior. @@ -394,8 +406,10 @@ the path elements in the p4 repository. The example above relied on the presence of the p4 branch. Without p4 branches, the same result will occur with: ---- +git init depot +cd depot git config git-p4.branchList main:branch1 -git p4 clone --detect-branches //depot@all +git p4 clone --detect-branches //depot@all . ---- diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 978d8da50c..a404b47b7b 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,20 +8,20 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git reset' [-q] [<commit>] [--] <paths>... -'git reset' (--patch | -p) [<commit>] [--] [<paths>...] +'git reset' [-q] [<tree-ish>] [--] <paths>... +'git reset' (--patch | -p) [<tree-sh>] [--] [<paths>...] 'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] DESCRIPTION ----------- -In the first and second form, copy entries from <commit> to the index. +In the first and second form, copy entries from <tree-ish> to the index. In the third form, set the current branch head (HEAD) to <commit>, optionally -modifying index and working tree to match. The <commit> defaults to HEAD -in all forms. +modifying index and working tree to match. The <tree-ish>/<commit> defaults +to HEAD in all forms. -'git reset' [-q] [<commit>] [--] <paths>...:: +'git reset' [-q] [<tree-ish>] [--] <paths>...:: This form resets the index entries for all <paths> to their - state at <commit>. (It does not affect the working tree, nor + state at <tree-ish>. (It does not affect the working tree, nor the current branch.) + This means that `git reset <paths>` is the opposite of `git add @@ -34,9 +34,9 @@ Alternatively, using linkgit:git-checkout[1] and specifying a commit, you can copy the contents of a path out of a commit to the index and to the working tree in one go. -'git reset' (--patch | -p) [<commit>] [--] [<paths>...]:: +'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]:: Interactively select hunks in the difference between the index - and <commit> (defaults to HEAD). The chosen hunks are applied + and <tree-ish> (defaults to HEAD). The chosen hunks are applied in reverse to the index. + This means that `git reset -p` is the opposite of `git add -p`, i.e. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index b9003fed24..d839233dff 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -176,6 +176,35 @@ save and restore any form of metadata associated with the working tree (eg: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl for an example of how to do this. +pre-push +~~~~~~~~ + +This hook is called by 'git push' and can be used to prevent a push from taking +place. The hook is called with two parameters which provide the name and +location of the destination remote, if a named remote is not being used both +values will be the same. + +Information about what is to be pushed is provided on the hook's standard +input with lines of the form: + + <local ref> SP <local sha1> SP <remote ref> SP <remote sha1> LF + +For instance, if the command +git push origin master:foreign+ were run the +hook would receive a line like the following: + + refs/heads/master 67890 refs/heads/foreign 12345 + +although the full, 40-character SHA1s would be supplied. If the foreign ref +does not yet exist the `<remote SHA1>` will be 40 `0`. If a ref is to be +deleted, the `<local ref>` will be supplied as `(delete)` and the `<local +SHA1>` will be 40 `0`. If the local commit was specified by something other +than a name which could be expanded (such as `HEAD~`, or a SHA1) it will be +supplied as it was originally given. + +If this hook exits with a non-zero status, 'git push' will abort without +pushing anything. Information about why the push is rejected may be sent +to the user by writing to standard error. + [[pre-receive]] pre-receive ~~~~~~~~~~~ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 91a6438031..0da205fd97 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -184,8 +184,10 @@ The second .gitignore prevents git from ignoring SEE ALSO -------- -linkgit:git-rm[1], linkgit:git-update-index[1], -linkgit:gitrepository-layout[5] +linkgit:git-rm[1], +linkgit:git-update-index[1], +linkgit:gitrepository-layout[5], +linkgit:git-check-ignore[1] GIT --- diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index ea6e4a52c9..816c791502 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -10,35 +10,42 @@ Content-type: text/asciidoc How to maintain Git =================== +Activities +---------- + The maintainer's git time is spent on three activities. - - Communication (60%) + - Communication (45%) Mailing list discussions on general design, fielding user questions, diagnosing bug reports; reviewing, commenting on, suggesting alternatives to, and rejecting patches. - - Integration (30%) + - Integration (50%) Applying new patches from the contributors while spotting and correcting minor mistakes, shuffling the integration and testing branches, pushing the results out, cutting the releases, and making announcements. - - Own development (10%) + - Own development (5%) Scratching my own itch and sending proposed patch series out. +The Policy +---------- + The policy on Integration is informally mentioned in "A Note from the maintainer" message, which is periodically posted to this mailing list after each feature release is made. -The policy. - - Feature releases are numbered as vX.Y.Z and are meant to contain bugfixes and enhancements in any area, including functionality, performance and usability, without regression. + - One release cycle for a feature release is expected to last for + eight to ten weeks. + - Maintenance releases are numbered as vX.Y.Z.W and are meant to contain only bugfixes for the corresponding vX.Y.Z feature release and earlier maintenance releases vX.Y.Z.V (V < W). @@ -62,12 +69,15 @@ The policy. - 'pu' branch is used to publish other proposed changes that do not yet pass the criteria set for 'next'. - - The tips of 'master', 'maint' and 'next' branches will always - fast-forward, to allow people to build their own - customization on top of them. + - The tips of 'master' and 'maint' branches will not be rewound to + allow people to build their own customization on top of them. + Early in a new development cycle, 'next' is rewound to the tip of + 'master' once, but otherwise it will not be rewound until the end + of the cycle. - - Usually 'master' contains all of 'maint', 'next' contains all - of 'master' and 'pu' contains all of 'next'. + - Usually 'master' contains all of 'maint' and 'next' contains all + of 'master'. 'pu' contains all the topics merged to 'next', but + is rebuilt directly on 'master'. - The tip of 'master' is meant to be more stable than any tagged releases, and the users are encouraged to follow it. @@ -77,14 +87,22 @@ The policy. are found before new topics are merged to 'master'. +A Typical Git Day +----------------- + A typical git day for the maintainer implements the above policy by doing the following: - - Scan mailing list and #git channel log. Respond with review - comments, suggestions etc. Kibitz. Collect potentially - usable patches from the mailing list. Patches about a single - topic go to one mailbox (I read my mail in Gnus, and type - \C-o to save/append messages in files in mbox format). + - Scan mailing list. Respond with review comments, suggestions + etc. Kibitz. Collect potentially usable patches from the + mailing list. Patches about a single topic go to one mailbox (I + read my mail in Gnus, and type \C-o to save/append messages in + files in mbox format). + + - Write his own patches to address issues raised on the list but + nobody has stepped up solving. Send it out just like other + contributors do, and pick them up just like patches from other + contributors (see above). - Review the patches in the saved mailboxes. Edit proposed log message for typofixes and clarifications, and add Acks @@ -100,40 +118,32 @@ by doing the following: - Obviously correct fixes that pertain to the tip of 'master' are directly applied to 'master'. + - Other topics are not handled in this step. + This step is done with "git am". $ git checkout master ;# or "git checkout maint" - $ git am -3 -s mailbox + $ git am -sc3 mailbox $ make test - - Merge downwards (maint->master): - - $ git checkout master - $ git merge maint - $ make test + In practice, almost no patch directly goes to 'master' or + 'maint'. - Review the last issue of "What's cooking" message, review the - topics scheduled for merging upwards (topic->master and - topic->maint), and merge. + topics ready for merging (topic->master and topic->maint). Use + "Meta/cook -w" script (where Meta/ contains a checkout of the + 'todo' branch) to aid this step. + + And perform the merge. Use "Meta/Reintegrate -e" script (see + later) to aid this step. + + $ Meta/cook -w last-issue-of-whats-cooking.mbox $ git checkout master ;# or "git checkout maint" - $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ echo ai/topic | Meta/Reintegrate -e ;# "git merge ai/topic" $ git log -p ORIG_HEAD.. ;# final review $ git diff ORIG_HEAD.. ;# final review $ make test ;# final review - $ git branch -d ai/topic ;# or "git branch -d ai/maint-topic" - - - Merge downwards (maint->master) if needed: - - $ git checkout master - $ git merge maint - $ make test - - - Merge downwards (master->next) if needed: - - $ git checkout next - $ git merge master - $ make test - Handle the remaining patches: @@ -142,9 +152,9 @@ by doing the following: and not in 'master') is applied to a new topic branch that is forked from the tip of 'master'. This includes both enhancements and unobvious fixes to 'master'. A topic - branch is named as ai/topic where "ai" is typically - author's initial and "topic" is a descriptive name of the - topic (in other words, "what's the series is about"). + branch is named as ai/topic where "ai" is two-letter string + named after author's initial and "topic" is a descriptive name + of the topic (in other words, "what's the series is about"). - An unobvious fix meant for 'maint' is applied to a new topic branch that is forked from the tip of 'maint'. The @@ -162,7 +172,8 @@ by doing the following: The above except the "replacement" are all done with: - $ git am -3 -s mailbox + $ git checkout ai/topic ;# or "git checkout -b ai/topic master" + $ git am -sc3 mailbox while patch replacement is often done by: @@ -170,93 +181,170 @@ by doing the following: then replace some parts with the new patch, and reapplying: + $ git checkout ai/topic $ git reset --hard ai/topic~$n - $ git am -3 -s 000*.txt + $ git am -sc3 -s 000*.txt The full test suite is always run for 'maint' and 'master' after patch application; for topic branches the tests are run as time permits. - - Update "What's cooking" message to review the updates to - existing topics, newly added topics and graduated topics. + - Merge maint to master as needed: - 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 - merged to 'next', one of three things can happen: + $ git checkout master + $ git merge maint + $ make test - - The commits are all next-worthy; merge the topic to next: + - Merge master to next as needed: $ git checkout next - $ git merge ai/topic ;# or "git merge ai/maint-topic" + $ git merge master $ make test + - Review the last issue of "What's cooking" again and see if topics + that are ready to be merged to 'next' are still in good shape + (e.g. has there any new issue identified on the list with the + series?) + + - Prepare 'jch' branch, which is used to represent somewhere + between 'master' and 'pu' and often is slightly ahead of 'next'. + + $ Meta/Reintegrate master..pu >Meta/redo-jch.sh + + The result is a script that lists topics to be merged in order to + rebuild 'pu' as the input to Meta/Reintegrate script. Remove + later topics that should not be in 'jch' yet. Add a line that + consists of '### match next' before the name of the first topic + in the output that should be in 'jch' but not in 'next' yet. + + - Now we are ready to start merging topics to 'next'. For each + branch whose tip is not merged to 'next', one of three things can + happen: + + - The commits are all next-worthy; merge the topic to next; - The new parts are of mixed quality, but earlier ones are - next-worthy; merge the early parts to next: + next-worthy; merge the early parts to next; + - Nothing is next-worthy; do not do anything. + + This step is aided with Meta/redo-jch.sh script created earlier. + If a topic that was already in 'next' gained a patch, the script + would list it as "ai/topic~1". To include the new patch to the + updated 'next', drop the "~1" part; to keep it excluded, do not + touch the line. If a topic that was not in 'next' should be + merged to 'next', add it at the end of the list. Then: + + $ git checkout -B jch master + $ Meta/redo-jch.sh -c1 + + to rebuild the 'jch' branch from scratch. "-c1" tells the script + to stop merging at the first line that begins with '###' + (i.e. the "### match next" line you added earlier). + + At this point, build-test the result. It may reveal semantic + conflicts (e.g. a topic renamed a variable, another added a new + reference to the variable under its old name), in which case + prepare an appropriate merge-fix first (see appendix), and + rebuild the 'jch' branch from scratch, starting at the tip of + 'master'. + + Then do the same to 'next' $ git checkout next - $ git merge ai/topic~2 ;# the tip two are dubious - $ make test + $ sh Meta/redo-jch.sh -c1 -e - - Nothing is next-worthy; do not do anything. + The "-e" option allows the merge message that comes from the + history of the topic and the comments in the "What's cooking" to + be edited. The resulting tree should match 'jch' as the same set + of topics are merged on 'master'; otherwise there is a mismerge. + Investigate why and do not proceed until the mismerge is found + and rectified. - - [** 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 diff jch next - $ git rebase master ai/topic + When all is well, clean up the redo-jch.sh script with - This step is helped with Meta/git-topic.perl script to - identify which topic is rebaseable. There also is a - pre-rebase hook to make sure that topics that are already in - 'next' are not rebased beyond the merged commit. + $ sh Meta/redo-jch.sh -u - - [** OBSOLETE **] Rebuild "pu" to merge the tips of topics not in 'next'. + This removes topics listed in the script that have already been + merged to 'master'. This may lose '### match next' marker; + add it again to the appropriate place when it happens. - $ git checkout pu - $ git reset --hard next - $ git merge ai/topic ;# repeat for all remaining topics - $ make test + - Rebuild 'pu'. - This step is helped with Meta/PU script + $ Meta/Reintegrate master..pu >Meta/redo-pu.sh - - Push four integration branches to a private repository at - k.org and run "make test" on all of them. + Edit the result by adding new topics that are not still in 'pu' + in the script. Then - - Push four integration branches to /pub/scm/git/git.git at - k.org. This triggers its post-update hook which: + $ git checkout -B pu jch + $ sh Meta/redo-pu.sh - (1) runs "git pull" in $HOME/git-doc/ repository to pull - 'master' just pushed out; + When all is well, clean up the redo-pu.sh script with - (2) runs "make doc" in $HOME/git-doc/, install the generated - documentation in staging areas, which are separate - repositories that have html and man branches checked - out. + $ sh Meta/redo-pu.sh -u - (3) runs "git commit" in the staging areas, and run "git - push" back to /pub/scm/git/git.git/ to update the html - and man branches. + Double check by running - (4) installs generated documentation to /pub/software/scm/git/docs/ - to be viewed from http://www.kernel.org/ + $ git branch --no-merged pu - - Fetch html and man branches back from k.org, and push four - integration branches and the two documentation branches to - repo.or.cz and other mirrors. + to see there is no unexpected leftover topics. + At this point, build-test the result for semantic conflicts, and + if there are, prepare an appropriate merge-fix first (see + appendix), and rebuild the 'pu' branch from scratch, starting at + the tip of 'jch'. + + - Update "What's cooking" message to review the updates to + existing topics, newly added topics and graduated topics. + + This step is helped with Meta/cook script. + + $ Meta/cook + + This script inspects the history between master..pu, finds tips + of topic branches, compares what it found with the current + contents in Meta/whats-cooking.txt, and updates that file. + Topics not listed in the file but are found in master..pu are + added to the "New topics" section, topics listed in the file that + are no longer found in master..pu are moved to the "Graduated to + master" section, and topics whose commits changed their states + (e.g. used to be only in 'pu', now merged to 'next') are updated + with change markers "<<" and ">>". + + Look for lines enclosed in "<<" and ">>"; they hold contents from + old file that are replaced by this integration round. After + verifying them, remove the old part. Review the description for + each topic and update its doneness and plan as needed. To review + the updated plan, run + + $ Meta/cook -w + + which will pick up comments given to the topics, such as "Will + merge to 'next'", etc. (see Meta/cook script to learn what kind + of phrases are supported). + + - Compile, test and install all four (five) integration branches; + Meta/Dothem script may aid this step. + + - Format documentation if the 'master' branch was updated; + Meta/dodoc.sh script may aid this step. + + - Push the integration branches out to public places; Meta/pushall + script may aid this step. + +Observations +------------ Some observations to be made. - * Each topic is tested individually, and also together with - other topics cooking in 'next'. Until it matures, none part - of it is merged to 'master'. + * Each topic is tested individually, and also together with other + topics cooking first in 'pu', then in 'jch' and then in 'next'. + Until it matures, no part of it is merged to 'master'. * A topic already in 'next' can get fixes while still in 'next'. Such a topic will have many merges to 'next' (in other words, "git log --first-parent next" will show many - "Merge ai/topic to next" for the same topic. + "Merge branch 'ai/topic' to next" for the same topic. * An unobvious fix for 'maint' is cooked in 'next' and then merged to 'master' to make extra sure it is Ok and then @@ -278,3 +366,80 @@ Some observations to be made. * Being in the 'next' branch is not a guarantee for a topic to be included in the next feature release. Being in the 'master' branch typically is. + + +Appendix +-------- + +Preparing a "merge-fix" +~~~~~~~~~~~~~~~~~~~~~~~ + +A merge of two topics may not textually conflict but still have +conflict at the semantic level. A classic example is for one topic +to rename an variable and all its uses, while another topic adds a +new use of the variable under its old name. When these two topics +are merged together, the reference to the variable newly added by +the latter topic will still use the old name in the result. + +The Meta/Reintegrate script that is used by redo-jch and redo-pu +scripts implements a crude but usable way to work this issue around. +When the script merges branch $X, it checks if "refs/merge-fix/$X" +exists, and if so, the effect of it is squashed into the result of +the mechanical merge. In other words, + + $ echo $X | Meta/Reintegrate + +is roughly equivalent to this sequence: + + $ git merge --rerere-autoupdate $X + $ git commit + $ git cherry-pick -n refs/merge-fix/$X + $ git commit --amend + +The goal of this "prepare a merge-fix" step is to come up with a +commit that can be squashed into a result of mechanical merge to +correct semantic conflicts. + +After finding that the result of merging branch "ai/topic" to an +integration branch had such a semantic conflict, say pu~4, check the +problematic merge out on a detached HEAD, edit the working tree to +fix the semantic conflict, and make a separate commit to record the +fix-up: + + $ git checkout pu~4 + $ git show -s --pretty=%s ;# double check + Merge branch 'ai/topic' to pu + $ edit + $ git commit -m 'merge-fix/ai/topic' -a + +Then make a reference "refs/merge-fix/ai/topic" to point at this +result: + + $ git update-ref refs/merge-fix/ai/topic HEAD + +Then double check the result by asking Meta/Reintegrate to redo the +merge: + + $ git checkout pu~5 ;# the parent of the problem merge + $ echo ai/topic | Meta/Reintegrate + $ git diff pu~4 + +This time, because you prepared refs/merge-fix/ai/topic, the +resulting merge should have been tweaked to include the fix for the +semantic conflict. + +Note that this assumes that the order in which conflicting branches +are merged does not change. If the reason why merging ai/topic +branch needs this merge-fix is because another branch merged earlier +to the integration branch changed the underlying assumption ai/topic +branch made (e.g. ai/topic branch added a site to refer to a +variable, while the other branch renamed that variable and adjusted +existing use sites), and if you changed redo-jch (or redo-pu) script +to merge ai/topic branch before the other branch, then the above +merge-fix should not be applied while merging ai/topic, but should +instead be applied while merging the other branch. You would need +to move the fix to apply to the other branch, perhaps like this: + + $ mf=refs/merge-fix + $ git update-ref $mf/$the_other_branch $mf/ai/topic + $ git update-ref -d $mf/ai/topic diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt index 944fc39fac..9d3e3527e4 100644 --- a/Documentation/technical/api-directory-listing.txt +++ b/Documentation/technical/api-directory-listing.txt @@ -67,11 +67,13 @@ marked. If you to exclude files, make sure you have loaded index first. * Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0, sizeof(dir))`. -* Call `add_exclude()` to add single exclude pattern, - `add_excludes_from_file()` to add patterns from a file - (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A - short-hand function `setup_standard_excludes()` can be used to set up - the standard set of exclude settings. +* To add single exclude pattern, call `add_exclude_list()` and then + `add_exclude()`. + +* To add patterns from a file (e.g. `.git/info/exclude`), call + `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A + short-hand function `setup_standard_excludes()` can be used to set + up the standard set of exclude settings. * Set options described in the Data Structure section above. @@ -79,4 +81,6 @@ marked. If you to exclude files, make sure you have loaded index first. * Use `dir.entries[]`. +* Call `clear_directory()` when none of the contained elements are no longer in use. + (JC) |