From c8bae7493d2f2910b57f13ded012e86bdcfb0532 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 16:47:53 +0200 Subject: Adding upstream version 1:2.39.2. Signed-off-by: Daniel Baumann --- Documentation/glossary-content.txt | 703 +++++++++++++++++++++++++++++++++++++ 1 file changed, 703 insertions(+) create mode 100644 Documentation/glossary-content.txt (limited to 'Documentation/glossary-content.txt') diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt new file mode 100644 index 0000000..5a53726 --- /dev/null +++ b/Documentation/glossary-content.txt @@ -0,0 +1,703 @@ +[[def_alternate_object_database]]alternate object database:: + Via the alternates mechanism, a <> + can inherit part of its <> + from another object database, which is called an "alternate". + +[[def_bare_repository]]bare repository:: + A bare repository is normally an appropriately + named <> 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 + administrative and control files that would normally be present in the + hidden `.git` sub-directory are directly present in the + `repository.git` directory instead, + and no other files are present and checked out. Usually publishers of + public repositories make bare repositories available. + +[[def_blob_object]]blob object:: + Untyped <>, e.g. the contents of a file. + +[[def_branch]]branch:: + A "branch" is a line of development. The most recent + <> on a branch is referred to as the tip of + that branch. The tip of the branch is <> by a branch + <>, which moves forward as additional development + is done on the branch. A single Git + <> can track an arbitrary number of + branches, but your <> is + associated with just one of them (the "current" or "checked out" + branch), and <> points to that branch. + +[[def_cache]]cache:: + Obsolete for: <>. + +[[def_chain]]chain:: + A list of objects, where each <> in the list contains + a reference to its successor (for example, the successor of a + <> could be one of its <>). + +[[def_changeset]]changeset:: + BitKeeper/cvsps speak for "<>". Since Git does not + store changes, but states, it really does not make sense to use the term + "changesets" with Git. + +[[def_checkout]]checkout:: + The action of updating all or part of the + <> with a <> + or <> from the + <>, and updating the + <> and <> if the whole working tree has + been pointed at a new <>. + +[[def_cherry-picking]]cherry-picking:: + In <> 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 + performed by the "git cherry-pick" command to extract the change introduced + by an existing <> and to record it based on the tip + of the current <> as a new commit. + +[[def_clean]]clean:: + A <> is clean, if it + corresponds to the <> referenced by the current + <>. Also see "<>". + +[[def_commit]]commit:: + As a noun: A single point in the + 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 + use the words "revision" or "version". Also used as a short + hand for <>. ++ +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 of the <> and advancing <> +to point at the new commit. + +[[def_commit_graph_general]]commit graph concept, representations and usage:: + A synonym for the <> structure formed by the commits + in the object database, <> by branch tips, + using their <> of linked commits. + This structure is the definitive commit graph. The + graph can be represented in other ways, e.g. the + <>. + +[[def_commit_graph_file]]commit-graph file:: + The "commit-graph" (normally hyphenated) file is a supplemental + representation of the <> + which accelerates commit graph walks. The "commit-graph" file is + stored either in the .git/objects/info directory or in the info + directory of an alternate object database. + +[[def_commit_object]]commit object:: + An <> which contains the information about a + particular <>, such as <>, committer, + author, date and the <> which corresponds + to the top <> of the stored + revision. + +[[def_commit-ish]]commit-ish (also committish):: + A <> or an + <> that can be recursively dereferenced to + a commit object. + The following are all commit-ishes: + a commit object, + a <> 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. + +[[def_DAG]]DAG:: + Directed acyclic graph. The <> form a + directed acyclic graph, because they have parents (directed), and the + graph of commit objects is acyclic (there is no <> + which begins and ends with the same <>). + +[[def_dangling_object]]dangling object:: + An <> which is not + <> even from other unreachable objects; a + dangling object has no references to it from any + reference or <> in the <>. + +[[def_detached_HEAD]]detached HEAD:: + Normally the <> stores the name of a + <>, 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" :-) + +[[def_dirty]]dirty:: + A <> is said to be "dirty" if + it contains modifications which have not been <> to the current + <>. + +[[def_evil_merge]]evil merge:: + An evil merge is a <> that introduces changes that + do not appear in any <>. + +[[def_fast_forward]]fast-forward:: + A fast-forward is a special type of <> where you have a + <> and you are "merging" another + <>'s changes that happen to be a descendant of what + you have. In such a case, you do not make a new <> + <> but instead just update your branch to point at the same + revision as the branch you are merging. This will happen frequently on a + <> of a remote + <>. + +[[def_fetch]]fetch:: + Fetching a <> means to get the + branch's <> from a remote + <>, to find out which objects are + missing from the local <>, + and to get them, too. See also linkgit:git-fetch[1]. + +[[def_file_system]]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:: + Synonym for <> (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 <> a <> 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 for <>. + +[[def_head]]head:: + A <> to the <> at the tip of a + <>. Heads are stored in a file in + `$GIT_DIR/refs/heads/` directory, except when using packed refs. (See + linkgit:git-pack-refs[1].) + +[[def_HEAD]]HEAD:: + The current <>. In more detail: Your <> is normally derived from the state of the tree + referred to by HEAD. HEAD is a reference to one of the + <> in your repository, except when using a + <>, in which case it directly + references an arbitrary commit. + +[[def_head_ref]]head ref:: + A synonym for <>. + +[[def_hook]]hook:: + 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 + and potentially aborted, and allow for a post-notification after the + operation is done. The hook scripts are found in the + `$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. + +[[def_index]]index:: + A collection of files with stat information, whose contents are stored + as objects. The index is a stored version of your + <>. Truth be told, it can also contain a second, and even + a third version of a working tree, which are used + when <>. + +[[def_index_entry]]index entry:: + The information regarding a particular file, stored in the + <>. An index entry can be unmerged, if a + <> was started, but not yet finished (i.e. if + the index contains multiple versions of that file). + +[[def_master]]master:: + The default development <>. Whenever you + create a Git <>, a branch named + "master" is created, and becomes the active branch. In most + cases, this contains the local development, though that is + purely by convention and is not required. + +[[def_merge]]merge:: + As a verb: To bring the contents of another + <> (possibly from an external + <>) into the current branch. In the + case where the merged-in branch is from a different repository, + this is done by first <> the remote branch + and then merging the result into the current branch. This + combination of fetch and merge operations is called a + <>. Merging is performed by an automatic process + that identifies changes made since the branches diverged, and + then applies all those changes together. In cases where changes + conflict, manual intervention may be required to complete the + merge. ++ +As a noun: unless it is a <>, a +successful merge results in the creation of a new <> +representing the result of the merge, and having as +<> the tips of the merged <>. +This commit is referred to as a "merge commit", or sometimes just a +"merge". + +[[def_object]]object:: + The unit of storage in Git. It is uniquely identified by the + <> of its contents. Consequently, an + object cannot be changed. + +[[def_object_database]]object database:: + Stores a set of "objects", and an individual <> is + identified by its <>. The objects usually + live in `$GIT_DIR/objects/`. + +[[def_object_identifier]]object identifier (oid):: + Synonym for <>. + +[[def_object_name]]object name:: + 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 "<>", + "<>", "<>" or + "<>" describing the type of an + <>. + +[[def_octopus]]octopus:: + To <> more than two <>. + +[[def_origin]]origin:: + The default upstream <>. Most projects have + at least one upstream project which they track. By default + 'origin' is used for that purpose. New upstream updates + will be fetched into <> named + origin/name-of-upstream-branch, which you can see using + `git branch -r`. + +[[def_overlay]]overlay:: + Only update and add files to the working directory, but don't + delete them, similar to how 'cp -R' would update the contents + in the destination directory. This is the default mode in a + <> when checking out files from the + <> or a <>. In + contrast, no-overlay mode also deletes tracked files not + present in the source, similar to 'rsync --delete'. + +[[def_pack]]pack:: + A set of objects which have been compressed into one file (to save space + or to transmit them efficiently). + +[[def_pack_index]]pack index:: + The list of identifiers, and other information, of the objects in a + <>, to assist in efficiently accessing the contents of a + pack. + +[[def_pathspec]]pathspec:: + 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", +and many other commands to +limit the scope of operations to some subset of the tree or +working tree. 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 + directory prefix. The scope of that pathspec is + limited to that subtree. +* the rest of the pathspec is a pattern for the remainder + 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 +signature" letters (which optionally is terminated by another 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 characters 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 an open +parenthesis `(`, a comma-separated list of zero or more "magic words", +and a close parentheses `)`, and the remainder is the pattern to match +against the path. ++ +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. + +attr;; +After `attr:` comes a space separated list of "attribute +requirements", all of which must be met in order for the +path to be considered a match; this is in addition to the +usual non-magic pathspec pattern matching. +See linkgit:gitattributes[5]. ++ +Each of the attribute requirements for the path takes one of +these forms: + +- "`ATTR`" requires that the attribute `ATTR` be set. + +- "`-ATTR`" requires that the attribute `ATTR` be unset. + +- "`ATTR=VALUE`" requires that the attribute `ATTR` be + set to the string `VALUE`. + +- "`!ATTR`" requires that the attribute `ATTR` be + unspecified. ++ +Note that when matching against a tree object, attributes are still +obtained from working tree, not from the given tree object. + +exclude;; + After a path matches any non-exclude pathspec, it will be run + through all exclude pathspecs (magic signature: `!` or its + synonym `^`). If it matches, the path is ignored. When there + is no non-exclude pathspec, the exclusion is applied to the + result set as if invoked without any pathspec. +-- + +[[def_parent]]parent:: + A <> contains a (possibly empty) list + of the logical predecessor(s) in the line of development, i.e. its + parents. + +[[def_pickaxe]]pickaxe:: + The term <> refers to an option to the diffcore + routines that help select changes that add or delete a given text + string. With the `--pickaxe-all` option, it can be used to view the full + <> that introduced or removed, say, a + particular line of text. See linkgit:git-diff[1]. + +[[def_plumbing]]plumbing:: + Cute name for <>. + +[[def_porcelain]]porcelain:: + Cute name for programs and program suites depending on + <>, presenting a high level access to + core Git. Porcelains expose more of a <> + interface than the <>. + +[[def_per_worktree_ref]]per-worktree ref:: + Refs that are per-<>, rather than + global. This is presently only <> and any refs + that start with `refs/bisect/`, but might later include other + 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 + <> 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 + <>, 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. + +[[def_pull]]pull:: + Pulling a <> means to <> it and + <> it. See also linkgit:git-pull[1]. + +[[def_push]]push:: + Pushing a <> means to get the branch's + <> from a remote <>, + find out if it is an ancestor to the branch's local + head ref, and in that case, putting all + objects, which are <> from the local + head ref, and which are missing from the remote + repository, into the remote + <>, and updating the remote + head ref. If the remote <> is not an + ancestor to the local head, the push fails. + +[[def_reachable]]reachable:: + All of the ancestors of a given <> are said to be + "reachable" from that commit. More + generally, one <> is reachable from + another if we can reach the one from the other by a <> + that follows <> to whatever they tag, + <> to their parents or trees, and + <> to the trees or <> + that they contain. + +[[def_reachability_bitmap]]reachability bitmaps:: + Reachability bitmaps store information about the + <> of a selected set of commits in + a packfile, or a multi-pack index (MIDX), to speed up object search. + The bitmaps are stored in a ".bitmap" file. A repository may have at + most one bitmap file in use. The bitmap file may belong to either one + pack, or the repository's multi-pack index (if it exists). + +[[def_rebase]]rebase:: + To reapply a series of changes from a <> to a + different base, and reset the <> of that branch + to the result. + +[[def_ref]]ref:: + A name that begins with `refs/` (e.g. `refs/heads/master`) + that points to an <> or another + ref (the latter is called a <>). + 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 <>. ++ +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:: + A reflog shows the local "history" of a ref. In other words, + it can tell you what the 3rd last revision in _this_ repository + was, and what was the current state in _this_ repository, + yesterday 9:14pm. See linkgit:git-reflog[1] for details. + +[[def_refspec]]refspec:: + A "refspec" is used by <> and + <> to describe the mapping between remote + <> and local ref. + +[[def_remote]]remote repository:: + A <> which is used to track the same + project but resides somewhere else. To communicate with remotes, + see <> or <>. + +[[def_remote_tracking_branch]]remote-tracking branch:: + A <> that is used to follow changes from another + <>. 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 <>. A remote-tracking + branch should not contain direct modifications or have local + commits made to it. + +[[def_repository]]repository:: + A collection of <> together with an + <> containing all objects + which are <> from the refs, possibly + accompanied by meta data from one or more <>. A + repository can share an object database with other repositories + via <>. + +[[def_resolve]]resolve:: + The action of fixing up manually what a failed automatic + <> left behind. + +[[def_revision]]revision:: + Synonym for <> (the noun). + +[[def_rewind]]rewind:: + To throw away part of the development, i.e. to assign the + <> to an earlier <>. + +[[def_SCM]]SCM:: + Source code management (tool). + +[[def_SHA1]]SHA-1:: + "Secure Hash Algorithm 1"; a cryptographic hash function. + In the context of Git used as a synonym for <>. + +[[def_shallow_clone]]shallow clone:: + Mostly a synonym to <> + but the phrase makes it more explicit that it was created by + running `git clone --depth=...` command. + +[[def_shallow_repository]]shallow repository:: + A shallow <> has an incomplete + history some of whose <> have <> cauterized away (in other + words, Git is told to pretend that these commits do not have the + parents, even though they are recorded in the <>). This is sometimes useful when you are interested only in the + recent history of a project even though the real history recorded in the + upstream is much larger. A shallow repository + is created by giving the `--depth` option to linkgit:git-clone[1], and + its history can be later deepened with linkgit:git-fetch[1]. + +[[def_stash]]stash entry:: + An <> used to temporarily store the contents of a + <> working directory and the index for future reuse. + +[[def_submodule]]submodule:: + A <> that holds the history of a + separate project inside another repository (the latter of + which is called <>). + +[[def_superproject]]superproject:: + A <> that references repositories + of other projects in its working tree as <>. + The superproject knows about the names of (but does not hold + copies of) commit objects of the contained submodules. + +[[def_symref]]symref:: + 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 + references are manipulated with the linkgit:git-symbolic-ref[1] + command. + +[[def_tag]]tag:: + A <> under `refs/tags/` namespace that points to an + object of an arbitrary type (typically a tag points to either a + <> or a <>). + In contrast to a <>, a tag is not updated by + the `commit` command. A Git tag has nothing to do with a Lisp + tag (which would be called an <> + in Git's context). A tag is most typically used to mark a particular + point in the commit ancestry <>. + +[[def_tag_object]]tag object:: + An <> containing a <> pointing to + another object, which can contain a message just like a + <>. It can also contain a (PGP) + signature, in which case it is called a "signed tag object". + +[[def_topic_branch]]topic branch:: + A regular Git <> 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 + that each contain very well defined concepts or small incremental yet + related changes. + +[[def_tree]]tree:: + Either a <>, or a <> together with the dependent <> and tree objects + (i.e. a stored representation of a working tree). + +[[def_tree_object]]tree object:: + An <> containing a list of file names and modes along + with refs to the associated blob and/or tree objects. A + <> is equivalent to a <>. + +[[def_tree-ish]]tree-ish (also treeish):: + A <> or an <> + that can be recursively dereferenced to a tree object. + Dereferencing a <> yields the + tree object corresponding to the <>'s + top <>. + The following are all tree-ishes: + a <>, + a tree object, + a <> 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:: + An <> which contains unmerged + <>. + +[[def_unreachable_object]]unreachable object:: + An <> which is not <> from a + <>, <>, or any other reference. + +[[def_upstream_branch]]upstream branch:: + The default <> that is merged into the branch in + question (or the branch in question is rebased onto). It is configured + via branch..remote and branch..merge. If the upstream branch + of 'A' is 'origin/B' sometimes we say "'A' is tracking 'origin/B'". + +[[def_working_tree]]working tree:: + The tree of actual checked out files. The working tree normally + contains the contents of the <> commit's tree, + plus any local changes that you have made but not yet committed. + +[[def_worktree]]worktree:: + A repository can have zero (i.e. bare repository) or one or + more worktrees attached to it. One "worktree" consists of a + "working tree" and repository metadata, most of which are + shared among other worktrees of a single repository, and + some of which are maintained separately per worktree + (e.g. the index, HEAD and pseudorefs like MERGE_HEAD, + per-worktree refs and per-worktree configuration file). -- cgit v1.2.3