1git(7) 2====== 3 4NAME 5---- 6git - the stupid content tracker 7 8 9SYNOPSIS 10-------- 11'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS] 12 13DESCRIPTION 14----------- 15'git' is both a program and a directory content tracker system. 16The program 'git' is just a wrapper to reach the core git programs 17(or a potty if you like, as it's not exactly porcelain but still 18brings your stuff to the plumbing). 19 20OPTIONS 21------- 22--version:: 23 prints the git suite version that the 'git' program came from. 24 25--help:: 26 prints the synopsis and a list of available commands. 27 If a git command is named this option will bring up the 28 man-page for that command. 29 30--exec-path:: 31 path to wherever your core git programs are installed. 32 This can also be controlled by setting the GIT_EXEC_PATH 33 environment variable. If no path is given 'git' will print 34 the current setting and then exit. 35 36CORE GIT COMMANDS 37----------------- 38Before reading this cover to cover, you may want to take a look 39at the link:tutorial.html[tutorial] document. 40 41The <<Discussion>> section below contains much useful definition and 42clarification info - read that first. And of the commands, I suggest 43reading gitlink:git-update-index[1] and 44gitlink:git-read-tree[1] first - I wish I had! 45 46If you are migrating from CVS, link:cvs-migration.html[cvs migration] 47document may be helpful after you finish the tutorial. 48 49After you get the general feel from the tutorial and this 50overview page, you may want to take a look at the 51link:howto-index.html[howto] documents. 52 53 54David Greaves <david@dgreaves.com> 5508/05/05 56 57Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to 58reflect recent changes. 59 60Commands Overview 61----------------- 62The git commands can helpfully be split into those that manipulate 63the repository, the index and the working fileset, those that 64interrogate and compare them, and those that moves objects and 65references between repositories. 66 67In addition, git itself comes with a spartan set of porcelain 68commands. They are usable but are not meant to compete with real 69Porcelains. 70 71There are also some ancillary programs that can be viewed as useful 72aids for using the core commands but which are unlikely to be used by 73SCMs layered over git. 74 75Manipulation commands 76~~~~~~~~~~~~~~~~~~~~~ 77gitlink:git-apply[1]:: 78 Reads a "diff -up1" or git generated patch file and 79 applies it to the working tree. 80 81gitlink:git-checkout-index[1]:: 82 Copy files from the index to the working directory 83 84gitlink:git-commit-tree[1]:: 85 Creates a new commit object 86 87gitlink:git-hash-object[1]:: 88 Computes the object ID from a file. 89 90gitlink:git-index-pack[1]:: 91 Build pack index file for an existing packed archive. 92 93gitlink:git-init-db[1]:: 94 Creates an empty git object database 95 96gitlink:git-merge-index[1]:: 97 Runs a merge for files needing merging 98 99gitlink:git-mktag[1]:: 100 Creates a tag object 101 102gitlink:git-pack-objects[1]:: 103 Creates a packed archive of objects. 104 105gitlink:git-prune-packed[1]:: 106 Remove extra objects that are already in pack files. 107 108gitlink:git-read-tree[1]:: 109 Reads tree information into the directory index 110 111gitlink:git-unpack-objects[1]:: 112 Unpacks objects out of a packed archive. 113 114gitlink:git-update-index[1]:: 115 Modifies the index or directory cache 116 117gitlink:git-write-tree[1]:: 118 Creates a tree from the current index 119 120 121Interrogation commands 122~~~~~~~~~~~~~~~~~~~~~~ 123 124gitlink:git-cat-file[1]:: 125 Provide content or type information for repository objects 126 127gitlink:git-diff-index[1]:: 128 Compares content and mode of blobs between the index and repository 129 130gitlink:git-diff-files[1]:: 131 Compares files in the working tree and the index 132 133gitlink:git-diff-stages[1]:: 134 Compares two "merge stages" in the index file. 135 136gitlink:git-diff-tree[1]:: 137 Compares the content and mode of blobs found via two tree objects 138 139gitlink:git-fsck-objects[1]:: 140 Verifies the connectivity and validity of the objects in the database 141 142gitlink:git-ls-files[1]:: 143 Information about files in the index/working directory 144 145gitlink:git-ls-tree[1]:: 146 Displays a tree object in human readable form 147 148gitlink:git-merge-base[1]:: 149 Finds as good a common ancestor as possible for a merge 150 151gitlink:git-name-rev[1]:: 152 Find symbolic names for given revs 153 154gitlink:git-rev-list[1]:: 155 Lists commit objects in reverse chronological order 156 157gitlink:git-show-index[1]:: 158 Displays contents of a pack idx file. 159 160gitlink:git-tar-tree[1]:: 161 Creates a tar archive of the files in the named tree 162 163gitlink:git-unpack-file[1]:: 164 Creates a temporary file with a blob's contents 165 166gitlink:git-var[1]:: 167 Displays a git logical variable 168 169gitlink:git-verify-pack[1]:: 170 Validates packed git archive files 171 172The interrogate commands may create files - and you can force them to 173touch the working file set - but in general they don't 174 175 176Synching repositories 177~~~~~~~~~~~~~~~~~~~~~ 178 179gitlink:git-clone-pack[1]:: 180 Clones a repository into the current repository (engine 181 for ssh and local transport) 182 183gitlink:git-fetch-pack[1]:: 184 Updates from a remote repository. 185 186gitlink:git-http-fetch[1]:: 187 Downloads a remote git repository via HTTP 188 189gitlink:git-local-fetch[1]:: 190 Duplicates another git repository on a local system 191 192gitlink:git-peek-remote[1]:: 193 Lists references on a remote repository using upload-pack protocol. 194 195gitlink:git-receive-pack[1]:: 196 Invoked by 'git-send-pack' to receive what is pushed to it. 197 198gitlink:git-send-pack[1]:: 199 Pushes to a remote repository, intelligently. 200 201gitlink:git-shell[1]:: 202 Restricted shell for GIT-only SSH access. 203 204gitlink:git-ssh-fetch[1]:: 205 Pulls from a remote repository over ssh connection 206 207gitlink:git-ssh-upload[1]:: 208 Helper "server-side" program used by git-ssh-fetch 209 210gitlink:git-update-server-info[1]:: 211 Updates auxiliary information on a dumb server to help 212 clients discover references and packs on it. 213 214gitlink:git-upload-pack[1]:: 215 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push 216 what are asked for. 217 218 219Porcelain-ish Commands 220---------------------- 221 222gitlink:git-add[1]:: 223 Add paths to the index file. 224 225gitlink:git-am[1]:: 226 Apply patches from a mailbox, but cooler. 227 228gitlink:git-applymbox[1]:: 229 Apply patches from a mailbox. 230 231gitlink:git-bisect[1]:: 232 Find the change that introduced a bug. 233 234gitlink:git-branch[1]:: 235 Create and Show branches. 236 237gitlink:git-checkout[1]:: 238 Checkout and switch to a branch. 239 240gitlink:git-cherry-pick[1]:: 241 Cherry-pick the effect of an existing commit. 242 243gitlink:git-clone[1]:: 244 Clones a repository into a new directory. 245 246gitlink:git-commit[1]:: 247 Record changes to the repository. 248 249gitlink:git-diff[1]:: 250 Show changes between commits, commit and working tree, etc. 251 252gitlink:git-fetch[1]:: 253 Download from a remote repository via various protocols. 254 255gitlink:git-format-patch[1]:: 256 Prepare patches for e-mail submission. 257 258gitlink:git-grep[1]:: 259 Print lines matching a pattern 260 261gitlink:git-log[1]:: 262 Shows commit logs. 263 264gitlink:git-ls-remote[1]:: 265 Shows references in a remote or local repository. 266 267gitlink:git-merge[1]:: 268 Grand unified merge driver. 269 270gitlink:git-mv[1]:: 271 Move or rename a file, a directory, or a symlink. 272 273gitlink:git-octopus[1]:: 274 Merge more than two commits. 275 276gitlink:git-pull[1]:: 277 Fetch from and merge with a remote repository. 278 279gitlink:git-push[1]:: 280 Update remote refs along with associated objects. 281 282gitlink:git-rebase[1]:: 283 Rebase local commits to new upstream head. 284 285gitlink:git-repack[1]:: 286 Pack unpacked objects in a repository. 287 288gitlink:git-reset[1]:: 289 Reset current HEAD to the specified state. 290 291gitlink:git-resolve[1]:: 292 Merge two commits. 293 294gitlink:git-revert[1]:: 295 Revert an existing commit. 296 297gitlink:git-shortlog[1]:: 298 Summarizes 'git log' output. 299 300gitlink:git-show-branch[1]:: 301 Show branches and their commits. 302 303gitlink:git-status[1]:: 304 Shows the working tree status. 305 306gitlink:git-verify-tag[1]:: 307 Check the GPG signature of tag. 308 309gitlink:git-whatchanged[1]:: 310 Shows commit logs and differences they introduce. 311 312 313Ancillary Commands 314------------------ 315Manipulators: 316 317gitlink:git-applypatch[1]:: 318 Apply one patch extracted from an e-mail. 319 320gitlink:git-archimport[1]:: 321 Import an arch repository into git. 322 323gitlink:git-convert-objects[1]:: 324 Converts old-style git repository 325 326gitlink:git-cvsimport[1]:: 327 Salvage your data out of another SCM people love to hate. 328 329gitlink:git-lost-found[1]:: 330 Recover lost refs that luckily have not yet been pruned. 331 332gitlink:git-merge-one-file[1]:: 333 The standard helper program to use with "git-merge-index" 334 335gitlink:git-prune[1]:: 336 Prunes all unreachable objects from the object database 337 338gitlink:git-relink[1]:: 339 Hardlink common objects in local repositories. 340 341gitlink:git-svnimport[1]:: 342 Import a SVN repository into git. 343 344gitlink:git-sh-setup[1]:: 345 Common git shell script setup code. 346 347gitlink:git-symbolic-ref[1]:: 348 Read and modify symbolic refs 349 350gitlink:git-tag[1]:: 351 An example script to create a tag object signed with GPG 352 353gitlink:git-update-ref[1]:: 354 Update the object name stored in a ref safely. 355 356 357Interrogators: 358 359gitlink:git-check-ref-format[1]:: 360 Make sure ref name is well formed. 361 362gitlink:git-cherry[1]:: 363 Find commits not merged upstream. 364 365gitlink:git-count-objects[1]:: 366 Count unpacked number of objects and their disk consumption. 367 368gitlink:git-daemon[1]:: 369 A really simple server for git repositories. 370 371gitlink:git-get-tar-commit-id[1]:: 372 Extract commit ID from an archive created using git-tar-tree. 373 374gitlink:git-mailinfo[1]:: 375 Extracts patch from a single e-mail message. 376 377gitlink:git-mailsplit[1]:: 378 git-mailsplit. 379 380gitlink:git-patch-id[1]:: 381 Compute unique ID for a patch. 382 383gitlink:git-parse-remote[1]:: 384 Routines to help parsing $GIT_DIR/remotes/ 385 386gitlink:git-request-pull[1]:: 387 git-request-pull. 388 389gitlink:git-rev-parse[1]:: 390 Pick out and massage parameters. 391 392gitlink:git-send-email[1]:: 393 Send patch e-mails out of "format-patch --mbox" output. 394 395gitlink:git-symbolic-refs[1]:: 396 Read and modify symbolic refs. 397 398gitlink:git-stripspace[1]:: 399 Filter out empty lines. 400 401 402Commands not yet documented 403--------------------------- 404 405gitlink:gitk[1]:: 406 gitk. 407 408 409Configuration Mechanism 410----------------------- 411 412Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file 413is used to hold per-repository configuration options. It is a 414simple text file modelled after `.ini` format familiar to some 415people. Here is an example: 416 417------------ 418# 419# This is the config file, and 420# a '#' or ';' character indicates 421# a comment 422# 423 424; core variables 425[core] 426 ; Don't trust file modes 427 filemode = false 428 429; user identity 430[user] 431 name = "Junio C Hamano" 432 email = "junkio@twinsun.com" 433 434------------ 435 436Various commands read from the configuration file and adjust 437their operation accordingly. 438 439 440Identifier Terminology 441---------------------- 442<object>:: 443 Indicates the sha1 identifier for any type of object 444 445<blob>:: 446 Indicates a blob object sha1 identifier 447 448<tree>:: 449 Indicates a tree object sha1 identifier 450 451<commit>:: 452 Indicates a commit object sha1 identifier 453 454<tree-ish>:: 455 Indicates a tree, commit or tag object sha1 identifier. A 456 command that takes a <tree-ish> argument ultimately wants to 457 operate on a <tree> object but automatically dereferences 458 <commit> and <tag> objects that point at a <tree>. 459 460<type>:: 461 Indicates that an object type is required. 462 Currently one of: blob/tree/commit/tag 463 464<file>:: 465 Indicates a filename - always relative to the root of 466 the tree structure GIT_INDEX_FILE describes. 467 468Symbolic Identifiers 469-------------------- 470Any git command accepting any <object> can also use the following 471symbolic notation: 472 473HEAD:: 474 indicates the head of the repository (ie the contents of 475 `$GIT_DIR/HEAD`) 476<tag>:: 477 a valid tag 'name'+ 478 (ie the contents of `$GIT_DIR/refs/tags/<tag>`) 479<head>:: 480 a valid head 'name'+ 481 (ie the contents of `$GIT_DIR/refs/heads/<head>`) 482<snap>:: 483 a valid snapshot 'name'+ 484 (ie the contents of `$GIT_DIR/refs/snap/<snap>`) 485 486 487File/Directory Structure 488------------------------ 489 490Please see link:repository-layout.html[repository layout] document. 491 492Higher level SCMs may provide and manage additional information in the 493GIT_DIR. 494 495 496Terminology 497----------- 498Please see link:glossary.html[glossary] document. 499 500 501Environment Variables 502--------------------- 503Various git commands use the following environment variables: 504 505The git Repository 506~~~~~~~~~~~~~~~~~~ 507These environment variables apply to 'all' core git commands. Nb: it 508is worth noting that they may be used/overridden by SCMS sitting above 509git so take care if using Cogito etc 510 511'GIT_INDEX_FILE':: 512 This environment allows the specification of an alternate 513 index file. If not specified, the default of `$GIT_DIR/index` 514 is used. 515 516'GIT_OBJECT_DIRECTORY':: 517 If the object storage directory is specified via this 518 environment variable then the sha1 directories are created 519 underneath - otherwise the default `$GIT_DIR/objects` 520 directory is used. 521 522'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 523 Due to the immutable nature of git objects, old objects can be 524 archived into shared, read-only directories. This variable 525 specifies a ":" separated list of git object directories which 526 can be used to search for git objects. New objects will not be 527 written to these directories. 528 529'GIT_DIR':: 530 If the 'GIT_DIR' environment variable is set then it specifies 531 a path to use instead of `./.git` for the base of the 532 repository. 533 534git Commits 535~~~~~~~~~~~ 536'GIT_AUTHOR_NAME':: 537'GIT_AUTHOR_EMAIL':: 538'GIT_AUTHOR_DATE':: 539'GIT_COMMITTER_NAME':: 540'GIT_COMMITTER_EMAIL':: 541 see gitlink:git-commit-tree[1] 542 543git Diffs 544~~~~~~~~~ 545'GIT_DIFF_OPTS':: 546'GIT_EXTERNAL_DIFF':: 547 see the "generating patches" section in : 548 gitlink:git-diff-index[1]; 549 gitlink:git-diff-files[1]; 550 gitlink:git-diff-tree[1] 551 552Discussion[[Discussion]] 553------------------------ 554include::../README[] 555 556Authors 557------- 558 git's founding father is Linus Torvalds <torvalds@osdl.org>. 559 The current git nurse is Junio C. Hamano <junkio@cox.net>. 560 The git potty was written by Andres Ericsson <ae@op5.se>. 561 General upbringing is handled by the git-list <git@vger.kernel.org>. 562 563Documentation 564-------------- 565Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 566 567GIT 568--- 569Part of the gitlink:git[7] suite 570