diff options
Diffstat (limited to 'Documentation')
51 files changed, 2389 insertions, 119 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index fe1c1e5..4557711 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -35,10 +35,22 @@ For shell scripts specifically (not exhaustive): - Case arms are indented at the same depth as case and esac lines. + - Redirection operators should be written with space before, but no + space after them. In other words, write 'echo test >"$file"' + instead of 'echo test> $file' or 'echo test > $file'. Note that + even though it is not required by POSIX to double-quote the + redirection target in a variable (as shown above), our code does so + because some versions of bash issue a warning without the quotes. + - We prefer $( ... ) for command substitution; unlike ``, it properly nests. It should have been the way Bourne spelled it from day one, but unfortunately isn't. + - If you want to find out if a command is available on the user's + $PATH, you should use 'type <command>', instead of 'which <command>'. + The output of 'which' is not machine parseable and its exit code + is not reliable across platforms. + - We use POSIX compliant parameter substitutions and avoid bashisms; namely: @@ -81,6 +93,10 @@ For shell scripts specifically (not exhaustive): are ERE elements not BRE (note that \? and \+ are not even part of BRE -- making them accessible from BRE is a GNU extension). + - Use Git's gettext wrappers in git-sh-i18n to make the user + interface translatable. See "Marking strings for translation" in + po/README. + For C programs: - We use tabs to indent, and interpret tabs as taking up to @@ -144,6 +160,9 @@ For C programs: - When we pass <string, length> pair to functions, we should try to pass them in that order. + - Use Git's gettext wrappers to make the user interface + translatable. See "Marking strings for translation" in po/README. + Writing Documentation: Every user-visible change should be reflected in the documentation. diff --git a/Documentation/Makefile b/Documentation/Makefile index 304b31e..d40e211 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -7,6 +7,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \ gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt +MAN7_TXT += gitcredentials.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) @@ -19,7 +20,10 @@ ARTICLES += everyday ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. -SP_ARTICLES = howto/revert-branch-rebase howto/using-merge-subtree user-manual +SP_ARTICLES = user-manual +SP_ARTICLES += howto/revert-branch-rebase +SP_ARTICLES += howto/using-merge-subtree +SP_ARTICLES += howto/using-signed-tag-in-pull-request API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) SP_ARTICLES += technical/api-index diff --git a/Documentation/RelNotes/1.7.10.txt b/Documentation/RelNotes/1.7.10.txt new file mode 100644 index 0000000..238234e --- /dev/null +++ b/Documentation/RelNotes/1.7.10.txt @@ -0,0 +1,214 @@ +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. + + +Updates since v1.7.9 +-------------------- + +UI, Workflows & Features + + * 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. An initial set of translated + messages for simplified chinese is 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). + + * "git fast-import" accepted "ls" command with an empty path by + mistake. + (merge 178e1de jn/maint-fast-import-empty-ls later to maint). + + * The "remaining" subcommand to "git rerere" was not documented. + (merge 3e7a1df ph/rerere-doc 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). + + * When "git config" diagnoses an error in a configuration file and + shows the line number for the offending line, it miscounted if the + error was at the end of line. + (merge 4b34059 ms/maint-config-error-at-eol-linecount later to maint). + + * "configure" script learned to take "--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. + + * "gitweb" used to drop warnings in the log file when "heads" view is + accessed in a repository whose HEAD does not point at a valid + branch. + +--- +exec >/var/tmp/1 +O=v1.7.10-rc1-18-g0987145 +echo O=$(git describe) +git log --first-parent --oneline ^maint $O.. +echo +git shortlog --no-merges ^maint $O.. diff --git a/Documentation/RelNotes/1.7.9.1.txt b/Documentation/RelNotes/1.7.9.1.txt new file mode 100644 index 0000000..6957183 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.1.txt @@ -0,0 +1,63 @@ +Git v1.7.9.1 Release Notes +========================== + +Fixes since v1.7.9 +------------------ + + * The makefile allowed environment variable X seep into it result in + command names suffixed with unnecessary strings. + + * The set of included header files in compat/inet-{ntop,pton} + wrappers was updated for Windows some time ago, but in a way that + broke Solaris build. + + * rpmbuild noticed an unpackaged but installed *.mo file and failed. + + * Subprocesses spawned from various git programs were often left running + to completion even when the top-level process was killed. + + * "git add -e" learned not to show a diff for an otherwise unmodified + submodule that only has uncommitted local changes in the patch + prepared by for the user to edit. + + * Typo in "git branch --edit-description my-tpoic" was not diagnosed. + + * Using "git grep -l/-L" together with options -W or --break may not + make much sense as the output is to only count the number of hits + and there is no place for file breaks, but the latter options made + "-l/-L" to miscount the hits. + + * "git log --first-parent $pathspec" did not stay on the first parent + chain and veered into side branch from which the whole change to the + specified paths came. + + * "git merge --no-edit $tag" failed to honor the --no-edit option. + + * "git merge --ff-only $tag" failed because it cannot record the + required mergetag without creating a merge, but this is so common + operation for branch that is used _only_ to follow the upstream, so + it was changed to allow fast-forwarding without recording the mergetag. + + * "git mergetool" now gives an empty file as the common base version + to the backend when dealing with the "both sides added, differently" + case. + + * "git push -q" was not sufficiently quiet. + + * When "git push" fails to update any refs, the client side did not + report an error correctly to the end user. + + * "rebase" and "commit --amend" failed to work on commits with ancient + timestamps near year 1970. + + * When asking for a tag to be pulled, "request-pull" did not show the + name of the tag prefixed with "tags/", which would have helped older + clients. + + * "git submodule add $path" forgot to recompute the name to be stored + in .gitmodules when the submodule at $path was once added to the + superproject and already initialized. + + * Many small corner case bugs on "git tag -n" was corrected. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.2.txt b/Documentation/RelNotes/1.7.9.2.txt new file mode 100644 index 0000000..e500da7 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.2.txt @@ -0,0 +1,69 @@ +Git v1.7.9.2 Release Notes +========================== + +Fixes since v1.7.9.1 +-------------------- + + * Bash completion script (in contrib/) did not like a pattern that + begins with a dash to be passed to __git_ps1 helper function. + + * Adaptation of the bash completion script (in contrib/) for zsh + incorrectly listed all subcommands when "git <TAB><TAB>" was given + to ask for list of porcelain subcommands. + + * The build procedure for profile-directed optimized binary was not + working very well. + + * Some systems need to explicitly link -lcharset to get locale_charset(). + + * t5541 ignored user-supplied port number used for HTTP server testing. + + * The error message emitted when we see an empty loose object was + not phrased correctly. + + * The code to ask for password did not fall back to the terminal + input when GIT_ASKPASS is set but does not work (e.g. lack of X + with GUI askpass helper). + + * We failed to give the true terminal width to any subcommand when + they are invoked with the pager, i.e. "git -p cmd". + + * map_user() was not rewriting its output correctly, which resulted + in the user visible symptom that "git blame -e" sometimes showed + excess '>' at the end of email addresses. + + * "git checkout -b" did not allow switching out of an unborn branch. + + * When you have both .../foo and .../foo.git, "git clone .../foo" did not + favor the former but the latter. + + * "git commit" refused to create a commit when entries added with + "add -N" remained in the index, without telling Git what their content + in the next commit should be. We should have created the commit without + these paths. + + * "git diff --stat" said "files", "insertions", and "deletions" even + when it is showing one "file", one "insertion" or one "deletion". + + * The output from "git diff --stat" for two paths that have the same + amount of changes showed graph bars of different length due to the + way we handled rounding errors. + + * "git grep" did not pay attention to -diff (hence -binary) attribute. + + * The transport programs (fetch, push, clone)ignored --no-progress + and showed progress when sending their output to a terminal. + + * Sometimes error status detected by a check in an earlier phase of + "git receive-pack" (the other end of "git push") was lost by later + checks, resulting in false indication of success. + + * "git rev-list --verify" sometimes skipped verification depending on + the phase of the moon, which dates back to 1.7.8.x series. + + * Search box in "gitweb" did not accept non-ASCII characters correctly. + + * Search interface of "gitweb" did not show multiple matches in the same file + correctly. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.3.txt b/Documentation/RelNotes/1.7.9.3.txt new file mode 100644 index 0000000..91c6501 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.3.txt @@ -0,0 +1,51 @@ +Git v1.7.9.3 Release Notes +========================== + +Fixes since v1.7.9.2 +-------------------- + + * "git p4" (in contrib/) submit the changes to a wrong place when the + "--use-client-spec" option is set. + + * The config.mak.autogen generated by optional autoconf support tried + to link the binary with -lintl even when libintl.h is missing from + the system. + + * When the filter driver exits before reading the content before the + main git process writes the contents to be filtered to the pipe to + it, the latter could be killed with SIGPIPE instead of ignoring + such an event as an error. + + * "git add --refresh <pathspec>" used to warn about unmerged paths + outside the given pathspec. + + * The bulk check-in codepath in "git add" streamed contents that + needs smudge/clean filters without running them, instead of punting + and delegating to the codepath to run filters after slurping + everything to core. + + * "git branch --with $that" assumed incorrectly that the user will never + ask the question with nonsense value in $that. + + * "git bundle create" produced a corrupt bundle file upon seeing + commits with excessively long subject line. + + * When a remote helper exits before reading the blank line from the + main git process to signal the end of commands, the latter could be + killed with SIGPIPE. Instead we should ignore such event as a + non-error. + + * The commit log template given with "git merge --edit" did not have + a short instructive text like what "git commit" gives. + + * "git rev-list --verify-objects -q" omitted the extra verification + it needs to do over "git rev-list --objects -q" by mistake. + + * "gitweb" used to drop warnings in the log file when "heads" view is + accessed in a repository whose HEAD does not point at a valid + branch. + + * An invalid regular expression pattern given by an end user made + "gitweb" to return garbled response. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.4.txt b/Documentation/RelNotes/1.7.9.4.txt new file mode 100644 index 0000000..e5217a1 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.4.txt @@ -0,0 +1,24 @@ +Git v1.7.9.4 Release Notes +========================== + +Fixes since v1.7.9.3 +-------------------- + + * The code to synthesize the fake ancestor tree used by 3-way merge + fallback in "git am" was not prepared to read a patch created with + a non-standard -p<num> value. + + * "git bundle" did not record boundary commits correctly when there + are many of them. + + * "git diff-index" and its friends at the plumbing level showed the + "diff --git" header and nothing else for a path whose cached stat + info is dirty without actual difference when asked to produce a + patch. This was a longstanding bug that we could have fixed long + time ago. + + * "gitweb" did use quotemeta() to prepare search string when asked to + do a fixed-string project search, but did not use it by mistake and + used the user-supplied string instead. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.txt b/Documentation/RelNotes/1.7.9.txt new file mode 100644 index 0000000..95320aa --- /dev/null +++ b/Documentation/RelNotes/1.7.9.txt @@ -0,0 +1,112 @@ +Git v1.7.9 Release Notes +======================== + +Updates since v1.7.8 +-------------------- + + * gitk updates accumulated since early 2011. + + * git-gui updated to 0.16.0. + + * git-p4 (in contrib/) updates. + + * Git uses gettext to translate its most common interface messages + into the user's language if translations are available and the + locale is appropriately set. Distributors can drop new PO files + in po/ to add new translations. + + * The code to handle username/password for HTTP transactions used in + "git push" & "git fetch" learned to talk "credential API" to + external programs to cache or store them, to allow integration with + platform native keychain mechanisms. + + * The input prompts in the terminal use our own getpass() replacement + when possible. HTTP transactions used to ask for the username without + echoing back what was typed, but with this change you will see it as + you type. + + * The internals of "revert/cherry-pick" have been tweaked to prepare + building more generic "sequencer" on top of the implementation that + drives them. + + * "git rev-parse FETCH_HEAD" after "git fetch" without specifying + what to fetch from the command line will now show the commit that + would be merged if the command were "git pull". + + * "git add" learned to stream large files directly into a packfile + instead of writing them into individual loose object files. + + * "git checkout -B <current branch> <elsewhere>" is a more intuitive + way to spell "git reset --keep <elsewhere>". + + * "git checkout" and "git merge" learned "--no-overwrite-ignore" option + to tell Git that untracked and ignored files are not expendable. + + * "git commit --amend" learned "--no-edit" option to say that the + user is amending the tree being recorded, without updating the + commit log message. + + * "git commit" and "git reset" re-learned the optimization to prime + the cache-tree information in the index, which makes it faster to + write a tree object out after the index entries are updated. + + * "git commit" detects and rejects an attempt to stuff NUL byte in + the commit log message. + + * "git commit" learned "-S" to GPG-sign the commit; this can be shown + with the "--show-signature" option to "git log". + + * fsck and prune are relatively lengthy operations that still go + silent while making the end-user wait. They learned to give progress + output like other slow operations. + + * The set of built-in function-header patterns for various languages + knows MATLAB. + + * "git log --format='<format>'" learned new %g[nNeE] specifiers to + show information from the reflog entries when walking the reflog + (i.e. with "-g"). + + * "git pull" can be used to fetch and merge an annotated/signed tag, + instead of the tip of a topic branch. The GPG signature from the + signed tag is recorded in the resulting merge commit for later + auditing. + + * "git log" learned "--show-signature" option to show the signed tag + that was merged that is embedded in the merge commit. It also can + show the signature made on the commit with "git commit -S". + + * "git branch --edit-description" can be used to add descriptive text + to explain what a topic branch is about. + + * "git fmt-merge-msg" learned to take the branch description into + account when preparing a merge summary that "git merge" records + when merging a local branch. + + * "git request-pull" has been updated to convey more information + useful for integrators to decide if a topic is worth merging and + what is pulled is indeed what the requestor asked to pull, + including: + + - the tip of the branch being requested to be merged; + - the branch description describing what the topic is about; + - the contents of the annotated tag, when requesting to pull a tag. + + * "git pull" learned to notice 'pull.rebase' configuration variable, + which serves as a global fallback for setting 'branch.<name>.rebase' + configuration variable per branch. + + * "git tag" learned "--cleanup" option to control how the whitespaces + and empty lines in tag message are cleaned up. + + * "gitweb" learned to show side-by-side diff. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.8 +------------------ + +Unless otherwise noted, all the fixes since v1.7.8 in the maintenance +releases are contained in this release (see release notes to them for +details). diff --git a/Documentation/config.txt b/Documentation/config.txt index 9fba453..c081657 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -12,8 +12,9 @@ The configuration variables are used by both the git plumbing and the porcelains. The variables are divided into sections, wherein the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last -dot. The variable names are case-insensitive and only alphanumeric -characters are allowed. Some variables may appear multiple times. +dot. The variable names are case-insensitive, allow only alphanumeric +characters and `-`, and must start with an alphabetic character. Some +variables may appear multiple times. Syntax ~~~~~~ @@ -54,9 +55,10 @@ All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form 'name = value'. If there is no equal sign on the line, the entire line is taken as 'name' and the variable is recognized as boolean "true". -The variable names are case-insensitive and only alphanumeric -characters and `-` are allowed. There can be more than one value -for a given variable; we say then that variable is multivalued. +The variable names are case-insensitive, allow only alphanumeric characters +and `-`, and must start with an alphabetic character. There can be more +than one value for a given variable; we say then that the variable is +multivalued. Leading and trailing whitespace in a variable value is discarded. Internal whitespace within a variable value is retained verbatim. @@ -84,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 ~~~~~~~ @@ -106,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 ~~~~~~~~~ @@ -674,10 +691,12 @@ branch.<name>.mergeoptions:: branch.<name>.rebase:: When true, rebase the branch <name> on top of the fetched branch, instead of merging the default branch from the default remote when - "git pull" is run. - *NOTE*: this is a possibly dangerous operation; do *not* use - it unless you understand the implications (see linkgit:git-rebase[1] - for details). + "git pull" is run. See "pull.rebase" for doing this in a non + branch-specific manner. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +for details). browser.<tool>.cmd:: Specify the command to invoke the specified browser. The @@ -829,6 +848,29 @@ commit.template:: "{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the specified user's home directory. +credential.helper:: + Specify an external helper to be called when a username or + password credential is needed; the helper may consult external + storage to avoid prompting the user for the credentials. See + linkgit:gitcredentials[7] for details. + +credential.useHttpPath:: + When acquiring credentials, consider the "path" component of an http + or https URL to be important. Defaults to false. See + linkgit:gitcredentials[7] for more information. + +credential.username:: + If no username is set for a network authentication, use this username + by default. See credential.<context>.* below, and + linkgit:gitcredentials[7]. + +credential.<url>.*:: + Any of the credential.* options above can be applied selectively to + some credentials. For example "credential.https://example.com.username" + would set the default username only for https connections to + example.com. See linkgit:gitcredentials[7] for details on how URLs are + matched. + include::diff-config.txt[] difftool.<tool>.path:: @@ -1098,6 +1140,17 @@ grep.lineNumber:: grep.extendedRegexp:: If set to true, enable '--extended-regexp' option by default. +gpg.program:: + Use this custom program instead of "gpg" found on $PATH when + making or verifying a PGP signature. The program must support the + same command line interface as GPG, namely, to verify a detached + signature, "gpg --verify $file - <$signature" is run, and the + program is expected to signal a good signature by exiting with + code 0, and to generate an ascii-armored detached signature, the + standard input of "gpg -bsau $key" is fed with the contents to be + signed, and the program is expected to send the result to its + standard output. + gui.commitmsgwidth:: Defines how wide the commit message window is in the linkgit:git-gui[1]. "75" is the default. @@ -1222,9 +1275,10 @@ help.autocorrect:: This is the default. http.proxy:: - Override the HTTP proxy, normally configured using the 'http_proxy' - environment variable (see linkgit:curl[1]). This can be overridden - on a per-remote basis; see remote.<name>.proxy + Override the HTTP proxy, normally configured using the 'http_proxy', + 'https_proxy', and 'all_proxy' environment variables (see + `curl(1)`). This can be overridden on a per-remote basis; see + remote.<name>.proxy http.cookiefile:: File containing previously stored cookie lines which should be used @@ -1587,6 +1641,16 @@ pretty.<name>:: Note that an alias with the same name as a built-in format will be silently ignored. +pull.rebase:: + When true, rebase branches on top of the fetched branch, instead + of merging the default branch from the default remote when "git + pull" is run. See "branch.<name>.rebase" for setting this on a + per-branch basis. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand the implications (see linkgit:git-rebase[1] +for details). + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 1aed79e..6aa1be0 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 ba7cd13..378f19f 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 887466d..ee6cca2 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 f46013c..6410c3d 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -14,6 +14,7 @@ SYNOPSIS 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> 'git branch' (-d | -D) [-r] <branchname>... +'git branch' --edit-description [<branchname>] DESCRIPTION ----------- @@ -23,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 @@ -48,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 @@ -58,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 @@ -153,13 +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. ---contains <commit>:: - Only list branches which contain the specified commit. +--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 (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 4b8b26b..6e22522 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-commit-tree.txt b/Documentation/git-commit-tree.txt index 02133d5..cfb9906 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -9,7 +9,8 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- [verse] -'git commit-tree' <tree> [(-p <parent commit>)...] < changelog +'git commit-tree' <tree> [(-p <parent>)...] < changelog +'git commit-tree' [(-p <parent>)...] [(-m <message>)...] [(-F <file>)...] <tree> DESCRIPTION ----------- @@ -17,7 +18,8 @@ This is usually not what an end user wants to run directly. See linkgit:git-commit[1] instead. Creates a new commit object based on the provided tree object and -emits the new commit object id on stdout. +emits the new commit object id on stdout. The log message is read +from the standard input, unless `-m` or `-F` options are given. A commit object may have any number of parents. With exactly one parent, it is an ordinary commit. Having more than one parent makes @@ -39,9 +41,17 @@ OPTIONS <tree>:: An existing tree object --p <parent commit>:: +-p <parent>:: Each '-p' indicates the id of a parent commit object. +-m <message>:: + A paragraph in the commig log message. This can be given more than + once and each <message> becomes its own paragraph. + +-F <file>:: + Read the commit log message from the given file. Use `-` to read + from the standard input. + Commit Information ------------------ diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index e7ecf5d..81b0398 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -85,8 +85,11 @@ OPTIONS is not exactly one. --get-regexp:: - Like --get-all, but interprets the name as a regular expression. - Also outputs the key names. + Like --get-all, but interprets the name as a regular expression and + writes out the key names. Regular expression matching is currently + case-sensitive and done against a canonicalized version of the key + in which section and variable names are lowercased, but subsection + names are not. --global:: For writing options: write to global ~/.gitconfig file rather than @@ -178,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-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt new file mode 100644 index 0000000..11edc5a --- /dev/null +++ b/Documentation/git-credential-cache--daemon.txt @@ -0,0 +1,26 @@ +git-credential-cache--daemon(1) +=============================== + +NAME +---- +git-credential-cache--daemon - temporarily store user credentials in memory + +SYNOPSIS +-------- +[verse] +git credential-cache--daemon <socket> + +DESCRIPTION +----------- + +NOTE: You probably don't want to invoke this command yourself; it is +started automatically when you use linkgit:git-credential-cache[1]. + +This command listens on the Unix domain socket specified by `<socket>` +for `git-credential-cache` clients. Clients may store and retrieve +credentials. Each credential is held for a timeout specified by the +client; once no credentials are held, the daemon exits. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt new file mode 100644 index 0000000..f3d09c5 --- /dev/null +++ b/Documentation/git-credential-cache.txt @@ -0,0 +1,77 @@ +git-credential-cache(1) +======================= + +NAME +---- +git-credential-cache - helper to temporarily store passwords in memory + +SYNOPSIS +-------- +----------------------------- +git config credential.helper 'cache [options]' +----------------------------- + +DESCRIPTION +----------- + +This command caches credentials in memory for use by future git +programs. The stored credentials never touch the disk, and are forgotten +after a configurable timeout. The cache is accessible over a Unix +domain socket, restricted to the current user by filesystem permissions. + +You probably don't want to invoke this command directly; it is meant to +be used as a credential helper by other parts of git. See +linkgit:gitcredentials[7] or `EXAMPLES` below. + +OPTIONS +------- + +--timeout <seconds>:: + + Number of seconds to cache credentials (default: 900). + +--socket <path>:: + + Use `<path>` to contact a running cache daemon (or start a new + cache daemon if one is not started). Defaults to + `~/.git-credential-cache/socket`. If your home directory is on a + network-mounted filesystem, you may need to change this to a + local filesystem. + +CONTROLLING THE DAEMON +---------------------- + +If you would like the daemon to exit early, forgetting all cached +credentials before their timeout, you can issue an `exit` action: + +-------------------------------------- +git credential-cache exit +-------------------------------------- + +EXAMPLES +-------- + +The point of this helper is to reduce the number of times you must type +your username or password. For example: + +------------------------------------ +$ git config credential.helper cache +$ git push http://example.com/repo.git +Username: <type your username> +Password: <type your password> + +[work for 5 more minutes] +$ git push http://example.com/repo.git +[your credentials are used automatically] +------------------------------------ + +You can provide options via the credential.helper configuration +variable (this example drops the cache time to 5 minutes): + +------------------------------------------------------- +$ git config credential.helper 'cache --timeout=300' +------------------------------------------------------- + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt new file mode 100644 index 0000000..3109346 --- /dev/null +++ b/Documentation/git-credential-store.txt @@ -0,0 +1,75 @@ +git-credential-store(1) +======================= + +NAME +---- +git-credential-store - helper to store credentials on disk + +SYNOPSIS +-------- +------------------- +git config credential.helper 'store [options]' +------------------- + +DESCRIPTION +----------- + +NOTE: Using this helper will store your passwords unencrypted on disk, +protected only by filesystem permissions. If this is not an acceptable +security tradeoff, try linkgit:git-credential-cache[1], or find a helper +that integrates with secure storage provided by your operating system. + +This command stores credentials indefinitely on disk for use by future +git programs. + +You probably don't want to invoke this command directly; it is meant to +be used as a credential helper by other parts of git. See +linkgit:gitcredentials[7] or `EXAMPLES` below. + +OPTIONS +------- + +--store=<path>:: + + Use `<path>` to store credentials. The file will have its + filesystem permissions set to prevent other users on the system + from reading it, but will not be encrypted or otherwise + protected. Defaults to `~/.git-credentials`. + +EXAMPLES +-------- + +The point of this helper is to reduce the number of times you must type +your username or password. For example: + +------------------------------------------ +$ git config credential.helper store +$ git push http://example.com/repo.git +Username: <type your username> +Password: <type your password> + +[several days later] +$ git push http://example.com/repo.git +[your credentials are used automatically] +------------------------------------------ + +STORAGE FORMAT +-------------- + +The `.git-credentials` file is stored in plaintext. Each credential is +stored on its own line as a URL like: + +------------------------------ +https://user:pass@example.com +------------------------------ + +When git needs authentication for a particular URL context, +credential-store will consider that context a pattern to match against +each entry in the credentials file. If the protocol, hostname, and +username (if we already have one) match, then the password is returned +to git. See the discussion of configuration in linkgit:gitcredentials[7] +for more information. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 19d473c..fe38f66 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-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 32aff95..3a0f55e 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -53,6 +53,11 @@ OPTIONS CONFIGURATION ------------- +merge.branchdesc:: + In addition to branch names, populate the log message with + the branch description text associated with them. Defaults + to false. + merge.log:: In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 55b33d7..bbb25da 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -10,7 +10,8 @@ SYNOPSIS -------- [verse] 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] - [--[no-]full] [--strict] [--verbose] [--lost-found] [<object>*] + [--[no-]full] [--strict] [--verbose] [--lost-found] + [--[no-]dangling] [--[no-]progress] [<object>*] DESCRIPTION ----------- @@ -29,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. @@ -72,6 +78,14 @@ index file, all SHA1 references in .git/refs/*, and all reflogs (unless a blob, the contents are written into the file, rather than its object name. +--progress:: +--no-progress:: + Progress status is reported on the standard error stream by + default when it is attached to a terminal, unless + --no-progress or --verbose is specified. --progress forces + progress status even if the standard error stream is not + directed to a terminal. + DISCUSSION ---------- diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 15d6711..6a8b1e3 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -79,6 +79,9 @@ OPTIONS --max-depth <depth>:: For each <pathspec> given on command line, descend at most <depth> levels of directories. A negative value means no limit. + This option is ignored if <pathspec> contains active wildcards. + In other words if "a*" matches a directory named "a*", + "*" is matched literally so --max-depth is still effective. -w:: --word-regexp:: diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 51dc325..97e7a8e 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -25,13 +25,24 @@ command directly. See linkgit:git-am[1] instead. OPTIONS ------- -k:: - Usually the program 'cleans up' the Subject: header line - to extract the title line for the commit log message, - among which (1) remove 'Re:' or 're:', (2) leading - whitespaces, (3) '[' up to ']', typically '[PATCH]', and - then prepends "[PATCH] ". This flag forbids this - munging, and is most useful when used to read back - 'git format-patch -k' output. + Usually the program removes email cruft from the Subject: + header line to extract the title line for the commit log + message. This option prevents this munging, and is most + useful when used to read back 'git format-patch -k' output. ++ +Specifically, the following are removed until none of them remain: ++ +-- +* Leading and trailing whitespace. + +* Leading `Re:`, `re:`, and `:`. + +* Leading bracketed strings (between `[` and `]`, usually + `[PATCH]`). +-- ++ +Finally, runs of whitespace are normalized to a single ASCII space +character. -b:: When -k is not in effect, all leading strings bracketed with '[' diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e2e6aba..3ceefb8 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 new file mode 100644 index 0000000..b7c7929 --- /dev/null +++ b/Documentation/git-p4.txt @@ -0,0 +1,507 @@ +git-p4(1) +========= + +NAME +---- +git-p4 - Import from and submit to Perforce repositories + + +SYNOPSIS +-------- +[verse] +'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... +'git p4 sync' [<sync options>] [<p4 depot path>...] +'git p4 rebase' +'git p4 submit' [<submit options>] [<master branch name>] + + +DESCRIPTION +----------- +This command provides a way to interact with p4 repositories +using git. + +Create a new git repository from an existing p4 repository using +'git p4 clone', giving it one or more p4 depot paths. Incorporate +new commits from p4 changes with 'git p4 sync'. The 'sync' command +is also used to include new branches from other p4 depot paths. +Submit git changes back to p4 using 'git p4 submit'. The command +'git p4 rebase' does a sync plus rebases the current branch onto +the updated p4 remote branch. + + +EXAMPLE +------- +* Create an alias for 'git p4', using the full path to the 'git-p4' + script if needed: ++ +------------ +$ git config --global alias.p4 '!git-p4' +------------ + +* Clone a repository: ++ +------------ +$ git p4 clone //depot/path/project +------------ + +* Do some work in the newly created git repository: ++ +------------ +$ cd project +$ vi foo.h +$ git commit -a -m "edited foo.h" +------------ + +* Update the git repository with recent changes from p4, rebasing your + work on top: ++ +------------ +$ git p4 rebase +------------ + +* Submit your commits back to p4: ++ +------------ +$ git p4 submit +------------ + + +COMMANDS +-------- + +Clone +~~~~~ +Generally, 'git p4 clone' is used to create a new git directory +from an existing p4 repository: +------------ +$ git p4 clone //depot/path/project +------------ +This: + +1. Creates an empty git repository in a subdirectory called 'project'. ++ +2. Imports the full contents of the head revision from the given p4 +depot path into a single commit in the git branch 'refs/remotes/p4/master'. ++ +3. Creates a local branch, 'master' from this remote and checks it out. + +To reproduce the entire p4 history in git, use the '@all' modifier on +the depot path: +------------ +$ git p4 clone //depot/path/project@all +------------ + + +Sync +~~~~ +As development continues in the p4 repository, those changes can +be included in the git repository using: +------------ +$ git p4 sync +------------ +This command finds new changes in p4 and imports them as git commits. + +P4 repositories can be added to an existing git repository using +'git p4 sync' too: +------------ +$ mkdir repo-git +$ cd repo-git +$ git init +$ git p4 sync //path/in/your/perforce/depot +------------ +This imports the specified depot into +'refs/remotes/p4/master' in an existing git repository. The +'--branch' option can be used to specify a different branch to +be used for the p4 content. + +If a git repository includes branches 'refs/remotes/origin/p4', these +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. + + +Rebase +~~~~~~ +A common working pattern is to fetch the latest changes from the p4 depot +and merge them with local uncommitted changes. Often, the p4 repository +is the ultimate location for all code, thus a rebase workflow makes +sense. This command does 'git p4 sync' followed by 'git rebase' to move +local commits on top of updated p4 changes. +------------ +$ git p4 rebase +------------ + + +Submit +~~~~~~ +Submitting changes from a git repository back to the p4 repository +requires a separate p4 client workspace. This should be specified +using the 'P4CLIENT' environment variable or the git configuration +variable 'git-p4.client'. The p4 client must exist, but the client root +will be created and populated if it does not already exist. + +To submit all changes that are in the current git branch but not in +the 'p4/master' branch, use: +------------ +$ git p4 submit +------------ + +To specify a branch other than the current one, use: +------------ +$ git p4 submit topicbranch +------------ + +The upstream reference is generally 'refs/remotes/p4/master', but can +be overridden using the '--origin=' command-line option. + +The p4 changes will be created as the user invoking 'git p4 submit'. The +'--preserve-user' option will cause ownership to be modified +according to the author of the git commit. This option requires admin +privileges in p4, which can be granted using 'p4 protect'. + + +OPTIONS +------- + +General options +~~~~~~~~~~~~~~~ +All commands except clone accept this option. + +--git-dir <dir>:: + Set the 'GIT_DIR' environment variable. See linkgit:git[1]. + +Sync options +~~~~~~~~~~~~ +These options can be used in the initial 'clone' as well as in +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. ++ +This example imports a new remote "p4/proj2" into an existing +git repository: +---- + $ git init + $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 +---- + +--detect-branches:: + Use the branch detection algorithm to find new paths in p4. It is + documented below in "BRANCH DETECTION". + +--changesfile <file>:: + Import exactly the p4 change numbers listed in 'file', one per + line. Normally, 'git p4' inspects the current p4 repository + state and detects the changes it should import. + +--silent:: + Do not print any progress information. + +--verbose:: + Provide more progress information. + +--detect-labels:: + Query p4 for labels associated with the depot paths, and add + them as tags in git. + +--import-local:: + By default, p4 branches are stored in 'refs/remotes/p4/', + where they will be treated as remote-tracking branches by + linkgit:git-branch[1] and other commands. This option instead + puts p4 branches in 'refs/heads/p4/'. Note that future + sync operations must specify '--import-local' as well so that + they can find the p4 branches in refs/heads. + +--max-changes <n>:: + Limit the number of imported changes to 'n'. Useful to + limit the amount of history when using the '@all' p4 revision + specifier. + +--keep-path:: + The mapping of file names from the p4 depot path to git, by + default, involves removing the entire depot path. With this + option, the full p4 depot path is retained in git. For example, + path '//depot/main/foo/bar.c', when imported from + '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the + git path is instead 'depot/main/foo/bar.c'. + +--use-client-spec:: + Use a client spec to find the list of interesting files in p4. + See the "CLIENT SPEC" section below. + +Clone options +~~~~~~~~~~~~~ +These options can be used in an initial 'clone', along with the 'sync' +options described above. + +--destination <directory>:: + Where to create the git repository. If not provided, the last + component in the p4 depot path is used to create a new + directory. + +--bare:: + Perform a bare clone. See linkgit:git-clone[1]. + +-/ <path>:: + Exclude selected depot paths when cloning. + +Submit options +~~~~~~~~~~~~~~ +These options can be used to modify 'git p4 submit' behavior. + +--verbose:: + Provide more progress information. + +--origin <commit>:: + Upstream location from which commits are identified to submit to + p4. By default, this is the most recent p4 commit reachable + from 'HEAD'. + +-M[<n>]:: + Detect renames. See linkgit:git-diff[1]. Renames will be + represented in p4 using explicit 'move' operations. There + is no corresponding option to detect copies, but there are + variables for both moves and copies. + +--preserve-user:: + Re-author p4 changes before submitting to p4. This option + requires p4 admin privileges. + + +DEPOT PATH SYNTAX +----------------- +The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can +be one or more space-separated p4 depot paths, with an optional +p4 revision specifier on the end: + +"//depot/my/project":: + Import one commit with all files in the '#head' change under that tree. + +"//depot/my/project@all":: + Import one commit for each change in the history of that depot path. + +"//depot/my/project@1,6":: + Import only changes 1 through 6. + +"//depot/proj1@all //depot/proj2@all":: + Import all changes from both named depot paths into a single + repository. Only files below these directories are included. + There is not a subdirectory in git for each "proj1" and "proj2". + You must use the '--destination' option when specifying more + than one depot path. The revision specifier must be specified + identically on each depot path. If there are files in the + depot paths with the same name, the path with the most recently + updated version of the file is the one that appears in git. + +See 'p4 help revisions' for the full syntax of p4 revision specifiers. + + +CLIENT SPEC +----------- +The p4 client specification is maintained with the 'p4 client' command +and contains among other fields, a View that specifies how the depot +is mapped into the client repository. The 'clone' and 'sync' commands +can consult the client spec when given the '--use-client-spec' option or +when the useClientSpec variable is true. After 'git p4 clone', the +useClientSpec variable is automatically set in the repository +configuration file. This allows future 'git p4 submit' commands to +work properly; the submit command looks only at the variable and does +not have a command-line option. + +The full syntax for a p4 view is documented in 'p4 help views'. Git-p4 +knows only a subset of the view syntax. It understands multi-line +mappings, overlays with '+', exclusions with '-' and double-quotes +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 +variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. + + +BRANCH DETECTION +---------------- +P4 does not have the same concept of a branch as git. Instead, +p4 organizes its content as a directory tree, where by convention +different logical branches are in different locations in the tree. +The 'p4 branch' command is used to maintain mappings between +different areas in the tree, and indicate related content. 'git p4' +can use these mappings to determine branch relationships. + +If you have a repository where all the branches of interest exist as +subdirectories of a single depot path, you can use '--detect-branches' +when cloning or syncing to have 'git p4' automatically find +subdirectories in p4, and to generate these as branches in git. + +For example, if the P4 repository structure is: +---- +//depot/main/... +//depot/branch1/... +---- + +And "p4 branch -o branch1" shows a View line that looks like: +---- +//depot/main/... //depot/branch1/... +---- + +Then this 'git p4 clone' command: +---- +git p4 clone --detect-branches //depot@all +---- +produces a separate branch in 'refs/remotes/p4/' for //depot/main, +called 'master', and one for //depot/branch1 called 'depot/branch1'. + +However, it is not necessary to create branches in p4 to be able to use +them like branches. Because it is difficult to infer branch +relationships automatically, a git configuration setting +'git-p4.branchList' can be used to explicitly identify branch +relationships. It is a list of "source:destination" pairs, like a +simple p4 branch specification, where the "source" and "destination" are +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 config git-p4.branchList main:branch1 +git p4 clone --detect-branches //depot@all +---- + + +PERFORMANCE +----------- +The fast-import mechanism used by 'git p4' creates one pack file for +each invocation of 'git p4 sync'. Normally, git garbage compression +(linkgit:git-gc[1]) automatically compresses these to fewer pack files, +but explicit invocation of 'git repack -adf' may improve performance. + + +CONFIGURATION VARIABLES +----------------------- +The following config settings can be used to modify 'git p4' behavior. +They all are in the 'git-p4' section. + +General variables +~~~~~~~~~~~~~~~~~ +git-p4.user:: + User specified as an option to all p4 commands, with '-u <user>'. + The environment variable 'P4USER' can be used instead. + +git-p4.password:: + Password specified as an option to all p4 commands, with + '-P <password>'. + The environment variable 'P4PASS' can be used instead. + +git-p4.port:: + Port specified as an option to all p4 commands, with + '-p <port>'. + The environment variable 'P4PORT' can be used instead. + +git-p4.host:: + Host specified as an option to all p4 commands, with + '-h <host>'. + The environment variable 'P4HOST' can be used instead. + +git-p4.client:: + Client specified as an option to all p4 commands, with + '-c <client>', including the client spec. + +Clone and sync variables +~~~~~~~~~~~~~~~~~~~~~~~~ +git-p4.syncFromOrigin:: + Because importing commits from other git repositories is much faster + than importing them from p4, a mechanism exists to find p4 changes + first in git remotes. If branches exist under 'refs/remote/origin/p4', + those will be fetched and used when syncing from p4. This + variable can be set to 'false' to disable this behavior. + +git-p4.branchUser:: + One phase in branch detection involves looking at p4 branches + to find new ones to import. By default, all branches are + inspected. This option limits the search to just those owned + by the single user named in the variable. + +git-p4.branchList:: + List of branches to be imported when branch detection is + enabled. Each entry should be a pair of branch names separated + by a colon (:). This example declares that both branchA and + branchB were created from main: +------------- +git config git-p4.branchList main:branchA +git config --add git-p4.branchList main:branchB +------------- + +git-p4.useClientSpec:: + Specify that the p4 client spec should be used to identify p4 + depot paths of interest. This is equivalent to specifying the + option '--use-client-spec'. See the "CLIENT SPEC" section above. + This variable is a boolean, not the name of a p4 client. + +Submit variables +~~~~~~~~~~~~~~~~ +git-p4.detectRenames:: + Detect renames. See linkgit:git-diff[1]. + +git-p4.detectCopies:: + Detect copies. See linkgit:git-diff[1]. + +git-p4.detectCopiesHarder:: + Detect copies harder. See linkgit:git-diff[1]. + +git-p4.preserveUser:: + On submit, re-author changes to reflect the git author, + regardless of who invokes 'git p4 submit'. + +git-p4.allowMissingP4Users:: + When 'preserveUser' is true, 'git p4' normally dies if it + cannot find an author in the p4 user map. This setting + submits the change regardless. + +git-p4.skipSubmitEdit:: + The submit process invokes the editor before each p4 change + is submitted. If this setting is true, though, the editing + step is skipped. + +git-p4.skipSubmitEditCheck:: + After editing the p4 change message, 'git p4' makes sure that + the description really was changed by looking at the file + modification time. This option disables that test. + +git-p4.allowSubmit:: + By default, any branch can be used as the source for a 'git p4 + submit' operation. This configuration variable, if set, permits only + the named branches to be used as submit sources. Branch names + must be the short names (no "refs/heads/"), and should be + separated by commas (","), with no spaces. + +git-p4.skipUserNameCheck:: + If the user running 'git p4 submit' does not exist in the p4 + 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 +---------------------- +* Changesets from p4 are imported using git fast-import. +* Cloning or syncing does not require a p4 client; file contents are + collected using 'p4 print'. +* Submitting requires a p4 client, which is not in the same location + as the git repository. Patches are applied, one at a time, to + this p4 client and submitted from there. +* Each commit imported by 'git p4' has a line at the end of the log + message indicating the p4 depot location and change number. This + line is used by later 'git p4 sync' operations to know which p4 + changes are new. diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index e1da468..0f18ec8 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -108,7 +108,7 @@ include::merge-options.txt[] fetched, the rebase uses that information to avoid rebasing non-local changes. + -See `branch.<name>.rebase` and `branch.autosetuprebase` in +See `pull.rebase`, `branch.<name>.rebase` and `branch.autosetuprebase` in linkgit:git-config[1] if you want to make `git pull` always use `{litdd}rebase` instead of merging. + diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index aede488..48760db 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-read-tree.txt b/Documentation/git-read-tree.txt index a43e874..c4bde65 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -341,7 +341,7 @@ since you pulled from him: ---------------- $ git fetch git://.... linus -$ LT=`cat .git/FETCH_HEAD` +$ LT=`git rev-parse FETCH_HEAD` ---------------- Your work tree is still based on your HEAD ($JC), but you have diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 5a8c506..d376d19 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -14,7 +14,7 @@ SYNOPSIS 'git remote rename' <old> <new> 'git remote rm' <name> 'git remote set-head' <name> (-a | -d | <branch>) -'git remote set-branches' <name> [--add] <branch>... +'git remote set-branches' [--add] <name> <branch>... 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> 'git remote set-url --delete' [--push] <name> <url> diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 40af321..4c1aff6 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-rerere.txt b/Documentation/git-rerere.txt index a6253ba..b43b7c8 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- [verse] -'git rerere' ['clear'|'forget' <pathspec>|'diff'|'status'|'gc'] +'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc'] DESCRIPTION ----------- @@ -37,30 +37,35 @@ its working state. 'clear':: -This resets the metadata used by rerere if a merge resolution is to be +Reset the metadata used by rerere if a merge resolution is to be aborted. Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]' will automatically invoke this command. 'forget' <pathspec>:: -This resets the conflict resolutions which rerere has recorded for the current +Reset the conflict resolutions which rerere has recorded for the current conflict in <pathspec>. 'diff':: -This displays diffs for the current state of the resolution. It is +Display diffs for the current state of the resolution. It is useful for tracking what has changed while the user is resolving conflicts. Additional arguments are passed directly to the system 'diff' command installed in PATH. 'status':: -Like 'diff', but this only prints the filenames that will be tracked -for resolutions. +Print paths with conflicts whose merge resolution rerere will record. + +'remaining':: + +Print paths with conflicts that have not been autoresolved by rerere. +This includes paths whose resolutions cannot be tracked by rerere, +such as conflicting submodules. 'gc':: -This prunes records of conflicted merges that +Prune records of conflicted merges that occurred a long time ago. By default, unresolved conflicts older than 15 days and resolved conflicts older than 60 days are pruned. These defaults are controlled via the diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 327233c..3241170 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-show-ref.txt b/Documentation/git-show-ref.txt index 3c45895..fcee000 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -44,7 +44,7 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with "^{}" + Dereference tags into object IDs as well. They will be shown with "{caret}{}" appended. -s:: @@ -73,9 +73,9 @@ OPTIONS --exclude-existing[=<pattern>]:: Make 'git show-ref' act as a filter that reads refs from stdin of the - form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$" + form "`{caret}(?:<anything>\s)?<refname>(?:{backslash}{caret}{})?$`" and performs the following actions on each: - (1) strip "^{}" at the end of line if any; + (1) strip "{caret}{}" at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; (4) ignore if refname is a ref that exists in the local repository; diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index a45d4c4..981d3a8 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 c83cb13..8d32b9a 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 @@ -38,7 +39,9 @@ created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u <key-id>` is used. When `-u <key-id>` is not used, the committer identity for the current user is used to find the -GnuPG key for signing. +GnuPG key for signing. The configuration variable `gpg.program` +is used to specify custom GnuPG binary. + OPTIONS ------- @@ -48,11 +51,11 @@ OPTIONS -s:: --sign:: - Make a GPG-signed tag, using the default e-mail address's key + 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 + Make a GPG-signed tag, using the given key. -f:: --force:: @@ -84,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). @@ -99,6 +105,13 @@ OPTIONS Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. +--cleanup=<mode>:: + This option sets how the tag message is cleaned up. + The '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'. The + 'strip' mode is default. The 'verbatim' mode does not change message at + all, 'whitespace' removes just leading/trailing whitespace lines and + 'strip' removes both whitespace and commentary. + <tagname>:: The name of the tag to create, delete, or describe. The new tag name must pass all checks defined by diff --git a/Documentation/git.txt b/Documentation/git.txt index 614693a..d5b7667 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,11 +9,11 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] +'git' [--version] [--help] [-c <name>=<value>] + [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] - [-c <name>=<value>] - [--help] <command> [<args>] + <command> [<args>] DESCRIPTION ----------- @@ -44,6 +44,15 @@ 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.9.4/git.html[documentation for release 1.7.9.4] + +* release notes for + link:RelNotes/1.7.9.4.txt[1.7.9.4], + link:RelNotes/1.7.9.3.txt[1.7.9.3], + link:RelNotes/1.7.9.2.txt[1.7.9.2], + link:RelNotes/1.7.9.1.txt[1.7.9.1], + link:RelNotes/1.7.9.txt[1.7.9]. + * link:v1.7.8.4/git.html[documentation for release 1.7.8.4] * release notes for diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 25e46ae..80120ea 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: @@ -500,6 +521,8 @@ patterns are available: - `java` suitable for source code in the Java language. +- `matlab` suitable for source code in the MATLAB language. + - `objc` suitable for source code in the Objective-C language. - `pascal` suitable for source code in the Pascal/Delphi language. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index c27d086..fb0d569 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1004,7 +1004,7 @@ Updating from ae3a2da... to a80b4aa.... Fast-forward (no commit created; -m option ignored) example | 1 + hello | 1 + - 2 files changed, 2 insertions(+), 0 deletions(-) + 2 files changed, 2 insertions(+) ---------------- Because your branch did not contain anything more than what had diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt new file mode 100644 index 0000000..066f825 --- /dev/null +++ b/Documentation/gitcredentials.txt @@ -0,0 +1,183 @@ +gitcredentials(7) +================= + +NAME +---- +gitcredentials - providing usernames and passwords to git + +SYNOPSIS +-------- +------------------ +git config credential.https://example.com.username myusername +git config credential.helper "$helper $options" +------------------ + +DESCRIPTION +----------- + +Git will sometimes need credentials from the user in order to perform +operations; for example, it may need to ask for a username and password +in order to access a remote repository over HTTP. This manual describes +the mechanisms git uses to request these credentials, as well as some +features to avoid inputting these credentials repeatedly. + +REQUESTING CREDENTIALS +---------------------- + +Without any credential helpers defined, git will try the following +strategies to ask the user for usernames and passwords: + +1. If the `GIT_ASKPASS` environment variable is set, the program + specified by the variable is invoked. A suitable prompt is provided + to the program on the command line, and the user's input is read + from its standard output. + +2. Otherwise, if the `core.askpass` configuration variable is set, its + value is used as above. + +3. Otherwise, if the `SSH_ASKPASS` environment variable is set, its + value is used as above. + +4. Otherwise, the user is prompted on the terminal. + +AVOIDING REPETITION +------------------- + +It can be cumbersome to input the same credentials over and over. Git +provides two methods to reduce this annoyance: + +1. Static configuration of usernames for a given authentication context. + +2. Credential helpers to cache or store passwords, or to interact with + a system password wallet or keychain. + +The first is simple and appropriate if you do not have secure storage available +for a password. It is generally configured by adding this to your config: + +--------------------------------------- +[credential "https://example.com"] + username = me +--------------------------------------- + +Credential helpers, on the other hand, are external programs from which git can +request both usernames and passwords; they typically interface with secure +storage provided by the OS or other programs. + +To use a helper, you must first select one to use. Git currently +includes the following helpers: + +cache:: + + Cache credentials in memory for a short period of time. See + linkgit:git-credential-cache[1] for details. + +store:: + + Store credentials indefinitely on disk. See + linkgit:git-credential-store[1] for details. + +You may also have third-party helpers installed; search for +`credential-*` in the output of `git help -a`, and consult the +documentation of individual helpers. Once you have selected a helper, +you can tell git to use it by putting its name into the +credential.helper variable. + +1. Find a helper. ++ +------------------------------------------- +$ git help -a | grep credential- +credential-foo +------------------------------------------- + +2. Read its description. ++ +------------------------------------------- +$ git help credential-foo +------------------------------------------- + +3. Tell git to use it. ++ +------------------------------------------- +$ git config --global credential.helper foo +------------------------------------------- + +If there are multiple instances of the `credential.helper` configuration +variable, each helper will be tried in turn, and may provide a username, +password, or nothing. Once git has acquired both a username and a +password, no more helpers will be tried. + + +CREDENTIAL CONTEXTS +------------------- + +Git considers each credential to have a context defined by a URL. This context +is used to look up context-specific configuration, and is passed to any +helpers, which may use it as an index into secure storage. + +For instance, imagine we are accessing `https://example.com/foo.git`. When git +looks into a config file to see if a section matches this context, it will +consider the two a match if the context is a more-specific subset of the +pattern in the config file. For example, if you have this in your config file: + +-------------------------------------- +[credential "https://example.com"] + username = foo +-------------------------------------- + +then we will match: both protocols are the same, both hosts are the same, and +the "pattern" URL does not care about the path component at all. However, this +context would not match: + +-------------------------------------- +[credential "https://kernel.org"] + username = foo +-------------------------------------- + +because the hostnames differ. Nor would it match `foo.example.com`; git +compares hostnames exactly, without considering whether two hosts are part of +the same domain. Likewise, a config entry for `http://example.com` would not +match: git compares the protocols exactly. + + +CONFIGURATION OPTIONS +--------------------- + +Options for a credential context can be configured either in +`credential.\*` (which applies to all credentials), or +`credential.<url>.\*`, where <url> matches the context as described +above. + +The following options are available in either location: + +helper:: + + The name of an external credential helper, and any associated options. + If the helper name is not an absolute path, then the string `git + credential-` is prepended. The resulting string is executed by the + shell (so, for example, setting this to `foo --option=bar` will execute + `git credential-foo --option=bar` via the shell. See the manual of + specific helpers for examples of their use. + +username:: + + A default username, if one is not provided in the URL. + +useHttpPath:: + + By default, git does not consider the "path" component of an http URL + to be worth matching via external helpers. This means that a credential + stored for `https://example.com/foo.git` will also be used for + `https://example.com/bar.git`. If you do want to distinguish these + cases, set this option to `true`. + + +CUSTOM HELPERS +-------------- + +You can write your own custom helpers to interface with any system in +which you keep credentials. See the documentation for git's +link:technical/api-credentials.html[credentials API] for details. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index f1e4422..e00a4d2 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -34,12 +34,12 @@ $ echo 'hello world' > file.txt $ git add . $ git commit -a -m "initial commit" [master (root-commit) 54196cc] initial commit - 1 files changed, 1 insertions(+), 0 deletions(-) + 1 file changed, 1 insertion(+) create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" [master c4d59f3] add emphasis - 1 files changed, 1 insertions(+), 1 deletions(-) + 1 file changed, 1 insertion(+), 1 deletion(-) ------------------------------------------------ What are the 7 digits of hex that git responded to the commit with? diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt new file mode 100644 index 0000000..98c0033 --- /dev/null +++ b/Documentation/howto/using-signed-tag-in-pull-request.txt @@ -0,0 +1,217 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Tue, 17 Jan 2011 13:00:00 -0800 +Subject: Using signed tag in pull requests +Abstract: Beginning v1.7.9, a contributor can push a signed tag to her + publishing repository and ask her integrator to pull it. This assures the + integrator that the pulled history is authentic and allows others to + later validate it. +Content-type: text/asciidoc + +Using signed tag in pull requests +================================= + +A typical distributed workflow using Git is for a contributor to fork a +project, build on it, publish the result to her public repository, and ask +the "upstream" person (often the owner of the project where she forked +from) to pull from her public repository. Requesting such a "pull" is made +easy by the `git request-pull` command. + +Earlier, a typical pull request may have started like this: + +------------ + The following changes since commit 406da78032179...: + + Froboz 3.2 (2011-09-30 14:20:57 -0700) + + are available in the git repository at: + + example.com:/git/froboz.git for-xyzzy +------------ + +followed by a shortlog of the changes and a diffstat. + +The request was for a branch name (e.g. `for-xyzzy`) in the public +repository of the contributor, and even though it stated where the +contributor forked her work from, the message did not say anything about +the commit to expect at the tip of the for-xyzzy branch. If the site that +hosts the public repository of the contributor cannot be fully trusted, it +was unnecessarily hard to make sure what was pulled by the integrator was +genuinely what the contributor had produced for the project. Also there +was no easy way for third-party auditors to later verify the resulting +history. + +Starting from Git release v1.7.9, a contributor can add a signed tag to +the commit at the tip of the history and ask the integrator to pull that +signed tag. When the integrator runs `git pull`, the signed tag is +automatically verified to assure that the history is not tampered with. +In addition, the resulting merge commit records the content of the signed +tag, so that other people can verify that the branch merged by the +integrator was signed by the contributor, without fetching the signed tag +used to validate the pull request separately and keeping it in the refs +namespace. + +This document describes the workflow between the contributor and the +integrator, using Git v1.7.9 or later. + + +A contributor or a lieutenant +----------------------------- + +After preparing her work to be pulled, the contributor uses `git tag -s` +to create a signed tag: + +------------ + $ git checkout work + $ ... "git pull" from sublieutenants, "git commit" your own work ... + $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work +------------ + +Note that this example uses the `-m` option to create a signed tag with +just a one-liner message, but this is for illustration purposes only. It +is advisable to compose a well-written explanation of what the topic does +to justify why it is worthwhile for the integrator to pull it, as this +message will eventually become part of the final history after the +integrator responds to the pull request (as we will see later). + +Then she pushes the tag out to her public repository: + +------------ + $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy +------------ + +There is no need to push the `work` branch or anything else. + +Note that the above command line used a plus sign at the beginning of +`+frotz-for-xyzzy` to allow forcing the update of a tag, as the same +contributor may want to reuse a signed tag with the same name after the +previous pull request has already been responded to. + +The contributor then prepares a message to request a "pull": + +------------ + $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt +------------ + +The arguments are: + +. the version of the integrator's commit the contributor based her work on; +. the URL of the repository, to which the contributor has pushed what she + wants to get pulled; and +. the name of the tag the contributor wants to get pulled (earlier, she could + write only a branch name here). + +The resulting msg.txt file begins like so: + +------------ + The following changes since commit 406da78032179...: + + Froboz 3.2 (2011-09-30 14:20:57 -0700) + + are available in the git repository at: + + example.com:/git/froboz.git tags/frotz-for-xyzzy + + for you to fetch changes up to 703f05ad5835c...: + + Add tests and documentation for frotz (2011-12-02 10:02:52 -0800) + + ----------------------------------------------- + Completed frotz feature + ----------------------------------------------- +------------ + +followed by a shortlog of the changes and a diffstat. Comparing this with +the earlier illustration of the output from the traditional `git request-pull` +command, the reader should notice that: + +. The tip commit to expect is shown to the integrator; and +. The signed tag message is shown prominently between the dashed lines + before the shortlog. + +The latter is why the contributor would want to justify why pulling her +work is worthwhile when creating the signed tag. The contributor then +opens her favorite MUA, reads msg.txt, edits and sends it to her upstream +integrator. + + +Integrator +---------- + +After receiving such a pull request message, the integrator fetches and +integrates the tag named in the request, with: + +------------ + $ git pull example.com:/git/froboz.git/ tags/frotz-for-xyzzy +------------ + +This operation will always open an editor to allow the integrator to fine +tune the commit log message when merging a signed tag. Also, pulling a +signed tag will always create a merge commit even when the integrator does +not have any new commit since the contributor's work forked (i.e. 'fast +forward'), so that the integrator can properly explain what the merge is +about and why it was made. + +In the editor, the integrator will see something like this: + +------------ + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ + + Completed frotz feature + # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB + # gpg: Good signature from "Con Tributor <nitfol@example.com>" +------------ + +Notice that the message recorded in the signed tag "Completed frotz +feature" appears here, and again that is why it is important for the +contributor to explain her work well when creating the signed tag. + +As usual, the lines commented with `#` are stripped out. The resulting +commit records the signed tag used for this validation in a hidden field +so that it can later be used by others to audit the history. There is no +need for the integrator to keep a separate copy of the tag in his +repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the +above example), and there is no need to publish the tag to his public +repository, either. + +After the integrator responds to the pull request and her work becomes +part of the permanent history, the contributor can remove the tag from +her public repository, if she chooses, in order to keep the tag namespace +of her public repository clean, with: + +------------ + $ git push example.com:/git/froboz.git :frotz-for-xyzzy +------------ + + +Auditors +-------- + +The `--show-signature` option can be given to `git log` or `git show` and +shows the verification status of the embedded signed tag in merge commits +created when the integrator responded to a pull request of a signed tag. + +A typical output from `git show --show-signature` may look like this: + +------------ + $ git show --show-signature + commit 02306ef6a3498a39118aef9df7975bdb50091585 + merged tag 'frotz-for-xyzzy' + gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB + gpg: Good signature from "Con Tributor <nitfol@example.com>" + Merge: 406da78 703f05a + Author: Inte Grator <xyzzy@example.com> + Date: Tue Jan 17 13:49:41 2012 -0800 + + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/ + + Completed frotz feature + + * tag 'frotz-for-xyzzy' (100 commits) + Add tests and documentation for frotz + ... +------------ + +There is no need for the auditor to explicitly fetch the contributor's +signature, or to even be aware of what tag(s) the contributor and integrator +used to communicate the signature. All the required information is recorded +as part of the merge commit. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 1a5c12e..0bcbe0a 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -8,18 +8,34 @@ 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 + pointer, without creating a merge commit. This is the default + behavior. + --no-ff:: - Do not generate a merge commit if the merge resolved as - a fast-forward, only update the branch pointer. This is - the default behavior of git-merge. -+ -With --no-ff Generate a merge commit even if the merge -resolved as a fast-forward. + Create a merge commit even when the merge resolves as a + fast-forward. + +--ff-only:: + Refuse to merge and exit with a non-zero status unless the + current `HEAD` is already up-to-date or the merge can be + resolved as a fast-forward. --log[=<n>]:: --no-log:: @@ -54,11 +70,6 @@ merge. With --no-squash perform the merge and commit the result. This option can be used to override --squash. ---ff-only:: - Refuse to merge and exit with a non-zero status unless the - current `HEAD` is already up-to-date or the merge can be - resolved as a fast-forward. - -s <strategy>:: --strategy=<strategy>:: Use the given merge strategy; can be supplied more than diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 561cc9f..880b6f2 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -132,6 +132,10 @@ The placeholders are: - '%N': commit notes - '%gD': reflog selector, e.g., `refs/stash@\{1\}` - '%gd': shortened reflog selector, e.g., `stash@\{1\}` +- '%gn': reflog identity name +- '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) +- '%ge': reflog identity email +- '%gE': reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) - '%gs': reflog subject - '%Cred': switch color to red - '%Cgreen': switch color to green diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 39e6207..6a4b635 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -117,27 +117,27 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). Pretend as if all the refs in `refs/heads` are listed on the command line as '<commit>'. If '<pattern>' is given, limit branches to ones matching given shell glob. If pattern lacks '?', - '*', or '[', '/*' at the end is implied. + '{asterisk}', or '[', '/{asterisk}' at the end is implied. --tags[=<pattern>]:: Pretend as if all the refs in `refs/tags` are listed on the command line as '<commit>'. If '<pattern>' is given, limit - tags to ones matching given shell glob. If pattern lacks '?', '*', - or '[', '/*' at the end is implied. + tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', + or '[', '/{asterisk}' at the end is implied. --remotes[=<pattern>]:: Pretend as if all the refs in `refs/remotes` are listed on the command line as '<commit>'. If '<pattern>' is given, limit remote-tracking branches to ones matching given shell glob. - If pattern lacks '?', '*', or '[', '/*' at the end is implied. + If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. --glob=<glob-pattern>:: Pretend as if all the refs matching shell glob '<glob-pattern>' are listed on the command line as '<commit>'. Leading 'refs/', - is automatically prepended if missing. If pattern lacks '?', '*', - or '[', '/*' at the end is implied. + is automatically prepended if missing. If pattern lacks '?', '{asterisk}', + or '[', '/{asterisk}' at the end is implied. --ignore-missing:: diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index b290b61..1725661 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -101,7 +101,7 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. '<rev>{tilde}<n>', e.g. 'master{tilde}3':: A suffix '{tilde}<n>' to a revision parameter means the commit - object that is the <n>th generation grand-parent of the named + object that is the <n>th generation ancestor of the named commit object, following only the first parents. I.e. '<rev>{tilde}3' is equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to '<rev>{caret}1{caret}1{caret}1'. See below for an illustration of diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt new file mode 100644 index 0000000..edf8dfb --- /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-credentials.txt b/Documentation/technical/api-credentials.txt new file mode 100644 index 0000000..21ca6a2 --- /dev/null +++ b/Documentation/technical/api-credentials.txt @@ -0,0 +1,245 @@ +credentials API +=============== + +The credentials API provides an abstracted way of gathering username and +password credentials from the user (even though credentials in the wider +world can take many forms, in this document the word "credential" always +refers to a username and password pair). + +Data Structures +--------------- + +`struct credential`:: + + This struct represents a single username/password combination + along with any associated context. All string fields should be + heap-allocated (or NULL if they are not known or not applicable). + The meaning of the individual context fields is the same as + their counterparts in the helper protocol; see the section below + for a description of each field. ++ +The `helpers` member of the struct is a `string_list` of helpers. Each +string specifies an external helper which will be run, in order, to +either acquire or store credentials. See the section on credential +helpers below. ++ +This struct should always be initialized with `CREDENTIAL_INIT` or +`credential_init`. + + +Functions +--------- + +`credential_init`:: + + Initialize a credential structure, setting all fields to empty. + +`credential_clear`:: + + Free any resources associated with the credential structure, + returning it to a pristine initialized state. + +`credential_fill`:: + + Instruct the credential subsystem to fill the username and + password fields of the passed credential struct by first + consulting helpers, then asking the user. After this function + returns, the username and password fields of the credential are + guaranteed to be non-NULL. If an error occurs, the function will + die(). + +`credential_reject`:: + + Inform the credential subsystem that the provided credentials + have been rejected. This will cause the credential subsystem to + notify any helpers of the rejection (which allows them, for + example, to purge the invalid credentials from storage). It + will also free() the username and password fields of the + credential and set them to NULL (readying the credential for + another call to `credential_fill`). Any errors from helpers are + ignored. + +`credential_approve`:: + + Inform the credential subsystem that the provided credentials + were successfully used for authentication. This will cause the + credential subsystem to notify any helpers of the approval, so + that they may store the result to be used again. Any errors + from helpers are ignored. + +`credential_from_url`:: + + Parse a URL into broken-down credential fields. + +Example +------- + +The example below shows how the functions of the credential API could be +used to login to a fictitious "foo" service on a remote host: + +----------------------------------------------------------------------- +int foo_login(struct foo_connection *f) +{ + int status; + /* + * Create a credential with some context; we don't yet know the + * username or password. + */ + + struct credential c = CREDENTIAL_INIT; + c.protocol = xstrdup("foo"); + c.host = xstrdup(f->hostname); + + /* + * Fill in the username and password fields by contacting + * helpers and/or asking the user. The function will die if it + * fails. + */ + credential_fill(&c); + + /* + * Otherwise, we have a username and password. Try to use it. + */ + status = send_foo_login(f, c.username, c.password); + switch (status) { + case FOO_OK: + /* It worked. Store the credential for later use. */ + credential_accept(&c); + break; + case FOO_BAD_LOGIN: + /* Erase the credential from storage so we don't try it + * again. */ + credential_reject(&c); + break; + default: + /* + * Some other error occured. We don't know if the + * credential is good or bad, so report nothing to the + * credential subsystem. + */ + } + + /* Free any associated resources. */ + credential_clear(&c); + + return status; +} +----------------------------------------------------------------------- + + +Credential Helpers +------------------ + +Credential helpers are programs executed by git to fetch or save +credentials from and to long-term storage (where "long-term" is simply +longer than a single git process; e.g., credentials may be stored +in-memory for a few minutes, or indefinitely on disk). + +Each helper is specified by a single string. The string is transformed +by git into a command to be executed using these rules: + + 1. If the helper string begins with "!", it is considered a shell + snippet, and everything after the "!" becomes the command. + + 2. Otherwise, if the helper string begins with an absolute path, the + verbatim helper string becomes the command. + + 3. Otherwise, the string "git credential-" is prepended to the helper + string, and the result becomes the command. + +The resulting command then has an "operation" argument appended to it +(see below for details), and the result is executed by the shell. + +Here are some example specifications: + +---------------------------------------------------- +# run "git credential-foo" +foo + +# same as above, but pass an argument to the helper +foo --bar=baz + +# the arguments are parsed by the shell, so use shell +# quoting if necessary +foo --bar="whitespace arg" + +# you can also use an absolute path, which will not use the git wrapper +/path/to/my/helper --with-arguments + +# or you can specify your own shell snippet +!f() { echo "password=`cat $HOME/.secret`"; }; f +---------------------------------------------------- + +Generally speaking, rule (3) above is the simplest for users to specify. +Authors of credential helpers should make an effort to assist their +users by naming their program "git-credential-$NAME", and putting it in +the $PATH or $GIT_EXEC_PATH during installation, which will allow a user +to enable it with `git config credential.helper $NAME`. + +When a helper is executed, it will have one "operation" argument +appended to its command line, which is one of: + +`get`:: + + Return a matching credential, if any exists. + +`store`:: + + Store the credential, if applicable to the helper. + +`erase`:: + + Remove a matching credential, if any, from the helper's storage. + +The details of the credential will be provided on the helper's stdin +stream. The credential is split into a set of named attributes. +Attributes are provided to the helper, one per line. Each attribute is +specified by a key-value pair, separated by an `=` (equals) sign, +followed by a newline. The key may contain any bytes except `=`, +newline, or NUL. The value may contain any bytes except newline or NUL. +In both cases, all bytes are treated as-is (i.e., there is no quoting, +and one cannot transmit a value with newline or NUL in it). The list of +attributes is terminated by a blank line or end-of-file. + +Git will send the following attributes (but may not send all of +them for a given credential; for example, a `host` attribute makes no +sense when dealing with a non-network protocol): + +`protocol`:: + + The protocol over which the credential will be used (e.g., + `https`). + +`host`:: + + The remote hostname for a network credential. + +`path`:: + + The path with which the credential will be used. E.g., for + accessing a remote https repository, this will be the + repository's path on the server. + +`username`:: + + The credential's username, if we already have one (e.g., from a + URL, from the user, or from a previously run helper). + +`password`:: + + The credential's password, if we are asking it to be stored. + +For a `get` operation, the helper should produce a list of attributes +on stdout in the same format. A helper is free to produce a subset, or +even no values at all if it has nothing useful to provide. Any provided +attributes will overwrite those already known about by git. + +For a `store` or `erase` operation, the helper's output is ignored. +If it fails to perform the requested operation, it may complain to +stderr to inform the user. If it does not support the requested +operation (e.g., a read-only store), it should silently ignore the +request. + +If a helper receives any other operation, it should silently ignore the +request. This leaves room for future operations to be added (older +helpers will just ignore the new requests). diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 4b92514..2527b7e 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/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index afe2759..95a8bf3 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -255,8 +255,24 @@ same behaviour as well. `strbuf_getline`:: - Read a line from a FILE* pointer. The second argument specifies the line + Read a line from a FILE *, overwriting the existing contents + of the strbuf. The second argument specifies the line terminator character, typically `'\n'`. + Reading stops after the terminator or at EOF. The terminator + is removed from the buffer before returning. Returns 0 unless + there was nothing left before EOF, in which case it returns `EOF`. + +`strbuf_getwholeline`:: + + Like `strbuf_getline`, but keeps the trailing terminator (if + any) in the buffer. + +`strbuf_getwholeline_fd`:: + + Like `strbuf_getwholeline`, but operates on a file descriptor. + It reads one character at a time, so it is very slow. Do not + use it unless you need the correct position in the file + descriptor. `stripspace`:: diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index f13a846..6c7fee7 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 |