diff options
Diffstat (limited to 'Documentation/glossary-content.txt')
| -rw-r--r-- | Documentation/glossary-content.txt | 137 |
1 files changed, 100 insertions, 37 deletions
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 5a537268e2..575c18f776 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -98,9 +98,8 @@ to point at the new commit. revision. [[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. + A <<def_commit_object,commit object>> or an <<def_object,object>> that + can be recursively <<def_dereference,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 @@ -125,6 +124,25 @@ to point at the new commit. dangling object has no references to it from any reference or <<def_object,object>> in the <<def_repository,repository>>. +[[def_dereference]]dereference:: + Referring to a <<def_symref,symbolic ref>>: the action of accessing the + <<def_ref,reference>> pointed at by a symbolic ref. Recursive + dereferencing involves repeating the aforementioned process on the + resulting ref until a non-symbolic reference is found. ++ +Referring to a <<def_tag_object,tag object>>: the action of accessing the +<<def_object,object>> a tag points at. Tags are recursively dereferenced by +repeating the operation on the result object until the result has either a +specified <<def_object_type,object type>> (where applicable) or any non-"tag" +object type. A synonym for "recursive dereference" in the context of tags is +"<<def_peel,peel>>". ++ +Referring to a <<def_commit_object,commit object>>: the action of accessing +the commit's tree object. Commits cannot be dereferenced recursively. ++ +Unless otherwise specified, "dereferencing" as it used in the context of Git +commands or protocols is implicitly recursive. + [[def_detached_HEAD]]detached HEAD:: Normally the <<def_HEAD,HEAD>> stores the name of a <<def_branch,branch>>, and commands that operate on the @@ -184,9 +202,11 @@ current branch integrates with) obviously do not work, as there is no [[def_gitfile]]gitfile:: A plain file `.git` at the root of a working tree that points at the directory that is the real repository. + For proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1]. + For syntax see linkgit:gitrepository-layout[5]. [[def_grafts]]grafts:: - Grafts enables two otherwise different lines of development to be joined + Grafts enable 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 is different from what was recorded when the commit was @@ -294,6 +314,12 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_octopus]]octopus:: To <<def_merge,merge>> more than two <<def_branch,branches>>. +[[def_orphan]]orphan:: + The act of getting on a <<def_branch,branch>> that does not + exist yet (i.e., an <<def_unborn,unborn>> branch). After + such an operation, the commit first created becomes a commit + without a parent, starting a new history. + [[def_origin]]origin:: The default upstream <<def_repository,repository>>. Most projects have at least one upstream project which they track. By default @@ -444,6 +470,10 @@ exclude;; of the logical predecessor(s) in the line of development, i.e. its parents. +[[def_peel]]peel:: + The action of recursively <<def_dereference,dereferencing>> a + <<def_tag_object,tag object>>. + [[def_pickaxe]]pickaxe:: The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore routines that help select changes that add or delete a given text @@ -467,20 +497,18 @@ exclude;; unusual refs. [[def_pseudoref]]pseudoref:: - Pseudorefs are a class of files under `$GIT_DIR` which behave - like refs for the purposes of rev-parse, but which are treated - specially by git. Pseudorefs both have names that are all-caps, - and always start with a line consisting of a - <<def_SHA1,SHA-1>> followed by whitespace. So, HEAD is not a - pseudoref, because it is sometimes a symbolic ref. They might - optionally contain some additional data. `MERGE_HEAD` and - `CHERRY_PICK_HEAD` are examples. Unlike - <<def_per_worktree_ref,per-worktree refs>>, these files cannot - be symbolic refs, and never have reflogs. They also cannot be - updated through the normal ref update machinery. Instead, - they are updated by directly writing to the files. However, - they can be read as if they were refs, so `git rev-parse - MERGE_HEAD` will work. + A ref that has different semantics than normal refs. These refs can be + read via normal Git commands, but cannot be written to by commands like + linkgit:git-update-ref[1]. ++ +The following pseudorefs are known to Git: + + - `FETCH_HEAD` is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It + may refer to multiple object IDs. Each object ID is annotated with metadata + indicating where it was fetched from and its fetch status. + + - `MERGE_HEAD` is written by linkgit:git-merge[1] when resolving merge + conflicts. It contains all commit IDs which are being merged. [[def_pull]]pull:: Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and @@ -522,20 +550,38 @@ exclude;; to the result. [[def_ref]]ref:: - 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>>). + A name 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). +Ref names must either start with `refs/` or be located in the root of +the hierarchy. For the latter, their name must follow these rules: ++ + - The name consists of only upper-case characters or underscores. + + - The name ends with "`_HEAD`" or is equal to "`HEAD`". ++ +There are some irregular refs in the root of the hierarchy that do not +match these rules. The following list is exhaustive and shall not be +extended in the future: ++ + - `AUTO_MERGE` + + - `BISECT_EXPECTED_REV` + + - `NOTES_MERGE_PARTIAL` + + - `NOTES_MERGE_REF` + + - `MERGE_AUTOSTASH` + -There are a few special-purpose refs that do not begin with `refs/`. -The most notable example is `HEAD`. +Different subhierarchies are used for different purposes. For example, +the `refs/heads/` hierarchy is used to represent local branches whereas +the `refs/tags/` hierarchy is used to represent local tags.. [[def_reflog]]reflog:: A reflog shows the local "history" of a ref. In other words, @@ -546,7 +592,8 @@ The most notable example is `HEAD`. [[def_refspec]]refspec:: A "refspec" is used by <<def_fetch,fetch>> and <<def_push,push>> to describe the mapping between remote - <<def_ref,ref>> and local ref. + <<def_ref,ref>> and local ref. See linkgit:git-fetch[1] or + linkgit:git-push[1] for details. [[def_remote]]remote repository:: A <<def_repository,repository>> which is used to track the same @@ -620,12 +667,11 @@ The most notable example is `HEAD`. copies of) commit objects of the contained submodules. [[def_symref]]symref:: - 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. - '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic - references are manipulated with the linkgit:git-symbolic-ref[1] - command. + 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 <<def_dereference,dereferences>> to this reference. + '<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic references + are manipulated with the linkgit:git-symbolic-ref[1] command. [[def_tag]]tag:: A <<def_ref,ref>> under `refs/tags/` namespace that points to an @@ -650,6 +696,11 @@ The most notable example is `HEAD`. that each contain very well defined concepts or small incremental yet related changes. +[[def_trailer]]trailer:: + Key-value metadata. Trailers are optionally found at the end of + a commit message. Might be called "footers" or "tags" in other + communities. See linkgit:git-interpret-trailers[1]. + [[def_tree]]tree:: Either a <<def_working_tree,working tree>>, or a <<def_tree_object,tree object>> together with the dependent <<def_blob_object,blob>> and tree objects @@ -661,11 +712,11 @@ The most notable example is `HEAD`. <<def_tree,tree>> is equivalent to a <<def_directory,directory>>. [[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>>. + A <<def_tree_object,tree object>> or an <<def_object,object>> that can + be recursively <<def_dereference,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, @@ -674,6 +725,18 @@ The most notable example is `HEAD`. object, etc. +[[def_unborn]]unborn:: + The <<def_HEAD,HEAD>> can point at a <<def_branch,branch>> + that does not yet exist and that does not have any commit on + it yet, and such a branch is called an unborn branch. The + most typical way users encounter an unborn branch is by + creating a repository anew without cloning from elsewhere. + The HEAD would point at the 'main' (or 'master', depending + on your configuration) branch that is yet to be born. Also + some operations can get you on an unborn branch with their + <<def_orphan,orphan>> option. + + [[def_unmerged_index]]unmerged index:: An <<def_index,index>> which contains unmerged <<def_index_entry,index entries>>. |