From: Junio C Hamano Date: Mon, 22 Apr 2013 01:40:15 +0000 (-0700) Subject: Merge branch 'ta/glossary' X-Git-Tag: v1.8.3-rc0~35 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/ad77690fe400d91d3da97e16c07f1a8591b19b99?hp=-c Merge branch 'ta/glossary' * ta/glossary: glossary: improve definitions of refspec and pathspec The name of the hash function is "SHA-1", not "SHA1" glossary: improve description of SHA-1 related topics glossary: remove outdated/misleading/irrelevant entries --- ad77690fe400d91d3da97e16c07f1a8591b19b99 diff --combined Documentation/config.txt index 29559c88af,323827962c..c67038b56d --- a/Documentation/config.txt +++ b/Documentation/config.txt @@@ -412,7 -412,7 +412,7 @@@ repository's usual working tree) core.logAllRefUpdates:: Enable the reflog. Updates to a ref is logged to the file "$GIT_DIR/logs/", by appending the new and old - SHA1, the date/time and the reason of the update, but + SHA-1, the date/time and the reason of the update, but only when the file exists. If this configuration variable is set to true, missing "$GIT_DIR/logs/" file is automatically created for branch heads (i.e. under @@@ -727,22 -727,9 +727,22 @@@ branch.autosetuprebase: This option defaults to never. branch..remote:: - When in branch , it tells 'git fetch' and 'git push' which - remote to fetch from/push to. It defaults to `origin` if no remote is - configured. `origin` is also used if you are not on any branch. + When on branch , it tells 'git fetch' and 'git push' + which remote to fetch from/push to. The remote to push to + may be overridden with `remote.pushdefault` (for all branches). + The remote to push to, for the current branch, may be further + overridden by `branch..pushremote`. If no remote is + configured, or if you are not on any branch, it defaults to + `origin` for fetching and `remote.pushdefault` for pushing. + +branch..pushremote:: + When on branch , it overrides `branch..remote` for + pushing. It also overrides `remote.pushdefault` for pushing + from branch . When you pull from one place (e.g. your + upstream) and push to another place (e.g. your own publishing + repository), you would want to set `remote.pushdefault` to + specify the remote to push to for all branches, and use this + option to override it for a specific branch. branch..merge:: Defines, together with branch..remote, the upstream branch @@@ -807,8 -794,7 +807,8 @@@ color.branch: color.branch.:: Use customized color for branch coloration. `` is one of `current` (the current branch), `local` (a local branch), - `remote` (a remote-tracking branch in refs/remotes/), `plain` (other + `remote` (a remote-tracking branch in refs/remotes/), + `upstream` (upstream tracking branch), `plain` (other refs). + The value for these configuration variables is a list of colors (at most @@@ -1110,11 -1096,6 +1110,11 @@@ format.signoff: the rights to submit this work under the same open source license. Please see the 'SubmittingPatches' document for further discussion. +format.coverLetter:: + A boolean that controls whether to generate a cover-letter when + format-patch is invoked, but in addition can be set to "auto", to + generate a cover-letter only when there's more than one patch. + filter..clean:: The command which is used to convert the content of a worktree file to a blob upon checkin. See linkgit:gitattributes[5] for @@@ -1466,14 -1447,6 +1466,14 @@@ http.sslCAPath: with when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_CAPATH' environment variable. +http.sslTry:: + Attempt to use AUTH SSL/TLS and encrypted data transfers + when connecting via regular FTP protocol. This might be needed + if the FTP server requires it for security reasons or you wish + to connect securely whenever remote FTP server supports it. + Default is false since it might trigger certificate verification + errors on misconfigured servers. + http.maxRequests:: How many HTTP requests to launch in parallel. Can be overridden by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5. @@@ -1925,11 -1898,6 +1925,11 @@@ receive.updateserverinfo: If set to true, git-receive-pack will run git-update-server-info after receiving data from git-push and updating refs. +remote.pushdefault:: + The remote to push to by default. Overrides + `branch..remote` for all branches, and is overridden by + `branch..pushremote` for specific branches. + remote..url:: The URL of a remote repository. See linkgit:git-fetch[1] or linkgit:git-push[1]. @@@ -2030,7 -1998,6 +2030,7 @@@ sendemail..*: sendemail.aliasesfile:: sendemail.aliasfiletype:: +sendemail.annotate:: sendemail.bcc:: sendemail.cc:: sendemail.cccmd:: @@@ -2156,13 -2123,7 +2156,13 @@@ uploadpack.hiderefs: are under the hierarchies listed on the value of this variable is excluded, and is hidden from `git ls-remote`, `git fetch`, etc. An attempt to fetch a hidden ref by `git - fetch` will fail. + fetch` will fail. See also `uploadpack.allowtipsha1inwant`. + +uploadpack.allowtipsha1inwant:: + When `uploadpack.hiderefs` is in effect, allow `upload-pack` + to accept a fetch request that asks for an object at the tip + of a hidden ref (by default, such a request is rejected). + see also `uploadpack.hiderefs`. url..insteadOf:: Any URL that starts with this value will be rewritten to diff --combined Documentation/git-rev-parse.txt index 1f9ed6cfd2,f2537bb837..947d62fd25 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@@ -60,19 -60,8 +60,19 @@@ OPTION instead. --verify:: - The parameter given must be usable as a single, valid - object name. Otherwise barf and abort. + Verify that exactly one parameter is provided, and that it + can be turned into a raw 20-byte SHA-1 that can be used to + access the object database. If so, emit it to the standard + output; otherwise, error out. ++ +If you want to make sure that the output actually names an object in +your object database and/or can be used as a specific type of object +you require, you can add "^{type}" peeling operator to the parmeter. +For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` +names an existing object that is a commit-ish (i.e. a commit, or an +annotated tag that points at a commit). To make sure that `$VAR` +names an existing object of any type, `git rev-parse "$VAR^{object}"` +can be used. -q:: --quiet:: @@@ -95,7 -84,7 +95,7 @@@ one. --symbolic:: - Usually the object names are output in SHA1 form (with + Usually the object names are output in SHA-1 form (with possible '{caret}' prefix); this option makes them output in a form as close to the original input as possible. @@@ -180,7 -169,7 +180,7 @@@ print a message to stderr and exit wit --short:: --short=number:: - Instead of outputting the full SHA1 values of object names try to + Instead of outputting the full SHA-1 values of object names try to abbreviate them to a shorter unique name. When no length is specified 7 is used. The minimum length is 4. @@@ -319,12 -308,12 +319,12 @@@ $ git rev-parse --verify HEA * Print the commit object name from the revision in the $REV shell variable: + ------------ -$ git rev-parse --verify $REV +$ git rev-parse --verify $REV^{commit} ------------ + This will error out if $REV is empty or not a valid revision. -* Same as above: +* Similar to above: + ------------ $ git rev-parse --default master --verify $REV diff --combined Documentation/glossary-content.txt index 2478a3963c,740bb325bf..ce3e4fae73 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@@ -100,26 -100,10 +100,23 @@@ to point at the new commit [[def_detached_HEAD]]detached HEAD:: Normally the <> stores the name of a - <>. However, Git also allows you to <> - an arbitrary <> that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be "detached". + <>, and commands that operate on the + history HEAD represents operate on the history leading to the + tip of the branch the HEAD points at. However, Git also + allows you to <> an arbitrary + <> that isn't necessarily the tip of any + particular branch. The HEAD in such a state is called + "detached". ++ +Note that commands that operate on the history of the current branch +(e.g. `git commit` to build a new history on top of it) still work +while the HEAD is detached. They update the HEAD to point at the tip +of the updated history without affecting any branch. Commands that +update or inquire information _about_ the current branch (e.g. `git +branch --set-upstream-to` that sets what remote tracking branch the +current branch integrates with) obviously do not work, as there is no +(real) current branch to ask about in this state. - [[def_dircache]]dircache:: - You are *waaaaay* behind. See <>. - [[def_directory]]directory:: The list you get with "ls" :-) @@@ -128,11 -112,6 +125,6 @@@ it contains modifications which have not been <> to the current <>. - [[def_ent]]ent:: - Favorite synonym to "<>" by some total geeks. See - http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth - explanation. Avoid this term, not to confuse people. - [[def_evil_merge]]evil merge:: An evil merge is a <> that introduces changes that do not appear in any <>. @@@ -174,7 -153,7 +166,7 @@@ created. Configured via the `.git/info/grafts` file. [[def_hash]]hash:: - In Git's context, synonym to <>. + In Git's context, synonym for <>. [[def_head]]head:: A <> to the <> at the tip of a @@@ -246,7 -225,7 +238,7 @@@ This commit is referred to as a "merge [[def_object]]object:: The unit of storage in Git. It is uniquely identified by the - <> of its contents. Consequently, an + <> of its contents. Consequently, an object can not be changed. [[def_object_database]]object database:: @@@ -258,10 -237,9 +250,9 @@@ Synonym for <>. [[def_object_name]]object name:: - The unique identifier of an <>. The <> - of the object's contents using the Secure Hash Algorithm - 1 and usually represented by the 40 character hexadecimal encoding of - the <> of the object. + The unique identifier of an <>. The + object name is usually represented by a 40 character + hexadecimal string. Also colloquially called <>. [[def_object_type]]object type:: One of the identifiers "<>", @@@ -270,8 -248,7 +261,7 @@@ <>. [[def_octopus]]octopus:: - To <> more than two <>. Also denotes an - intelligent predator. + To <> more than two <>. [[def_origin]]origin:: The default upstream <>. Most projects have @@@ -291,7 -268,7 +281,7 @@@ pack. [[def_pathspec]]pathspec:: - Pattern used to specify paths. + Pattern used to limit paths in Git commands. + Pathspecs are used on the command line of "git ls-files", "git ls-tree", "git add", "git grep", "git diff", "git checkout", @@@ -300,6 -277,8 +290,8 @@@ limit the scope of operations to some s worktree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The pathspec syntax is as follows: + + + -- * any path matches itself * the pathspec up to the last slash represents a @@@ -309,11 -288,12 +301,12 @@@ of the pathname. Paths relative to the directory prefix will be matched against that pattern using fnmatch(3); in particular, '*' and '?' _can_ match directory separators. + + -- + For example, Documentation/*.jpg will match all .jpg files in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg. - + A pathspec that begins with a colon `:` has special meaning. In the short form, the leading colon `:` is followed by zero or more "magic @@@ -329,18 -309,10 +322,10 @@@ and a close parentheses `)`, and the re against the path. + The "magic signature" consists of an ASCII symbol that is not - alphanumeric. - + - -- - top `/`;; - The magic word `top` (mnemonic: `/`) makes the pattern match - from the root of the working tree, even when you are running - the command from inside a subdirectory. - -- - + - Currently only the slash `/` is recognized as the "magic signature", - but it is envisioned that we will support more types of magic in later - versions of Git. + alphanumeric. Currently only the slash `/` is recognized as a + "magic signature": it makes the pattern match from the root of + the working tree, even when you are running the command from + inside a subdirectory. + A pathspec with only a colon means "there is no pathspec". This form should not be combined with other pathspec. @@@ -398,7 -370,7 +383,7 @@@ to the result. [[def_ref]]ref:: - A 40-byte hex representation of a <> or a name that + A 40-byte hex representation of a <> or a name that denotes a particular <>. They may be stored in a file under `$GIT_DIR/refs/` directory, or in the `$GIT_DIR/packed-refs` file. @@@ -412,15 -384,7 +397,7 @@@ [[def_refspec]]refspec:: A "refspec" is used by <> and <> to describe the mapping between remote - <> and local ref. They are combined with a colon in - the format :, preceded by an optional plus sign, +. - For example: `git fetch $URL - refs/heads/master:refs/heads/origin` means "grab the master - <> <> from the $URL and store - it as my origin branch head". And `git push - $URL refs/heads/master:refs/heads/to-upstream` means "publish my - master branch head as to-upstream branch at $URL". See also - linkgit:git-push[1]. + <> and local ref. [[def_remote_tracking_branch]]remote-tracking branch:: A regular Git <> that is used to follow changes from @@@ -454,8 -418,9 +431,9 @@@ [[def_SCM]]SCM:: Source code management (tool). - [[def_SHA1]]SHA1:: - Synonym for <>. + [[def_SHA1]]SHA-1:: + "Secure Hash Algorithm 1"; a cryptographic hash function. + In the context of Git used as a synonym for <>. [[def_shallow_repository]]shallow repository:: A shallow <> has an incomplete @@@ -469,7 -434,7 +447,7 @@@ its history can be later deepened with linkgit:git-fetch[1]. [[def_symref]]symref:: - Symbolic reference: instead of containing the <> + Symbolic reference: instead of containing the <> id itself, it is of the format 'ref: refs/some/thing' and when referenced, it recursively dereferences to this reference. '<>' is a prime example of a symref. Symbolic diff --combined Documentation/pretty-formats.txt index afac703f21,342965d4f6..f5b50dcba2 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@@ -75,7 -75,7 +75,7 @@@ This is designed to be as compact as po * 'raw' + The 'raw' format shows the entire commit exactly as - stored in the commit object. Notably, the SHA1s are + stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and 'parents' information show the true parent commits, without taking grafts nor history @@@ -131,8 -131,7 +131,8 @@@ The placeholders are - '%B': raw body (unwrapped subject and body) - '%N': commit notes - '%GG': raw verification message from GPG for a signed commit -- '%G?': show either "G" for Good or "B" for Bad for a signed commit +- '%G?': show "G" for a Good signature, "B" for a Bad signature, "U" for a good, + untrusted signature and "N" for no signature - '%GS': show the name of the signer for a signed commit - '%GK': show the key used to sign a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` diff --combined Documentation/revisions.txt index 8855b1a0ac,c5822634fc..a8ff691492 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@@ -2,13 -2,13 +2,13 @@@ SPECIFYING REVISION -------------------- A revision parameter '' typically, but not necessarily, names a - commit object. It uses what is called an 'extended SHA1' + commit object. It uses what is called an 'extended SHA-1' syntax. Here are various ways to spell object names. The ones listed near the end of this list name trees and blobs contained in a commit. '', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e':: - The full SHA1 object name (40-byte hexadecimal string), or + The full SHA-1 object name (40-byte hexadecimal string), or a leading substring that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there is no other object in @@@ -116,11 -116,6 +116,11 @@@ some output processing may assume ref n object of that type is found or the object cannot be dereferenced anymore (in which case, barf). '{caret}0' is a short-hand for '{caret}\{commit\}'. ++ +'rev{caret}\{object\}' can be used to make sure 'rev' names an +object that exists, without requiring 'rev' to be a tag, and +without dereferencing 'rev'; because a tag is already an object, +it does not have to be dereferenced even once to get to an object. '{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: A suffix '{caret}' followed by an empty brace pair