Documentation/glossary.txt

   1 GIT Glossary
   2 ============
   3
   4 [[def_alternate_object_database]]alternate object database::
   5         Via the alternates mechanism, a <<def_repository,repository>> can
   6         inherit part of its <<def_object_database,object database>> from another
   7         <<def_object_database,object database>>, which is called "alternate".
   8
   9 [[def_bare_repository]]bare repository::
  10         A <<def_bare_repository,bare repository>> is normally an appropriately
  11         named <<def_directory,directory>> with a `.git` suffix that does not
  12         have a locally checked-out copy of any of the files under
  13         <<def_revision,revision>> control. That is, all of the `git`
  14         administrative and control files that would normally be present in the
  15         hidden `.git` sub-directory are directly present in the
  16         `repository.git` directory instead,
  17         and no other files are present and checked out. Usually publishers of
  18         public repositories make bare repositories available.
  19
  20 [[def_blob_object]]blob object::
  21         Untyped <<def_object,object>>, e.g. the contents of a file.
  22
  23 [[def_branch]]branch::
  24         A non-cyclical graph of revisions, i.e. the complete history of a
  25         particular <<def_revision,revision>>, which is called the
  26         branch <<def_head,head>>. The heads
  27         are stored in `$GIT_DIR/refs/heads/`.
  28
  29 [[def_cache]]cache::
  30         Obsolete for: <<def_index,index>>.
  31
  32 [[def_chain]]chain::
  33         A list of objects, where each <<def_object,object>> in the list contains
  34         a reference to its successor (for example, the successor of a
  35         <<def_commit,commit>> could be one of its parents).
  36
  37 [[def_changeset]]changeset::
  38         BitKeeper/cvsps speak for "<<def_commit,commit>>". Since git does not
  39         store changes, but states, it really does not make sense to use the term
  40         "changesets" with git.
  41
  42 [[def_checkout]]checkout::
  43         The action of updating the <<def_working_tree,working tree>> to a
  44         <<def_revision,revision>> which was stored in the
  45         <<def_object_database,object database>>.
  46
  47 [[def_cherry-picking]]cherry-picking::
  48         In <<def_SCM,SCM>> jargon, "cherry pick" means to choose a subset of
  49         changes out of a series of changes (typically commits) and record them
  50         as a new series of changes on top of different codebase. In GIT, this is
  51         performed by "git cherry-pick" command to extract the change introduced
  52         by an existing <<def_commit,commit>> and to record it based on the tip
  53         of the current <<def_branch,branch>> as a new <<def_commit,commit>>.
  54
  55 [[def_clean]]clean::
  56         A <<def_working_tree,working tree>> is <<def_clean,clean>>, if it
  57         corresponds to the <<def_revision,revision>> referenced by the current
  58         <<def_head,head>>. Also see "<<def_dirty,dirty>>".
  59
  60 [[def_commit]]commit::
  61         As a verb: The action of storing the current state of the
  62         <<def_index,index>> in the <<def_object_database,object database>>. The
  63         result is a <<def_revision,revision>>. As a noun: Short hand for
  64         <<def_commit_object,commit object>>.
  65
  66 [[def_commit_object]]commit object::
  67         An <<def_object,object>> which contains the information about a
  68         particular <<def_revision,revision>>, such as parents, committer,
  69         author, date and the <<def_tree_object,tree object>> which corresponds
  70         to the top <<def_directory,directory>> of the stored
  71         <<def_revision,revision>>.
  72
  73 [[def_core_git]]core git::
  74         Fundamental data structures and utilities of git. Exposes only limited
  75         source code management tools.
  76
  77 [[def_DAG]]DAG::
  78         Directed acyclic graph. The <<def_commit,commit>> objects form a
  79         directed acyclic graph, because they have parents (directed), and the
  80         graph of <<def_commit,commit>> objects is acyclic (there is no
  81         <<def_chain,chain>> which begins and ends with the same
  82         <<def_object,object>>).
  83
  84 [[def_dangling_object]]dangling object::
  85         An <<def_unreachable_object,unreachable object>> which is not
  86         <<def_reachable,reachable>> even from other unreachable objects; a
  87         <<def_dangling_object,dangling object>> has no references to it from any
  88         reference or <<def_object,object>> in the <<def_repository,repository>>.
  89
  90 [[def_dircache]]dircache::
  91         You are *waaaaay* behind.
  92
  93 [[def_directory]]directory::
  94         The list you get with "ls" :-)
  95
  96 [[def_dirty]]dirty::
  97         A <<def_working_tree,working tree>> is said to be <<def_dirty,dirty>> if
  98         it contains modifications which have not been committed to the current
  99         <<def_branch,branch>>.
 100
 101 [[def_ent]]ent::
 102         Favorite synonym to "<<def_tree-ish,tree-ish>>" by some total geeks. See
 103         `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth
 104         explanation. Avoid this term, not to confuse people.
 105
 106 [[def_fast_forward]]fast forward::
 107         A fast-forward is a special type of <<def_merge,merge>> where you have a
 108         <<def_revision,revision>> and you are "merging" another
 109         <<def_branch,branch>>'s changes that happen to be a descendant of what
 110         you have. In such these cases, you do not make a new <<def_merge,merge>>
 111         <<def_commit,commit>> but instead just update to his
 112         <<def_revision,revision>>. This will happen frequently on a
 113         <<def_tracking_branch,tracking branch>> of a remote
 114         <<def_repository,repository>>.
 115
 116 [[def_fetch]]fetch::
 117         Fetching a <<def_branch,branch>> means to get the
 118         <<def_branch,branch>>'s <<def_head_ref,head ref>> from a remote
 119         <<def_repository,repository>>, to find out which objects are missing
 120         from the local <<def_object_database,object database>>, and to get them,
 121         too.
 122
 123 [[def_file_system]]file system::
 124         Linus Torvalds originally designed git to be a user space file system,
 125         i.e. the infrastructure to hold files and directories. That ensured the
 126         efficiency and speed of git.
 127
 128 [[def_git_archive]]git archive::
 129         Synonym for <<def_repository,repository>> (for arch people).
 130
 131 [[def_grafts]]grafts::
 132         Grafts enables two otherwise different lines of development to be joined
 133         together by recording fake ancestry information for commits. This way
 134         you can make git pretend the set of parents a <<def_commit,commit>> has
 135         is different from what was recorded when the <<def_commit,commit>> was
 136         created. Configured via the `.git/info/grafts` file.
 137
 138 [[def_hash]]hash::
 139         In git's context, synonym to <<def_object_name,object name>>.
 140
 141 [[def_head]]head::
 142         The top of a <<def_branch,branch>>. It contains a <<def_ref,ref>> to the
 143         corresponding <<def_commit_object,commit object>>.
 144
 145 [[def_head_ref]]head ref::
 146         A <<def_ref,ref>> pointing to a <<def_head,head>>. Often, this is
 147         abbreviated to "<<def_head,head>>". Head refs are stored in
 148         `$GIT_DIR/refs/heads/`.
 149
 150 [[def_hook]]hook::
 151         During the normal execution of several git commands, call-outs are made
 152         to optional scripts that allow a developer to add functionality or
 153         checking. Typically, the hooks allow for a command to be pre-verified
 154         and potentially aborted, and allow for a post-notification after the
 155         operation is done. The <<def_hook,hook>> scripts are found in the
 156         `$GIT_DIR/hooks/` <<def_directory,directory>>, and are enabled by simply
 157         making them executable.
 158
 159 [[def_index]]index::
 160         A collection of files with stat information, whose contents are stored
 161         as objects. The <<def_index,index>> is a stored version of your working
 162         <<def_tree,tree>>. Truth be told, it can also contain a second, and even
 163         a third version of a <<def_working_tree,working tree>>, which are used
 164         when merging.
 165
 166 [[def_index_entry]]index entry::
 167         The information regarding a particular file, stored in the
 168         <<def_index,index>>. An <<def_index_entry,index entry>> can be unmerged,
 169         if a <<def_merge,merge>> was started, but not yet finished (i.e. if the
 170         <<def_index,index>> contains multiple versions of that file).
 171
 172 [[def_master]]master::
 173         The default development <<def_branch,branch>>. Whenever you create a git
 174         <<def_repository,repository>>, a <<def_branch,branch>> named
 175         "<<def_master,master>>" is created, and becomes the active
 176         <<def_branch,branch>>. In most cases, this contains the local
 177         development, though that is purely conventional and not required.
 178
 179 [[def_merge]]merge::
 180         To <<def_merge,merge>> branches means to try to accumulate the changes
 181         since a common ancestor and apply them to the first
 182         <<def_branch,branch>>. An automatic <<def_merge,merge>> uses heuristics
 183         to accomplish that. Evidently, an automatic <<def_merge,merge>> can
 184         fail.
 185
 186 [[def_object]]object::
 187         The unit of storage in git. It is uniquely identified by the
 188         <<def_SHA1,SHA1>> of its contents. Consequently, an
 189         <<def_object,object>> can not be changed.
 190
 191 [[def_object_database]]object database::
 192         Stores a set of "objects", and an individual <<def_object,object>> is
 193         identified by its <<def_object_name,object name>>. The objects usually
 194         live in `$GIT_DIR/objects/`.
 195
 196 [[def_object_identifier]]object identifier::
 197         Synonym for <<def_object_name,object name>>.
 198
 199 [[def_object_name]]object name::
 200         The unique identifier of an <<def_object,object>>. The <<def_hash,hash>>
 201         of the <<def_object,object>>'s contents using the Secure Hash Algorithm
 202         1 and usually represented by the 40 character hexadecimal encoding of
 203         the <<def_hash,hash>> of the <<def_object,object>> (possibly followed by
 204         a white space).
 205
 206 [[def_object_type]]object type::
 207         One of the identifiers
 208         "<<def_commit,commit>>","<<def_tree,tree>>","<<def_tag,tag>>" or "<<def_blob_object,blob>>"
 209         describing the type of an <<def_object,object>>.
 210
 211 [[def_octopus]]octopus::
 212         To <<def_merge,merge>> more than two branches. Also denotes an
 213         intelligent predator.
 214
 215 [[def_origin]]origin::
 216         The default upstream <<def_repository,repository>>. Most projects have
 217         at least one upstream project which they track. By default
 218         '<<def_origin,origin>>' is used for that purpose. New upstream updates
 219         will be fetched into remote tracking branches named
 220         origin/name-of-upstream-branch, which you can see using
 221         "git <<def_branch,branch>> -r".
 222
 223 [[def_pack]]pack::
 224         A set of objects which have been compressed into one file (to save space
 225         or to transmit them efficiently).
 226
 227 [[def_pack_index]]pack index::
 228         The list of identifiers, and other information, of the objects in a
 229         <<def_pack,pack>>, to assist in efficiently accessing the contents of a
 230         <<def_pack,pack>>.
 231
 232 [[def_parent]]parent::
 233         A <<def_commit_object,commit object>> contains a (possibly empty) list
 234         of the logical predecessor(s) in the line of development, i.e. its
 235         parents.
 236
 237 [[def_pickaxe]]pickaxe::
 238         The term <<def_pickaxe,pickaxe>> refers to an option to the diffcore
 239         routines that help select changes that add or delete a given text
 240         string. With the --pickaxe-all option, it can be used to view the full
 241         <<def_changeset,changeset>> that introduced or removed, say, a
 242         particular line of text. See gitlink:git-diff[1].
 243
 244 [[def_plumbing]]plumbing::
 245         Cute name for <<def_core_git,core git>>.
 246
 247 [[def_porcelain]]porcelain::
 248         Cute name for programs and program suites depending on
 249         <<def_core_git,core git>>, presenting a high level access to
 250         <<def_core_git,core git>>. Porcelains expose more of a <<def_SCM,SCM>>
 251         interface than the <<def_plumbing,plumbing>>.
 252
 253 [[def_pull]]pull::
 254         Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and
 255         <<def_merge,merge>> it.
 256
 257 [[def_push]]push::
 258         Pushing a <<def_branch,branch>> means to get the <<def_branch,branch>>'s
 259         <<def_head_ref,head ref>> from a remote <<def_repository,repository>>,
 260         find out if it is an ancestor to the <<def_branch,branch>>'s local
 261         <<def_head_ref,head ref>> is a direct, and in that case, putting all
 262         objects, which are <<def_reachable,reachable>> from the local
 263         <<def_head_ref,head ref>>, and which are missing from the remote
 264         <<def_repository,repository>>, into the remote
 265         <<def_object_database,object database>>, and updating the remote
 266         <<def_head_ref,head ref>>. If the remote <<def_head,head>> is not an
 267         ancestor to the local <<def_head,head>>, the <<def_push,push>> fails.
 268
 269 [[def_reachable]]reachable::
 270         All of the ancestors of a given <<def_commit,commit>> are said to be
 271         <<def_reachable,reachable>> from that <<def_commit,commit>>. More
 272         generally, one <<def_object,object>> is <<def_reachable,reachable>> from
 273         another if we can reach the one from the other by a <<def_chain,chain>>
 274         that follows <<def_tag,tags>> to whatever they tag,
 275         <<def_commit_object,commits>> to their parents or trees, and
 276         <<def_tree_object,trees>> to the trees or <<def_blob_object,blobs>>
 277         that they contain.
 278
 279 [[def_rebase]]rebase::
 280         To reapply a series of changes from a <<def_branch,branch>> to a
 281         different base, and reset the <<def_head,head>> of that branch
 282         to the result.
 283
 284 [[def_ref]]ref::
 285         A 40-byte hex representation of a <<def_SHA1,SHA1>> or a name that
 286         denotes a particular <<def_object,object>>. These may be stored in
 287         `$GIT_DIR/refs/`.
 288
 289 [[def_refspec]]refspec::
 290         A <<def_refspec,refspec>> is used by <<def_fetch,fetch>> and
 291         <<def_push,push>> to describe the mapping between remote <<def_ref,ref>>
 292         and local <<def_ref,ref>>. They are combined with a colon in the format
 293         <src>:<dst>, preceded by an optional plus sign, +. For example: `git
 294         fetch $URL refs/heads/master:refs/heads/origin` means
 295         "grab the master <<def_branch,branch>> <<def_head,head>>
 296         from the $URL and store it as my origin
 297         <<def_branch,branch>> <<def_head,head>>". And `git <<def_push,push>>
 298         $URL refs/heads/master:refs/heads/to-upstream` means
 299         "publish my master <<def_branch,branch>>
 300         <<def_head,head>> as to-upstream <<def_branch,branch>> at $URL". See
 301         also gitlink:git-push[1]
 302
 303 [[def_repository]]repository::
 304         A collection of refs together with an <<def_object_database,object
 305         database>> containing all objects which are <<def_reachable,reachable>>
 306         from the refs, possibly accompanied by meta data from one or more
 307         porcelains. A <<def_repository,repository>> can share an
 308         <<def_object_database,object database>> with other repositories.
 309
 310 [[def_resolve]]resolve::
 311         The action of fixing up manually what a failed automatic
 312         <<def_merge,merge>> left behind.
 313
 314 [[def_revision]]revision::
 315         A particular state of files and directories which was stored in the
 316         <<def_object_database,object database>>. It is referenced by a
 317         <<def_commit_object,commit object>>.
 318
 319 [[def_rewind]]rewind::
 320         To throw away part of the development, i.e. to assign the
 321         <<def_head,head>> to an earlier <<def_revision,revision>>.
 322
 323 [[def_SCM]]SCM::
 324         Source code management (tool).
 325
 326 [[def_SHA1]]SHA1::
 327         Synonym for <<def_object_name,object name>>.
 328
 329 [[def_shallow_repository]]shallow repository::
 330         A <<def_shallow_repository,shallow repository>> has an incomplete
 331         history some of whose commits have parents cauterized away (in other
 332         words, git is told to pretend that these commits do not have the
 333         parents, even though they are recorded in the <<def_commit_object,commit
 334         object>>). This is sometimes useful when you are interested only in the
 335         recent history of a project even though the real history recorded in the
 336         upstream is much larger. A <<def_shallow_repository,shallow repository>>
 337         is created by giving the `--depth` option to gitlink:git-clone[1], and
 338         its history can be later deepened with gitlink:git-fetch[1].
 339
 340 [[def_symref]]symref::
 341         Symbolic reference: instead of containing the <<def_SHA1,SHA1>> id
 342         itself, it is of the format 'ref: refs/some/thing' and when
 343         referenced, it recursively dereferences to this reference. 'HEAD' is a
 344         prime example of a <<def_symref,symref>>. Symbolic references are
 345         manipulated with the gitlink:git-symbolic-ref[1] command.
 346
 347 [[def_tag]]tag::
 348         A <<def_ref,ref>> pointing to a <<def_tag,tag>> or
 349         <<def_commit_object,commit object>>. In contrast to a <<def_head,head>>,
 350         a tag is not changed by a <<def_commit,commit>>. Tags (not
 351         <<def_tag_object,tag objects>>) are stored in `$GIT_DIR/refs/tags/`. A
 352         git tag has nothing to do with a Lisp tag (which would be
 353         called an <<def_object_type,object type>> in git's context). A
 354         tag is most typically used to mark a particular point in the
 355         <<def_commit,commit>> ancestry <<def_chain,chain>>.
 356
 357 [[def_tag_object]]tag object::
 358         An <<def_object,object>> containing a <<def_ref,ref>> pointing to
 359         another <<def_object,object>>, which can contain a message just like a
 360         <<def_commit_object,commit object>>. It can also contain a (PGP)
 361         signature, in which case it is called a "signed <<def_tag_object,tag
 362         object>>".
 363
 364 [[def_topic_branch]]topic branch::
 365         A regular git <<def_branch,branch>> that is used by a developer to
 366         identify a conceptual line of development. Since branches are very easy
 367         and inexpensive, it is often desirable to have several small branches
 368         that each contain very well defined concepts or small incremental yet
 369         related changes.
 370
 371 [[def_tracking_branch]]tracking branch::
 372         A regular git <<def_branch,branch>> that is used to follow changes from
 373         another <<def_repository,repository>>. A <<def_tracking_branch,tracking
 374         branch>> should not contain direct modifications or have local commits
 375         made to it. A <<def_tracking_branch,tracking branch>> can usually be
 376         identified as the right-hand-side <<def_ref,ref>> in a Pull:
 377         <<def_refspec,refspec>>.
 378
 379 [[def_tree]]tree::
 380         Either a <<def_working_tree,working tree>>, or a <<def_tree_object,tree
 381         object>> together with the dependent blob and <<def_tree,tree>> objects
 382         (i.e. a stored representation of a <<def_working_tree,working tree>>).
 383
 384 [[def_tree_object]]tree object::
 385         An <<def_object,object>> containing a list of file names and modes along
 386         with refs to the associated blob and/or tree objects. A
 387         <<def_tree,tree>> is equivalent to a <<def_directory,directory>>.
 388
 389 [[def_tree-ish]]tree-ish::
 390         A <<def_ref,ref>> pointing to either a <<def_commit_object,commit
 391         object>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag
 392         object>> pointing to a <<def_tag,tag>> or <<def_commit,commit>> or
 393         <<def_tree_object,tree object>>.
 394
 395 [[def_unmerged_index]]unmerged index::
 396         An <<def_index,index>> which contains unmerged
 397         <<def_index_entry,index entries>>.
 398
 399 [[def_unreachable_object]]unreachable object::
 400         An <<def_object,object>> which is not <<def_reachable,reachable>> from a
 401         <<def_branch,branch>>, <<def_tag,tag>>, or any other reference.
 402
 403 [[def_working_tree]]working tree::
 404         The set of files and directories currently being worked on, i.e. you can
 405         work in your <<def_working_tree,working tree>> without using git at all.