From: Junio C Hamano Date: Fri, 26 Apr 2013 22:28:23 +0000 (-0700) Subject: Merge branch 'jn/glossary-revision' X-Git-Tag: v1.8.3-rc0~4 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/019eb0dd351ee53b875df27f6748bcb69dc02063?ds=inline;hp=-c Merge branch 'jn/glossary-revision' The wording for "revision" in the glossary wanted to say it refers to "commit (noun) as a concept" but it was badly phrased. This may need further updates to hint that in contexts where it is clear, the word may refer to an object name, not necessarily a commit. But the patch as-is is already an improvement. * jn/glossary-revision: glossary: a revision is just a commit --- 019eb0dd351ee53b875df27f6748bcb69dc02063 diff --combined Documentation/glossary-content.txt index ce3e4fae73,521fceebe6..68a18e1497 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@@ -100,22 -100,12 +100,22 @@@ 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". - -[[def_dircache]]dircache:: - You are *waaaaay* behind. See <>. + <>, 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_directory]]directory:: The list you get with "ls" :-) @@@ -125,6 -115,11 +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 <>. @@@ -166,7 -161,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 @@@ -238,7 -233,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:: @@@ -250,9 -245,10 +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 "<>", @@@ -261,7 -257,8 +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 @@@ -281,7 -278,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", @@@ -290,8 -287,6 +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 @@@ -301,12 -296,11 +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 @@@ -322,10 -316,18 +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. @@@ -383,7 -385,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. @@@ -397,7 -399,15 +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 @@@ -420,9 -430,7 +420,7 @@@ <> left behind. [[def_revision]]revision:: - A particular state of files and directories which was stored in the - <>. It is referenced by a - <>. + Synonym for <> (the noun). [[def_rewind]]rewind:: To throw away part of the development, i.e. to assign the @@@ -431,9 -439,8 +429,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 @@@ -447,7 -454,7 +445,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