Documentation/git.txt

   1 git(7)
   2 ======
   3 v0.1, May 2005
   4
   5 NAME
   6 ----
   7 git - the stupid content tracker
   8
   9
  10 SYNOPSIS
  11 --------
  12 'git-<command>' <args>
  13
  14 DESCRIPTION
  15 -----------
  16
  17 This is reference information for the core git commands.
  18
  19 The link:README[] contains much useful definition and clarification
  20 info - read that first.  And of the commands, I suggest reading
  21 'git-update-cache' and 'git-read-tree' first - I wish I had!
  22
  23 David Greaves <david@dgreaves.com>
  24 08/05/05
  25
  26 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
  27 reflect recent changes.
  28
  29 Commands Overview
  30 -----------------
  31 The git commands can helpfully be split into those that manipulate
  32 the repository, the cache and the working fileset and those that
  33 interrogate and compare them.
  34
  35 There are also some ancilliary programs that can be viewed as useful
  36 aids for using the core commands but which are unlikely to be used by
  37 SCMs layered over git.
  38
  39 Manipulation commands
  40 ~~~~~~~~~~~~~~~~~~~~~
  41 link:git-checkout-cache.html[git-checkout-cache]::
  42         Copy files from the cache to the working directory
  43
  44 link:git-commit-tree.html[git-commit-tree]::
  45         Creates a new commit object
  46
  47 link:git-init-db.html[git-init-db]::
  48         Creates an empty git object database
  49
  50 link:git-merge-base.html[git-merge-base]::
  51         Finds as good a common ancestor as possible for a merge
  52
  53 link:git-mktag.html[git-mktag]::
  54         Creates a tag object
  55
  56 link:git-read-tree.html[git-read-tree]::
  57         Reads tree information into the directory cache
  58
  59 link:git-update-cache.html[git-update-cache]::
  60         Modifies the index or directory cache
  61
  62 link:git-write-blob.html[git-write-blob]::
  63         Creates a blob from a file
  64
  65 link:git-write-tree.html[git-write-tree]::
  66         Creates a tree from the current cache
  67
  68 Interrogation commands
  69 ~~~~~~~~~~~~~~~~~~~~~~
  70 link:git-cat-file.html[git-cat-file]::
  71         Provide content or type information for repository objects
  72
  73 link:git-check-files.html[git-check-files]::
  74         Verify a list of files are up-to-date
  75
  76 link:git-diff-cache.html[git-diff-cache]::
  77         Compares content and mode of blobs between the cache and repository
  78
  79 link:git-diff-files.html[git-diff-files]::
  80         Compares files in the working tree and the cache
  81
  82 link:git-diff-tree.html[git-diff-tree]::
  83         Compares the content and mode of blobs found via two tree objects
  84
  85 link:git-export.html[git-export]::
  86         Exports each commit and a diff against each of its parents
  87
  88 link:git-fsck-cache.html[git-fsck-cache]::
  89         Verifies the connectivity and validity of the objects in the database
  90
  91 link:git-ls-files.html[git-ls-files]::
  92         Information about files in the cache/working directory
  93
  94 link:git-ls-tree.html[git-ls-tree]::
  95         Displays a tree object in human readable form
  96
  97 link:git-merge-cache.html[git-merge-cache]::
  98         Runs a merge for files needing merging
  99
 100 link:git-rev-list.html[git-rev-list]::
 101         Lists commit objects in reverse chronological order
 102
 103 link:git-rev-tree.html[git-rev-tree]::
 104         Provides the revision tree for one or more commits
 105
 106 link:git-tar-tree.html[git-tar-tree]::
 107         Creates a tar archive of the files in the named tree
 108
 109 link:git-unpack-file.html[git-unpack-file]::
 110         Creates a temporary file with a blob's contents
 111
 112 The interrogate commands may create files - and you can force them to
 113 touch the working file set - but in general they don't
 114
 115
 116 Ancilliary Commands
 117 -------------------
 118 Manipulators:
 119
 120 link:git-apply-patch-script.html[git-apply-patch-script]::
 121         Sample script to apply the diffs from git-diff-*
 122
 123 link:git-convert-cache.html[git-convert-cache]::
 124         Converts old-style GIT repository
 125
 126 link:git-http-pull.html[git-http-pull]::
 127         Downloads a remote GIT repository via HTTP
 128
 129 link:git-local-pull.html[git-local-pull]::
 130         Duplicates another GIT repository on a local system
 131
 132 link:git-merge-one-file-script.html[git-merge-one-file-script]::
 133         The standard helper program to use with "git-merge-cache"
 134
 135 link:git-pull-script.html[git-pull-script]::
 136         Script used by Linus to pull and merge a remote repository
 137
 138 link:git-prune-script.html[git-prune-script]::
 139         Prunes all unreachable objects from the object database
 140
 141 link:git-resolve-script.html[git-resolve-script]::
 142         Script used to merge two trees
 143
 144 link:git-tag-script.html[git-tag-script]::
 145         An example script to create a tag object signed with GPG
 146
 147 link:git-rpull.html[git-rpull]::
 148         Pulls from a remote repository over ssh connection
 149
 150 Interogators:
 151
 152 link:git-diff-helper.html[git-diff-helper]::
 153         Generates patch format output for git-diff-*
 154
 155 link:git-rpush.html[git-rpush]::
 156         Helper "server-side" program used by git-rpull
 157
 158
 159
 160 Terminology
 161 -----------
 162 see README for description
 163
 164 Identifier terminology
 165 ----------------------
 166 <object>::
 167         Indicates any object sha1 identifier
 168
 169 <blob>::
 170         Indicates a blob object sha1 identifier
 171
 172 <tree>::
 173         Indicates a tree object sha1 identifier
 174
 175 <commit>::
 176         Indicates a commit object sha1 identifier
 177
 178 <tree-ish>::
 179         Indicates a tree, commit or tag object sha1 identifier.
 180         A command that takes a <tree-ish> argument ultimately
 181         wants to operate on a <tree> object but automatically
 182         dereferences <commit> and <tag> that points at a
 183         <tree>.
 184
 185 <type>::
 186         Indicates that an object type is required.
 187         Currently one of: blob/tree/commit/tag
 188
 189 <file>::
 190         Indicates a filename - always relative to the root of
 191         the tree structure GIT_INDEX_FILE describes.
 192
 193 Symbolic Identifiers
 194 --------------------
 195 Any git comand accepting any <object> can also use the following symbolic notation:
 196
 197 HEAD::
 198         indicates the head of the repository (ie the contents of `$GIT_DIR/HEAD`)
 199 <tag>::
 200         a valid tag 'name'+
 201         (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
 202 <head>::
 203         a valid head 'name'+
 204         (ie the contents of `$GIT_DIR/refs/heads/<head>`)
 205 <snap>::
 206         a valid snapshot 'name'+
 207         (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
 208
 209
 210 File/Directory Structure
 211 ------------------------
 212 The git-core manipulates the following areas in the directory:
 213
 214  .git/         The base (overridden with $GIT_DIR)
 215    objects/    The object base (overridden with $GIT_OBJECT_DIRECTORY)
 216      ??/       'First 2 chars of object' directories
 217
 218 It can interrogate (but never updates) the following areas:
 219
 220    refs/       Directories containing symbolic names for objects
 221                (each file contains the hex SHA1 + newline)
 222      heads/    Commits which are heads of various sorts
 223      tags/     Tags, by the tag name (or some local renaming of it)
 224      snap/     ????
 225    ...         Everything else isn't shared
 226    HEAD        Symlink to refs/heads/<something>
 227
 228 Higher level SCMs may provide and manage additional information in the
 229 GIT_DIR.
 230
 231 Terminology
 232 -----------
 233 Each line contains terms used interchangeably
 234
 235  object database, .git directory
 236  directory cache, index
 237  id, sha1, sha1-id, sha1 hash
 238  type, tag
 239  blob, blob object
 240  tree, tree object
 241  commit, commit object
 242  parent
 243  root object
 244  changeset
 245
 246
 247 Environment Variables
 248 ---------------------
 249 Various git commands use the following environment variables:
 250
 251 The git Repository
 252 ~~~~~~~~~~~~~~~~~~
 253 These environment variables apply to 'all' core git commands. Nb: it
 254 is worth noting that they may be used/overridden by SCMS sitting above
 255 git so take care if using Cogito etc
 256
 257 'GIT_INDEX_FILE'::
 258         This environment allows the specification of an alternate
 259         cache/index file. If not specified, the default of
 260         `$GIT_DIR/index` is used.
 261
 262 'GIT_OBJECT_DIRECTORY'::
 263         If the object storage directory is specified via this
 264         environment variable then the sha1 directories are created
 265         underneath - otherwise the default `$GIT_DIR/objects`
 266         directory is used.
 267
 268 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 269         Due to the immutable nature of git objects, old objects can be
 270         archived into shared, read-only directories. This variable
 271         specifies a ":" seperated list of git object directories which
 272         can be used to search for git objects. New objects will not be
 273         written to these directories.
 274
 275 'GIT_DIR'::
 276         If the 'GIT_DIR' environment variable is set then it specifies
 277         a path to use instead of `./.git` for the base of the
 278         repository.
 279
 280 git Commits
 281 ~~~~~~~~~~~
 282 'GIT_AUTHOR_NAME'::
 283 'GIT_AUTHOR_EMAIL'::
 284 'GIT_AUTHOR_DATE'::
 285 'GIT_COMMITTER_NAME'::
 286 'GIT_COMMITTER_EMAIL'::
 287         see link:git-commit-tree.html[git-commit-tree]
 288
 289 git Diffs
 290 ~~~~~~~~~
 291 'GIT_DIFF_OPTS'::
 292 'GIT_EXTERNAL_DIFF'::
 293         see the "generating patches" section in :
 294         link:git-diff-cache.html[git-diff-cache];
 295         link:git-diff-files.html[git-diff-files];
 296         link:git-diff-tree.html[git-diff-tree]
 297
 298 Author
 299 ------
 300 Written by Linus Torvalds <torvalds@osdl.org>
 301
 302 Documentation
 303 --------------
 304 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 305
 306 GIT
 307 ---
 308 Part of the link:git.html[git] suite
 309