Changeset 782 for git/branches/dmik/Documentation/glossary-content.txt

Timestamp:

Jun 23, 2014, 9:45:51 PM (11 years ago)

Author:

dmik

Message:

git: Merge version 2.0.0 from vendor to dmik branch.

Location:

git/branches/dmik

Files:

• . (modified) (1 prop)
• Documentation/glossary-content.txt (modified) (29 diffs)

git/branches/dmik/Documentation/glossary-content.txt ¶

@@ -8 +8 @@
         named <<def_directory,directory>> with a `.git` suffix that does not
         have a locally checked-out copy of any of the files under
-        revision control. That is, all of the `git`
+        revision control. That is, all of the Git
         administrative and control files that would normally be present in the
         hidden `.git` sub-directory are directly present in the
@@ -23 +23 @@
         that branch.  The tip of the branch is referenced by a branch
         <<def_head,head>>, which moves forward as additional development
-        is done on the branch.  A single git
+        is done on the branch.  A single Git
         <<def_repository,repository>> can track an arbitrary number of
         branches, but your <<def_working_tree,working tree>> is
@@ -38 +38 @@
 
 [[def_changeset]]changeset::
-        BitKeeper/cvsps speak for "<<def_commit,commit>>". Since git does not
+        BitKeeper/cvsps speak for "<<def_commit,commit>>". Since Git does not
         store changes, but states, it really does not make sense to use the term
-        "changesets" with git.
+        "changesets" with Git.
 
 [[def_checkout]]checkout::
@@ -53 +53 @@
         In <<def_SCM,SCM>> jargon, "cherry pick" means to choose a subset of
         changes out of a series of changes (typically commits) and record them
-        as a new series of changes on top of a different codebase. In GIT, this is
+        as a new series of changes on top of a different codebase. In Git, this is
         performed by the "git cherry-pick" command to extract the change introduced
         by an existing <<def_commit,commit>> and to record it based on the tip
@@ -65 +65 @@
 [[def_commit]]commit::
         As a noun: A single point in the
-        git history; the entire history of a project is represented as a
+        Git history; the entire history of a project is represented as a
         set of interrelated commits.  The word "commit" is often
-        used by git in the same places other revision control systems
+        used by Git in the same places other revision control systems
         use the words "revision" or "version".  Also used as a short
         hand for <<def_commit_object,commit object>>.
 +
 As a verb: The action of storing a new snapshot of the project's
-state in the git history, by creating a new commit representing the current
+state in the Git history, by creating a new commit representing the current
 state of the <<def_index,index>> and advancing <<def_HEAD,HEAD>>
 to point at the new commit.
@@ -83 +83 @@
         revision.
 
-[[def_core_git]]core git::
-        Fundamental data structures and utilities of git. Exposes only limited
+[[def_commit-ish]]commit-ish (also committish)::
+        A <<def_commit_object,commit object>> or an
+        <<def_object,object>> that can be recursively dereferenced to
+        a commit object.
+        The following are all commit-ishes:
+        a commit object,
+        a <<def_tag_object,tag object>> that points to a commit
+        object,
+        a tag object that points to a tag object that points to a
+        commit object,
+        etc.
+
+[[def_core_git]]core Git::
+        Fundamental data structures and utilities of Git. Exposes only limited
         source code management tools.
 
@@ -101 +113 @@
 [[def_detached_HEAD]]detached HEAD::
         Normally the <<def_HEAD,HEAD>> stores the name of a
-        <<def_branch,branch>>.  However, git also allows you to <<def_checkout,check out>>
-        an arbitrary <<def_commit,commit>> 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 <<def_index,index>>.
+        <<def_branch,branch>>, 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 <<def_checkout,check out>> an arbitrary
+        <<def_commit,commit>> 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::
@@ -115 +137 @@
         it contains modifications which have not been <<def_commit,committed>> to the current
         <<def_branch,branch>>.
-
-[[def_ent]]ent::
-        Favorite synonym to "<<def_tree-ish,tree-ish>>" 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::
@@ -143 +160 @@
 
 [[def_file_system]]file system::
-        Linus Torvalds originally designed git to be a user space file system,
+        Linus Torvalds originally designed Git to be a user space file system,
         i.e. the infrastructure to hold files and directories. That ensured the
-        efficiency and speed of git.
-
-[[def_git_archive]]git archive::
+        efficiency and speed of Git.
+
+[[def_git_archive]]Git archive::
         Synonym for <<def_repository,repository>> (for arch people).
+
+[[def_gitfile]]gitfile::
+        A plain file `.git` at the root of a working tree that
+        points at the directory that is the real repository.
 
 [[def_grafts]]grafts::
         Grafts enables two otherwise different lines of development to be joined
         together by recording fake ancestry information for commits. This way
-        you can make git pretend the set of <<def_parent,parents>> a <<def_commit,commit>> has
+        you can make Git pretend the set of <<def_parent,parents>> a <<def_commit,commit>> has
         is different from what was recorded when the commit was
         created. Configured via the `.git/info/grafts` file.
++
+Note that the grafts mechanism is outdated and can lead to problems
+transferring objects between repositories; see linkgit:git-replace[1]
+for a more flexible and robust system to do the same thing.
 
 [[def_hash]]hash::
-        In git's context, synonym to <<def_object_name,object name>>.
+        In Git's context, synonym for <<def_object_name,object name>>.
 
 [[def_head]]head::
@@ -178 +203 @@
 
 [[def_hook]]hook::
-        During the normal execution of several git commands, call-outs are made
+        During the normal execution of several Git commands, call-outs are made
         to optional scripts that allow a developer to add functionality or
         checking. Typically, the hooks allow for a command to be pre-verified
@@ -185 +210 @@
         `$GIT_DIR/hooks/` directory, and are enabled by simply
         removing the `.sample` suffix from the filename. In earlier versions
-        of git you had to make them executable.
+        of Git you had to make them executable.
 
 [[def_index]]index::
@@ -202 +227 @@
 [[def_master]]master::
         The default development <<def_branch,branch>>. Whenever you
-        create a git <<def_repository,repository>>, a branch named
+        create a Git <<def_repository,repository>>, a branch named
         "master" is created, and becomes the active branch. In most
         cases, this contains the local development, though that is
@@ -229 +254 @@
 
 [[def_object]]object::
-        The unit of storage in git. It is uniquely identified by the
-        <<def_SHA1,SHA1>> of its contents. Consequently, an
+        The unit of storage in Git. It is uniquely identified by the
+        <<def_SHA1,SHA-1>> of its contents. Consequently, an
         object can not be changed.
 
@@ -242 +267 @@
 
 [[def_object_name]]object name::
-        The unique identifier of an <<def_object,object>>. The <<def_hash,hash>>
-        of the object's contents using the Secure Hash Algorithm
-        1 and usually represented by the 40 character hexadecimal encoding of
-        the <<def_hash,hash>> of the object.
+        The unique identifier of an <<def_object,object>>.  The
+        object name is usually represented by a 40 character
+        hexadecimal string.  Also colloquially called <<def_SHA1,SHA-1>>.
 
 [[def_object_type]]object type::
@@ -254 +278 @@
 
 [[def_octopus]]octopus::
-        To <<def_merge,merge>> more than two <<def_branch,branches>>. Also denotes an
-        intelligent predator.
+        To <<def_merge,merge>> more than two <<def_branch,branches>>.
 
 [[def_origin]]origin::
@@ -261 +284 @@
         at least one upstream project which they track. By default
         'origin' is used for that purpose. New upstream updates
-        will be fetched into remote <<def_remote_tracking_branch,remote-tracking branches>> named
+        will be fetched into <<def_remote_tracking_branch,remote-tracking branches>> named
         origin/name-of-upstream-branch, which you can see using
         `git branch -r`.
@@ -275 +298 @@
 
 [[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
@@ -284 +307 @@
 paths are relative to the current directory or toplevel.  The
 pathspec syntax is as follows:
++
+--
 
 * any path matches itself
@@ -293 +318 @@
   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
 signature" letters (which optionally is terminated by another colon `:`),
-and the remainder is the pattern to match against the path. The optional
-colon that terminates the "magic signature" can be omitted if the pattern
-begins with a character that cannot be a "magic signature" and is not a
-colon.
+and the remainder is the pattern to match against the path.
+The "magic signature" consists of ASCII symbols that are neither
+alphanumeric, glob, regex special charaters nor colon.
+The optional colon that terminates the "magic signature" can be
+omitted if the pattern begins with a character that does not belong to
+"magic signature" symbol set and is not a colon.
 +
 In the long form, the leading colon `:` is followed by a open
@@ -312 +340 @@
 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.
-+
 A pathspec with only a colon means "there is no pathspec". This form
 should not be combined with other pathspec.
++
+--
+top;;
+        The magic word `top` (magic signature: `/`) makes the pattern
+        match from the root of the working tree, even when you are
+        running the command from inside a subdirectory.
+
+literal;;
+        Wildcards in the pattern such as `*` or `?` are treated
+        as literal characters.
+
+icase;;
+        Case insensitive match.
+
+glob;;
+        Git treats the pattern as a shell glob suitable for
+        consumption by fnmatch(3) with the FNM_PATHNAME flag:
+        wildcards in the pattern will not match a / in the pathname.
+        For example, "Documentation/{asterisk}.html" matches
+        "Documentation/git.html" but not "Documentation/ppc/ppc.html"
+        or "tools/perf/Documentation/perf.html".
++
+Two consecutive asterisks ("`**`") in patterns matched against
+full pathname may have special meaning:
+
+ - A leading "`**`" followed by a slash means match in all
+   directories. For example, "`**/foo`" matches file or directory
+   "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`"
+   matches file or directory "`bar`" anywhere that is directly
+   under directory "`foo`".
+
+ - A trailing "`/**`" matches everything inside. For example,
+   "`abc/**`" matches all files inside directory "abc", relative
+   to the location of the `.gitignore` file, with infinite depth.
+
+ - A slash followed by two consecutive asterisks then a slash
+   matches zero or more directories. For example, "`a/**/b`"
+   matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
+
+ - Other consecutive asterisks are considered invalid.
++
+Glob magic is incompatible with literal magic.
+
+exclude;;
+        After a path matches any non-exclude pathspec, it will be run
+        through all exclude pathspec (magic signature: `!`). If it
+        matches, the path is ignored.
+--
 
 [[def_parent]]parent::
@@ -342 +404 @@
 
 [[def_plumbing]]plumbing::
-        Cute name for <<def_core_git,core git>>.
+        Cute name for <<def_core_git,core Git>>.
 
 [[def_porcelain]]porcelain::
         Cute name for programs and program suites depending on
-        <<def_core_git,core git>>, presenting a high level access to
-        core git. Porcelains expose more of a <<def_SCM,SCM>>
+        <<def_core_git,core Git>>, presenting a high level access to
+        core Git. Porcelains expose more of a <<def_SCM,SCM>>
         interface than the <<def_plumbing,plumbing>>.
 
@@ -382 +444 @@
 
 [[def_ref]]ref::
-        A 40-byte hex representation of a <<def_SHA1,SHA1>> or a name that
-        denotes a particular <<def_object,object>>. They may be stored in
-        a file under `$GIT_DIR/refs/` directory, or
-        in the `$GIT_DIR/packed-refs` file.
+        A name that begins with `refs/` (e.g. `refs/heads/master`)
+        that points to an <<def_object_name,object name>> or another
+        ref (the latter is called a <<def_symref,symbolic ref>>).
+        For convenience, a ref can sometimes be abbreviated when used
+        as an argument to a Git command; see linkgit:gitrevisions[7]
+        for details.
+        Refs are stored in the <<def_repository,repository>>.
++
+The ref namespace is hierarchical.
+Different subhierarchies are used for different purposes (e.g. the
+`refs/heads/` hierarchy is used to represent local branches).
++
+There are a few special-purpose refs that do not begin with `refs/`.
+The most notable example is `HEAD`.
 
 [[def_reflog]]reflog::
@@ -396 +468 @@
         A "refspec" is used by <<def_fetch,fetch>> and
         <<def_push,push>> to describe the mapping between remote
-        <<def_ref,ref>> and local ref. They are combined with a colon in
-        the format <src>:<dst>, preceded by an optional plus sign, +.
-        For example: `git fetch $URL
-        refs/heads/master:refs/heads/origin` means "grab the master
-        <<def_branch,branch>> <<def_head,head>> 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].
+        <<def_ref,ref>> and local ref.
 
 [[def_remote_tracking_branch]]remote-tracking branch::
-        A regular git <<def_branch,branch>> that is used to follow changes from
-        another <<def_repository,repository>>. A remote-tracking
-        branch should not contain direct modifications or have local commits
-        made to it. A remote-tracking branch can usually be
-        identified as the right-hand-side <<def_ref,ref>> in a Pull:
-        <<def_refspec,refspec>>.
+        A <<def_ref,ref>> that is used to follow changes from another
+        <<def_repository,repository>>. It typically looks like
+        'refs/remotes/foo/bar' (indicating that it tracks a branch named
+        'bar' in a remote named 'foo'), and matches the right-hand-side of
+        a configured fetch <<def_refspec,refspec>>. A remote-tracking
+        branch should not contain direct modifications or have local
+        commits made to it.
 
 [[def_repository]]repository::
@@ -427 +492 @@
 
 [[def_revision]]revision::
-        A particular state of files and directories which was stored in the
-        <<def_object_database,object database>>. It is referenced by a
-        <<def_commit_object,commit object>>.
+        Synonym for <<def_commit,commit>> (the noun).
 
 [[def_rewind]]rewind::
@@ -438 +501 @@
         Source code management (tool).
 
-[[def_SHA1]]SHA1::
-        Synonym for <<def_object_name,object name>>.
+[[def_SHA1]]SHA-1::
+        "Secure Hash Algorithm 1"; a cryptographic hash function.
+        In the context of Git used as a synonym for <<def_object_name,object name>>.
 
 [[def_shallow_repository]]shallow repository::
         A shallow <<def_repository,repository>> has an incomplete
         history some of whose <<def_commit,commits>> have <<def_parent,parents>> cauterized away (in other
-        words, git is told to pretend that these commits do not have the
+        words, Git is told to pretend that these commits do not have the
         parents, even though they are recorded in the <<def_commit_object,commit
         object>>). This is sometimes useful when you are interested only in the
@@ -453 +517 @@
 
 [[def_symref]]symref::
-        Symbolic reference: instead of containing the <<def_SHA1,SHA1>>
+        Symbolic reference: instead of containing the <<def_SHA1,SHA-1>>
         id itself, it is of the format 'ref: refs/some/thing' and when
         referenced, it recursively dereferences to this reference.
@@ -465 +529 @@
         <<def_tag_object,tag>> or a <<def_commit_object,commit object>>).
         In contrast to a <<def_head,head>>, a tag is not updated by
-        the `commit` command. A git tag has nothing to do with a Lisp
+        the `commit` command. A Git tag has nothing to do with a Lisp
         tag (which would be called an <<def_object_type,object type>>
-        in git's context). A tag is most typically used to mark a particular
+        in Git's context). A tag is most typically used to mark a particular
         point in the commit ancestry <<def_chain,chain>>.
 
@@ -477 +541 @@
 
 [[def_topic_branch]]topic branch::
-        A regular git <<def_branch,branch>> that is used by a developer to
+        A regular Git <<def_branch,branch>> that is used by a developer to
         identify a conceptual line of development. Since branches are very easy
         and inexpensive, it is often desirable to have several small branches
@@ -493 +557 @@
         <<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
 
-[[def_tree-ish]]tree-ish::
-        A <<def_ref,ref>> pointing to either a <<def_commit_object,commit
-        object>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag
-        object>> pointing to a tag or commit or tree object.
+[[def_tree-ish]]tree-ish (also treeish)::
+        A <<def_tree_object,tree object>> or an <<def_object,object>>
+        that can be recursively dereferenced to a tree object.
+        Dereferencing a <<def_commit_object,commit object>> yields the
+        tree object corresponding to the <<def_revision,revision>>'s
+        top <<def_directory,directory>>.
+        The following are all tree-ishes:
+        a <<def_commit-ish,commit-ish>>,
+        a tree object,
+        a <<def_tag_object,tag object>> that points to a tree object,
+        a tag object that points to a tag object that points to a tree
+        object,
+        etc.
 
 [[def_unmerged_index]]unmerged index::