diff options
Diffstat (limited to 'Documentation')
27 files changed, 530 insertions, 60 deletions
diff --git a/Documentation/RelNotes/1.7.10.txt b/Documentation/RelNotes/1.7.10.txt new file mode 100644 index 000000000..d326ff849 --- /dev/null +++ b/Documentation/RelNotes/1.7.10.txt @@ -0,0 +1,216 @@ +Git v1.7.10 Release Notes +========================= + +Compatibility Notes +------------------- + + * From this release on, the "git merge" command in an interactive + session will start an editor when it automatically resolves the + merge for the user to explain the resulting commit, just like the + "git commit" command does when it wasn't given a commit message. + + If you have a script that runs "git merge" and keeps its standard + input and output attached to the user's terminal, and if you do not + want the user to explain the resulting merge commits, you can + export GIT_MERGE_AUTOEDIT environment variable set to "no", like + this: + + #!/bin/sh + GIT_MERGE_AUTOEDIT=no + export GIT_MERGE_AUTOEDIT + + to disable this behaviour (if you want your users to explain their + merge commits, you do not have to do anything). Alternatively, you + can give the "--no-edit" option to individual invocations of the + "git merge" command if you know everybody who uses your script has + Git v1.7.8 or newer. + + * The "--binary/-b" options to "git am" have been a no-op for quite a + while and were deprecated in mid 2008 (v1.6.0). When you give these + options to "git am", it will now warn and ask you not to use them. + + * When you do not tell which branches and tags to push to the "git push" + command in any way, the command used "matching refs" rule to update + remote branches and tags with branches and tags with the same name you + locally have. In future versions of Git, this will change to use the + "upstream" rule to update the branch at the remote you would "pull" + from into your current branch with your local current branch. The + release after 1.7.10 will start issuing a warning about this change, + to encourage you to tell the command what to push out, e.g. by setting + push.default configuration. + + +Updates since v1.7.9 +-------------------- + +UI, Workflows & Features + + * various "gitk" updates. + - show the path to the top level directory in the window title + - update preference edit dialog + - display file list correctly when directories are given on command line + - make "git-describe" output in the log message into a clickable link + - avoid matching the UNIX timestamp part when searching all fields + - give preference to symbolic font names like sans & monospace + - allow comparing two commits using a mark + - "gitk" honors log.showroot configuration. + + * Teams for localizing the messages from the Porcelain layer of + commands are starting to form, thanks to Jiang Xin who volunteered + to be the localization coordinator. Translated messages for + simplified Chinese and Swedish are available. + + * The configuration mechanism learned an "include" facility; an + assignment to the include.path pseudo-variable causes the named + file to be included in-place when Git looks up configuration + variables. + + * A content filter (clean/smudge) used to be just a way to make the + recorded contents "more useful", and allowed to fail; a filter can + now optionally be marked as "required". + + * Options whose names begin with "--no-" (e.g. the "--no-verify" + option of the "git commit" command) can be negated by omitting + "no-" from its name, e.g. "git commit --verify". + + * "git am" learned to pass "-b" option to underlying "git mailinfo", so + that a bracketed string other than "PATCH" at the beginning can be kept. + + * "git clone" learned "--single-branch" option to limit cloning to a + single branch (surprise!); tags that do not point into the history + of the branch are not fetched. + + * "git clone" learned to detach the HEAD in the resulting repository + when the user specifies a tag with "--branch" (e.g., "--branch=v1.0"). + Clone also learned to print the usual "detached HEAD" advice in such + a case, similar to "git checkout v1.0". + + * When showing a patch while ignoring whitespace changes, the context + lines are taken from the postimage, in order to make it easier to + view the output. + + * "git diff --stat" learned to adjust the width of the output on + wider terminals, and give more columns to pathnames as needed. + + * "diff-highlight" filter (in contrib/) was updated to produce more + aesthetically pleasing output. + + * "fsck" learned "--no-dangling" option to omit dangling object + information. + + * "git log -G" and "git log -S" learned to pay attention to the "-i" + option. With "-i", "log -G" ignores the case when finding patch + hunks that introduce or remove a string that matches the given + pattern. Similarly with "-i", "log -S" ignores the case when + finding the commit the given block of text appears or disappears + from the file. + + * "git merge" in an interactive session learned to spawn the editor + by default to let the user edit the auto-generated merge message, + to encourage people to explain their merges better. Legacy scripts + can export GIT_MERGE_AUTOEDIT=no to retain the historical behavior. + Both "git merge" and "git pull" can be given --no-edit from the + command line to accept the auto-generated merge message. + + * The advice message given when the user didn't give enough clue on + what to merge to "git pull" and "git merge" has been updated to + be more concise and easier to understand. + + * "git push" learned the "--prune" option, similar to "git fetch". + + * The whole directory that houses a top-level superproject managed by + "git submodule" can be moved to another place. + + * "git symbolic-ref" learned the "--short" option to abbreviate the + refname it shows unambiguously. + + * "git tag --list" can be given "--points-at <object>" to limit its + output to those that point at the given object. + + * "gitweb" allows intermediate entries in the directory hierarchy + that leads to a project to be clicked, which in turn shows the + list of projects inside that directory. + + * "gitweb" learned to read various pieces of information for the + repositories lazily, instead of reading everything that could be + needed (including the ones that are not necessary for a specific + task). + + * Project search in "gitweb" shows the substring that matched in the + project name and description highlighted. + + * A new script "diffall" is added to contrib/; it drives an + external tool to perform a directory diff of two Git revisions + in one go, unlike "difftool" that compares one file at a time. + +Foreign Interface + + * Improved handling of views, labels and branches in "git-p4" (in contrib). + + * "git-p4" (in contrib) suffered from unnecessary merge conflicts when + p4 expanded the embedded $RCS$-like keywords; it can be now told to + unexpand them. + + * Some "git-svn" updates. + + * "vcs-svn"/"svn-fe" learned to read dumps with svn-deltas and + support incremental imports. + + * "git difftool/mergetool" learned to drive DeltaWalker. + +Performance + + * Unnecessary calls to parse_object() "git upload-pack" makes in + response to "git fetch", have been eliminated, to help performance + in repositories with excessive number of refs. + +Internal Implementation (please report possible regressions) + + * Recursive call chains in "git index-pack" to deal with long delta + chains have been flattened, to reduce the stack footprint. + + * Use of add_extra_ref() API is now gone, to make it possible to + cleanly restructure the overall refs API. + + * The command line parser of "git pack-objects" now uses parse-options + API. + + * The test suite supports the new "test_pause" helper function. + + * Parallel to the test suite, there is a beginning of performance + benchmarking framework. + + * t/Makefile is adjusted to prevent newer versions of GNU make from + running tests in seemingly random order. + + * The code to check if a path points at a file beyond a symbolic link + has been restructured to be thread-safe. + + * When pruning directories that has become empty during "git prune" + and "git prune-packed", call closedir() that iterates over a + directory before rmdir() it. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.9 +------------------ + +Unless otherwise noted, all the fixes since v1.7.9 in the maintenance +releases are contained in this release (see release notes to them for +details). + + * Build with NO_PERL_MAKEMAKER was broken and Git::I18N did not work + with versions of Perl older than 5.8.3. + (merge 5eb660e ab/perl-i18n later to maint). + + * "git tag -s" honored "gpg.program" configuration variable since + 1.7.9, but "git tag -v" and "git verify-tag" didn't. + (merge a2c2506 az/verify-tag-use-gpg-config later to maint). + + * "configure" script learned to take "--with-sane-tool-path" from the + command line to record SANE_TOOL_PATH (used to avoid broken platform + tools in /usr/bin) in config.mak.autogen. This may be useful for + people on Solaris who have saner tools outside /usr/xpg[46]/bin. + + * zsh port of bash completion script needed another workaround. diff --git a/Documentation/config.txt b/Documentation/config.txt index 0e1168c06..c081657be 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -86,6 +86,17 @@ customary UNIX fashion. Some variables may require a special value format. +Includes +~~~~~~~~ + +You can include one config file from another by setting the special +`include.path` variable to the name of the file to be included. The +included file is expanded immediately, as if its contents had been +found at the location of the include directive. If the value of the +`include.path` variable is a relative path, the path is considered to be +relative to the configuration file in which the include directive was +found. See below for examples. + Example ~~~~~~~ @@ -108,6 +119,10 @@ Example gitProxy="ssh" for "kernel.org" gitProxy=default-proxy ; for the rest + [include] + path = /path/to/foo.inc ; include by absolute path + path = foo ; expand "foo" relative to the current file + Variables ~~~~~~~~~ diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 1aed79e7d..6aa1be047 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -52,6 +52,10 @@ directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: `files,10,cumulative`. +diff.statGraphWidth:: + Limit the width of the graph part in --stat output. If set, applies + to all commands generating --stat outuput except format-patch. + diff.external:: If this config variable is set, diff generation is not performed using the internal diff machinery, but using the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index ba7cd1348..378f19f0e 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -56,13 +56,19 @@ endif::git-format-patch[] Generate a diff using the "histogram diff" algorithm. --stat[=<width>[,<name-width>[,<count>]]]:: - Generate a diffstat. You can override the default - output width for 80-column terminal by `--stat=<width>`. - The width of the filename part can be controlled by - giving another width to it separated by a comma. + Generate a diffstat. By default, as much space as necessary + will be used for the filename part, and the rest for the graph + part. Maximum width defaults to terminal width, or 80 columns + if not connected to a terminal, and can be overriden by + `<width>`. The width of the filename part can be limited by + giving another width `<name-width>` after a comma. The width + of the graph part can be limited by using + `--stat-graph-width=<width>` (affects all commands generating + a stat graph) or by setting `diff.statGraphWidth=<width>` + (does not affect `git format-patch`). By giving a third parameter `<count>`, you can limit the - output to the first `<count>` lines, followed by - `...` if there are more. + output to the first `<count>` lines, followed by `...` if + there are more. + These parameters can also be set individually with `--stat-width=<width>`, `--stat-name-width=<name-width>` and `--stat-count=<count>`. @@ -159,11 +165,12 @@ any of those replacements occurred. of the `--diff-filter` option on what the status letters mean. --submodule[=<format>]:: - Chose the output format for submodule differences. <format> can be one of - 'short' and 'log'. 'short' just shows pairs of commit names, this format - is used when this option is not given. 'log' is the default value for this - option and lists the commits in that commit range like the 'summary' - option of linkgit:git-submodule[1] does. + Specify how differences in submodules are shown. When `--submodule` + or `--submodule=log` is given, the 'log' format is used. This format lists + the commits in the range like linkgit:git-submodule[1] `summary` does. + Omitting the `--submodule` option or specifying `--submodule=short`, + uses the 'short' format. This format just shows the names of the commits + at the beginning and end of the range. --color[=<when>]:: Show colored diff. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 887466d77..ee6cca2e1 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -40,6 +40,9 @@ OPTIONS --keep:: Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). +--keep-non-patch:: + Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + --keep-cr:: --no-keep-cr:: With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0427e80a3..6410c3d34 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -24,8 +24,8 @@ be highlighted with an asterisk. Option `-r` causes the remote-tracking 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. +wildcard (i.e., matched using fnmatch(3)). +Multiple patterns may be given; if any of them matches, the branch 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 @@ -49,7 +49,7 @@ the remote-tracking branch. This behavior may be changed via the global overridden by using the `--track` and `--no-track` options, and changed later using `git branch --set-upstream`. -With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. +With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match <newbranch>, and a reflog entry is created to remember the branch renaming. If <newbranch> exists, -M must be used to force the rename @@ -59,7 +59,7 @@ With a `-d` or `-D` option, `<branchname>` will be deleted. You may specify more than one branch for deletion. If the branch currently has a reflog then the reflog will also be deleted. -Use -r together with -d to delete remote-tracking branches. Note, that it +Use `-r` together with `-d` to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist in the remote repository or if 'git fetch' was configured not to fetch them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a @@ -154,17 +154,18 @@ start-point is either a local or remote-tracking branch. branch.autosetupmerge configuration variable is true. --set-upstream:: - If specified branch does not exist yet or if '--force' has been - given, acts exactly like '--track'. Otherwise sets up configuration - like '--track' would when creating the branch, except that where + If specified branch does not exist yet or if `--force` has been + given, acts exactly like `--track`. Otherwise sets up configuration + like `--track` would when creating the branch, except that where branch points to is not changed. --edit-description:: Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. `request-pull`). ---contains <commit>:: - Only list branches which contain the specified commit. +--contains [<commit>]:: + Only list branches which contain the specified commit (HEAD + if not specified). --merged [<commit>]:: Only list branches whose tips are reachable from the diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 4b8b26b75..6e22522c4 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -13,7 +13,8 @@ SYNOPSIS [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--separate-git-dir <git dir>] - [--depth <depth>] [--recursive|--recurse-submodules] [--] <repository> + [--depth <depth>] [--[no-]single-branch] + [--recursive|--recurse-submodules] [--] <repository> [<directory>] DESCRIPTION @@ -146,8 +147,9 @@ objects from the source repository into a pack in the cloned repository. -b <name>:: Instead of pointing the newly created HEAD to the branch pointed to by the cloned repository's HEAD, point to `<name>` branch - instead. In a non-bare repository, this is the branch that will - be checked out. + instead. `--branch` can also take tags and treat them like + detached HEAD. In a non-bare repository, this is the branch + that will be checked out. --upload-pack <upload-pack>:: -u <upload-pack>:: @@ -179,6 +181,14 @@ objects from the source repository into a pack in the cloned repository. with a long history, and would want to send in fixes as patches. +--single-branch:: + Clone only the history leading to the tip of a single branch, + either specified by the `--branch` option or the primary + branch remote's `HEAD` points at. When creating a shallow + clone with the `--depth` option, this is the default, unless + `--no-single-branch` is given to fetch the histories near the + tips of all branches. + --recursive:: --recurse-submodules:: After the clone is created, initialize all submodules within, diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 7617d9eb2..81b03982e 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -181,6 +181,11 @@ See also <<FILES>>. Opens an editor to modify the specified config file; either '--system', '--global', or repository (default). +--includes:: +--no-includes:: + Respect `include.*` directives in config files when looking up + values. Defaults to on. + [[FILES]] FILES ----- diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 19d473c07..fe38f667f 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -32,8 +32,9 @@ OPTIONS --tool=<tool>:: Use the diff tool specified by <tool>. Valid diff tools are: - araxis, bc3, diffuse, emerge, ecmerge, gvimdiff, kdiff3, - kompare, meld, opendiff, p4merge, tkdiff, vimdiff and xxdiff. + araxis, bc3, deltawalker, diffuse, emerge, ecmerge, gvimdiff, + kdiff3, kompare, meld, opendiff, p4merge, tkdiff, vimdiff and + xxdiff. + If a diff tool is not specified, 'git difftool' will use the configuration variable `diff.tool`. If the diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 6c47395ad..bbb25da2d 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] - [--[no-]progress] [<object>*] + [--[no-]dangling] [--[no-]progress] [<object>*] DESCRIPTION ----------- @@ -30,6 +30,11 @@ index file, all SHA1 references in .git/refs/*, and all reflogs (unless Print out objects that exist but that aren't reachable from any of the reference nodes. +--dangling:: +--no-dangling:: + Print objects that exist but that are never 'directly' used (default). + `--no-dangling` can be used to omit this information from the output. + --root:: Report root nodes. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e2e6aba17..3ceefb8a1 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -9,7 +9,7 @@ git-merge - Join two or more development histories together SYNOPSIS -------- [verse] -'git merge' [-n] [--stat] [--no-commit] [--squash] +'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [-s <strategy>] [-X <strategy-option>] [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] 'git merge' <msg> HEAD <commit>... diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index ed827902f..b7c792971 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -318,6 +318,11 @@ around whitespace. Of the possible wildcards, git-p4 only handles '...', and only when it is at the end of the path. Git-p4 will complain if it encounters an unhandled wildcard. +Bugs in the implementation of overlap mappings exist. If multiple depot +paths map through overlays to the same location in the repository, +git-p4 can choose the wrong one. This is hard to solve without +dedicating a client spec just for git-p4. + The name of the client can be given to git-p4 in multiple ways. The variable 'git-p4.client' takes precedence if it exists. Otherwise, normal p4 mechanisms of determining the client are used: environment @@ -482,6 +487,11 @@ git-p4.skipUserNameCheck:: user map, 'git p4' exits. This option can be used to force submission regardless. +git-p4.attemptRCSCleanup: + If enabled, 'git p4 submit' will attempt to cleanup RCS keywords + ($Header$, etc). These would otherwise cause merge conflicts and prevent + the submit going ahead. This option should be considered experimental at + present. IMPLEMENTATION DETAILS ---------------------- diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index aede48877..48760db33 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream] + [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] [<repository> [<refspec>...]] DESCRIPTION @@ -71,6 +71,14 @@ nor in any Push line of the corresponding remotes file---see below). Instead of naming each ref to push, specifies that all refs under `refs/heads/` be pushed. +--prune:: + Remove remote branches that don't have a local counterpart. For example + a remote branch `tmp` will be removed if a local branch with the same + name doesn't exist any more. This also respects refspecs, e.g. + `git push --prune remote refs/heads/{asterisk}:refs/tmp/{asterisk}` would + make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo` + doesn't exist. + --mirror:: Instead of naming each ref to push, specifies that all refs under `refs/` (which includes but is not diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 40af32115..4c1aff65e 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -34,7 +34,7 @@ OPTIONS Especially useful when packing a repository that is used for private development. Use with '-d'. This will clean up the objects that `git prune` - leaves behind, but `git fsck --full` shows as + leaves behind, but `git fsck --full --dangling` shows as dangling. + Note that users fetching over dumb protocols will have to fetch the diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 327233c85..324117072 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -198,6 +198,10 @@ must be used for each option. if a username is not specified (with '--smtp-user' or 'sendemail.smtpuser'), then authentication is not attempted. +--smtp-debug=0|1:: + Enable (1) or disable (0) debug output. If enabled, SMTP + commands and replies will be printed. Useful to debug TLS + connection and authentication problems. Automating ~~~~~~~~~~ diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt index 5c3ec327b..2ffaf9392 100644 --- a/Documentation/git-sh-i18n--envsubst.txt +++ b/Documentation/git-sh-i18n--envsubst.txt @@ -25,7 +25,7 @@ plumbing scripts and/or are writing new ones. 'git sh-i18n{litdd}envsubst' is Git's stripped-down copy of the GNU `envsubst(1)` program that comes with the GNU gettext package. It's used internally by linkgit:git-sh-i18n[1] to interpolate the variables -passed to the the `eval_gettext` function. +passed to the `eval_gettext` function. No promises are made about the interface, or that this program won't disappear without warning in the next version diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index b72964947..c243ee552 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -190,7 +190,7 @@ commit for each submodule. sync:: Synchronizes submodules' remote URL configuration setting to the value specified in .gitmodules. It will only affect those - submodules which already have an url entry in .git/config (that is the + submodules which already have a URL entry in .git/config (that is the case when they are initialized or freshly added). This is useful when submodule URLs change upstream and you need to update your local repositories accordingly. diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index a45d4c4f2..981d3a8fc 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -8,7 +8,8 @@ git-symbolic-ref - Read and modify symbolic refs SYNOPSIS -------- [verse] -'git symbolic-ref' [-q] [-m <reason>] <name> [<ref>] +'git symbolic-ref' [-m <reason>] <name> <ref> +'git symbolic-ref' [-q] [--short] <name> DESCRIPTION ----------- @@ -33,6 +34,10 @@ OPTIONS symbolic ref but a detached HEAD; instead exit with non-zero status silently. +--short:: + When showing the value of <name> as a symbolic ref, try to shorten the + value, e.g. from `refs/heads/master` to `master`. + -m:: Update the reflog for <name> with <reason>. This is valid only when creating or updating a symbolic ref. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 53ff5f6cf..8d32b9a81 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -12,7 +12,8 @@ SYNOPSIS 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... -'git tag' [-n[<num>]] -l [--contains <commit>] [<pattern>...] +'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] + [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION @@ -86,6 +87,9 @@ OPTIONS --contains <commit>:: Only list tags which contain the specified commit. +--points-at <object>:: + Only list tags of the given object. + -m <msg>:: --message=<msg>:: Use the given tag message (instead of prompting). diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index a85b187e0..80120ea14 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -294,16 +294,27 @@ output is used to update the worktree file. Similarly, the `clean` command is used to convert the contents of worktree file upon checkin. -A missing filter driver definition in the config is not an error -but makes the filter a no-op passthru. - -The content filtering is done to massage the content into a -shape that is more convenient for the platform, filesystem, and -the user to use. The key phrase here is "more convenient" and not -"turning something unusable into usable". In other words, the -intent is that if someone unsets the filter driver definition, -or does not have the appropriate filter program, the project -should still be usable. +One use of the content filtering is to massage the content into a shape +that is more convenient for the platform, filesystem, and the user to use. +For this mode of operation, the key phrase here is "more convenient" and +not "turning something unusable into usable". In other words, the intent +is that if someone unsets the filter driver definition, or does not have +the appropriate filter program, the project should still be usable. + +Another use of the content filtering is to store the content that cannot +be directly used in the repository (e.g. a UUID that refers to the true +content stored outside git, or an encrypted content) and turn it into a +usable form upon checkout (e.g. download the external content, or decrypt +the encrypted content). + +These two filters behave differently, and by default, a filter is taken as +the former, massaging the contents into more convenient shape. A missing +filter driver definition in the config, or a filter driver that exits with +a non-zero status, is not an error but makes the filter a no-op passthru. + +You can declare that a filter turns a content that by itself is unusable +into a usable content by setting the filter.<driver>.required configuration +variable to `true`. For example, in .gitattributes, you would assign the `filter` attribute for paths. @@ -335,6 +346,16 @@ input that is already correctly indented. In this case, the lack of a smudge filter means that the clean filter _must_ accept its own output without modifying it. +If a filter _must_ succeed in order to make the stored contents usable, +you can declare that the filter is `required`, in the configuration: + +------------------------ +[filter "crypt"] + clean = openssl enc ... + smudge = openssl enc -d ... + required +------------------------ + Sequence "%f" on the filter command line is replaced with the name of the file the filter is working on. A filter might use this in keyword substitution. For example: diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 4040941e5..4e1fd52e7 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -28,7 +28,7 @@ submodule.<name>.path:: be unique within the .gitmodules file. submodule.<name>.url:: - Defines an url from where the submodule repository can be cloned. + Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to linkgit:git-clone[1] or (if it begins with ./ or ../) a location relative to the superproject's origin repository. @@ -84,7 +84,7 @@ Consider the following .gitmodules file: This defines two submodules, `libfoo` and `libbar`. These are expected to be checked out in the paths 'include/foo' and 'include/bar', and for both -submodules an url is specified which can be used for cloning the submodules. +submodules a URL is specified which can be used for cloning the submodules. SEE ALSO -------- diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 605a08532..168e8bfed 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -14,7 +14,7 @@ gitweb. DESCRIPTION ----------- -Gitweb provides a web interface to git repositories. It's features include: +Gitweb provides a web interface to git repositories. Its features include: * Viewing multiple Git repositories with common root. * Browsing every revision of the repository. @@ -60,7 +60,7 @@ to gitweb. The list of projects is generated by default by scanning the more exact; gitweb is not interested in a working area, and is best suited to showing "bare" repositories). -The name of repository in gitweb is path to it's `$GIT_DIR` (it's object +The name of the repository in gitweb is the path to its `$GIT_DIR` (its object database) relative to `$projectroot`. Therefore the repository $repo can be found at "$projectroot/$repo". diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index 293305612..1ae8d1214 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -25,7 +25,7 @@ What you want is the 'subtree' merge strategy, which helps you in such a situation. In this example, let's say you have the repository at `/path/to/B` (but -it can be an URL as well, if you want). You want to merge the 'master' +it can be a URL as well, if you want). You want to merge the 'master' branch of that repository to the `dir-B` subdirectory in your current branch. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 2bd92c474..0bcbe0ac3 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -8,9 +8,20 @@ failed and do not autocommit, to give the user a chance to inspect and further tweak the merge result before committing. --edit:: --e:: - Invoke editor before committing successful merge to further - edit the default merge message. +--no-edit:: + Invoke an editor before committing successful mechanical merge to + further edit the auto-generated merge message, so that the user + can explain and justify the merge. The `--no-edit` option can be + used to accept the auto-generated message (this is generally + discouraged). The `--edit` option is still useful if you are + giving a draft message with the `-m` option from the command line + and want to edit it in the editor. ++ +Older scripts may depend on the historical behaviour of not allowing the +user to edit the merge log message. They will see an editor opened when +they run `git merge`. To make it easier to adjust such scripts to the +updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be +set to `no` at the beginning of them. --ff:: When the merge resolves as a fast-forward, only update the branch diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt new file mode 100644 index 000000000..edf8dfb99 --- /dev/null +++ b/Documentation/technical/api-config.txt @@ -0,0 +1,140 @@ +config API +========== + +The config API gives callers a way to access git configuration files +(and files which have the same syntax). See linkgit:git-config[1] for a +discussion of the config file syntax. + +General Usage +------------- + +Config files are parsed linearly, and each variable found is passed to a +caller-provided callback function. The callback function is responsible +for any actions to be taken on the config option, and is free to ignore +some options. It is not uncommon for the configuration to be parsed +several times during the run of a git program, with different callbacks +picking out different variables useful to themselves. + +A config callback function takes three parameters: + +- the name of the parsed variable. This is in canonical "flat" form: the + section, subsection, and variable segments will be separated by dots, + and the section and variable segments will be all lowercase. E.g., + `core.ignorecase`, `diff.SomeType.textconv`. + +- the value of the found variable, as a string. If the variable had no + value specified, the value will be NULL (typically this means it + should be interpreted as boolean true). + +- a void pointer passed in by the caller of the config API; this can + contain callback-specific data + +A config callback should return 0 for success, or -1 if the variable +could not be parsed properly. + +Basic Config Querying +--------------------- + +Most programs will simply want to look up variables in all config files +that git knows about, using the normal precedence rules. To do this, +call `git_config` with a callback function and void data pointer. + +`git_config` will read all config sources in order of increasing +priority. Thus a callback should typically overwrite previously-seen +entries with new ones (e.g., if both the user-wide `~/.gitconfig` and +repo-specific `.git/config` contain `color.ui`, the config machinery +will first feed the user-wide one to the callback, and then the +repo-specific one; by overwriting, the higher-priority repo-specific +value is left at the end). + +The `git_config_with_options` function lets the caller examine config +while adjusting some of the default behavior of `git_config`. It should +almost never be used by "regular" git code that is looking up +configuration variables. It is intended for advanced callers like +`git-config`, which are intentionally tweaking the normal config-lookup +process. It takes two extra parameters: + +`filename`:: +If this parameter is non-NULL, it specifies the name of a file to +parse for configuration, rather than looking in the usual files. Regular +`git_config` defaults to `NULL`. + +`respect_includes`:: +Specify whether include directives should be followed in parsed files. +Regular `git_config` defaults to `1`. + +There is a special version of `git_config` called `git_config_early`. +This version takes an additional parameter to specify the repository +config, instead of having it looked up via `git_path`. This is useful +early in a git program before the repository has been found. Unless +you're working with early setup code, you probably don't want to use +this. + +Reading Specific Files +---------------------- + +To read a specific file in git-config format, use +`git_config_from_file`. This takes the same callback and data parameters +as `git_config`. + +Value Parsing Helpers +--------------------- + +To aid in parsing string values, the config API provides callbacks with +a number of helper functions, including: + +`git_config_int`:: +Parse the string to an integer, including unit factors. Dies on error; +otherwise, returns the parsed result. + +`git_config_ulong`:: +Identical to `git_config_int`, but for unsigned longs. + +`git_config_bool`:: +Parse a string into a boolean value, respecting keywords like "true" and +"false". Integer values are converted into true/false values (when they +are non-zero or zero, respectively). Other values cause a die(). If +parsing is successful, the return value is the result. + +`git_config_bool_or_int`:: +Same as `git_config_bool`, except that integers are returned as-is, and +an `is_bool` flag is unset. + +`git_config_maybe_bool`:: +Same as `git_config_bool`, except that it returns -1 on error rather +than dying. + +`git_config_string`:: +Allocates and copies the value string into the `dest` parameter; if no +string is given, prints an error message and returns -1. + +`git_config_pathname`:: +Similar to `git_config_string`, but expands `~` or `~user` into the +user's home directory when found at the beginning of the path. + +Include Directives +------------------ + +By default, the config parser does not respect include directives. +However, a caller can use the special `git_config_include` wrapper +callback to support them. To do so, you simply wrap your "real" callback +function and data pointer in a `struct config_include_data`, and pass +the wrapper to the regular config-reading functions. For example: + +------------------------------------------- +int read_file_with_include(const char *file, config_fn_t fn, void *data) +{ + struct config_include_data inc = CONFIG_INCLUDE_INIT; + inc.fn = fn; + inc.data = data; + return git_config_from_file(git_config_include, file, &inc); +} +------------------------------------------- + +`git_config` respects includes automatically. The lower-level +`git_config_from_file` does not. + +Writing Config Files +-------------------- + +TODO diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 4b92514f6..2527b7e8d 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -39,7 +39,8 @@ The parse-options API allows: * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`. * Boolean long options can be 'negated' (or 'unset') by prepending - `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`. + `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`. Conversely, + options that begin with `no-` can be 'negated' by removing it. * Options and non-option arguments can clearly be separated using the `\--` option, e.g. `-a -b \--option \-- \--this-is-a-file` indicates that diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index f13a84613..6c7fee7ef 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1582,7 +1582,7 @@ Checking the repository for corruption The linkgit:git-fsck[1] command runs a number of self-consistency checks on the repository, and reports on any problems. This may take some -time. The most common warning by far is about "dangling" objects: +time. ------------------------------------------------- $ git fsck @@ -1597,9 +1597,11 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f ... ------------------------------------------------- -Dangling objects are not a problem. At worst they may take up a little -extra disk space. They can sometimes provide a last-resort method for -recovering lost work--see <<dangling-objects>> for details. +You will see informational messages on dangling objects. They are objects +that still exist in the repository but are no longer referenced by any of +your branches, and can (and will) be removed after a while with "gc". +You can run `git fsck --no-dangling` to supress these messages, and still +view real errors. [[recovering-lost-changes]] Recovering lost changes @@ -3295,15 +3297,12 @@ it is with linkgit:git-fsck[1]; this may be time-consuming. Assume the output looks like this: ------------------------------------------------ -$ git fsck --full +$ git fsck --full --no-dangling broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 to blob 4b9458b3786228369c63936db65827de3cc06200 missing blob 4b9458b3786228369c63936db65827de3cc06200 ------------------------------------------------ -(Typically there will be some "dangling object" messages too, but they -aren't interesting.) - Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 points to it. If you could find just one copy of that missing blob object, possibly in some other repository, you could move it into |