From: Junio C Hamano Date: Mon, 22 Apr 2013 18:26:58 +0000 (-0700) Subject: Merge branch 'ta/glossary' into maint X-Git-Tag: v1.8.2.2~21 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/76f9bc9f53a7bc72950d8ee88e88bf41903fab74?ds=inline;hp=-c Merge branch 'ta/glossary' into maint * 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 --- 76f9bc9f53a7bc72950d8ee88e88bf41903fab74 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