Andrew's git - gitweb.git/blob - Documentation/git.txt

   1git(1)
   2======
   3
   4NAME
   5----
   6git - the stupid content tracker
   7
   8
   9SYNOPSIS
  10--------
  11[verse]
  12'git' [--version] [--help] [-c <name>=<value>]
  13    [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
  14    [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
  15    [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
  16    <command> [<args>]
  17
  18DESCRIPTION
  19-----------
  20Git is a fast, scalable, distributed revision control system with an
  21unusually rich command set that provides both high-level operations
  22and full access to internals.
  23
  24See linkgit:gittutorial[7] to get started, then see
  25link:everyday.html[Everyday Git] for a useful minimum set of
  26commands.  The link:user-manual.html[Git User's Manual] has a more
  27in-depth introduction.
  28
  29After you mastered the basic concepts, you can come back to this
  30page to learn what commands Git offers.  You can learn more about
  31individual Git commands with "git help command".  linkgit:gitcli[7]
  32manual page gives you an overview of the command line command syntax.
  33
  34Formatted and hyperlinked version of the latest Git documentation
  35can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
  36
  37ifdef::stalenotes[]
  38[NOTE]
  39============
  40
  41You are reading the documentation for the latest (possibly
  42unreleased) version of Git, that is available from 'master'
  43branch of the `git.git` repository.
  44Documentation for older releases are available here:
  45
  46* link:v1.8.3.3/git.html[documentation for release 1.8.3.3]
  47
  48* release notes for
  49  link:RelNotes/1.8.3.3.txt[1.8.3.3],
  50  link:RelNotes/1.8.3.2.txt[1.8.3.2],
  51  link:RelNotes/1.8.3.1.txt[1.8.3.1],
  52  link:RelNotes/1.8.3.txt[1.8.3].
  53
  54* link:v1.8.2.3/git.html[documentation for release 1.8.2.3]
  55
  56* release notes for
  57  link:RelNotes/1.8.2.3.txt[1.8.2.3].
  58  link:RelNotes/1.8.2.2.txt[1.8.2.2].
  59  link:RelNotes/1.8.2.1.txt[1.8.2.1].
  60  link:RelNotes/1.8.2.txt[1.8.2].
  61
  62* link:v1.8.1.6/git.html[documentation for release 1.8.1.6]
  63
  64* release notes for
  65  link:RelNotes/1.8.1.6.txt[1.8.1.6],
  66  link:RelNotes/1.8.1.5.txt[1.8.1.5],
  67  link:RelNotes/1.8.1.4.txt[1.8.1.4],
  68  link:RelNotes/1.8.1.3.txt[1.8.1.3],
  69  link:RelNotes/1.8.1.2.txt[1.8.1.2],
  70  link:RelNotes/1.8.1.1.txt[1.8.1.1],
  71  link:RelNotes/1.8.1.txt[1.8.1].
  72
  73* link:v1.8.0.3/git.html[documentation for release 1.8.0.3]
  74
  75* release notes for
  76  link:RelNotes/1.8.0.3.txt[1.8.0.3],
  77  link:RelNotes/1.8.0.2.txt[1.8.0.2],
  78  link:RelNotes/1.8.0.1.txt[1.8.0.1],
  79  link:RelNotes/1.8.0.txt[1.8.0].
  80
  81* link:v1.7.12.4/git.html[documentation for release 1.7.12.4]
  82
  83* release notes for
  84  link:RelNotes/1.7.12.4.txt[1.7.12.4],
  85  link:RelNotes/1.7.12.3.txt[1.7.12.3],
  86  link:RelNotes/1.7.12.2.txt[1.7.12.2],
  87  link:RelNotes/1.7.12.1.txt[1.7.12.1],
  88  link:RelNotes/1.7.12.txt[1.7.12].
  89
  90* link:v1.7.11.7/git.html[documentation for release 1.7.11.7]
  91
  92* release notes for
  93  link:RelNotes/1.7.11.7.txt[1.7.11.7],
  94  link:RelNotes/1.7.11.6.txt[1.7.11.6],
  95  link:RelNotes/1.7.11.5.txt[1.7.11.5],
  96  link:RelNotes/1.7.11.4.txt[1.7.11.4],
  97  link:RelNotes/1.7.11.3.txt[1.7.11.3],
  98  link:RelNotes/1.7.11.2.txt[1.7.11.2],
  99  link:RelNotes/1.7.11.1.txt[1.7.11.1],
 100  link:RelNotes/1.7.11.txt[1.7.11].
 101
 102* link:v1.7.10.5/git.html[documentation for release 1.7.10.5]
 103
 104* release notes for
 105  link:RelNotes/1.7.10.5.txt[1.7.10.5],
 106  link:RelNotes/1.7.10.4.txt[1.7.10.4],
 107  link:RelNotes/1.7.10.3.txt[1.7.10.3],
 108  link:RelNotes/1.7.10.2.txt[1.7.10.2],
 109  link:RelNotes/1.7.10.1.txt[1.7.10.1],
 110  link:RelNotes/1.7.10.txt[1.7.10].
 111
 112* link:v1.7.9.7/git.html[documentation for release 1.7.9.7]
 113
 114* release notes for
 115  link:RelNotes/1.7.9.7.txt[1.7.9.7],
 116  link:RelNotes/1.7.9.6.txt[1.7.9.6],
 117  link:RelNotes/1.7.9.5.txt[1.7.9.5],
 118  link:RelNotes/1.7.9.4.txt[1.7.9.4],
 119  link:RelNotes/1.7.9.3.txt[1.7.9.3],
 120  link:RelNotes/1.7.9.2.txt[1.7.9.2],
 121  link:RelNotes/1.7.9.1.txt[1.7.9.1],
 122  link:RelNotes/1.7.9.txt[1.7.9].
 123
 124* link:v1.7.8.6/git.html[documentation for release 1.7.8.6]
 125
 126* release notes for
 127  link:RelNotes/1.7.8.6.txt[1.7.8.6],
 128  link:RelNotes/1.7.8.5.txt[1.7.8.5],
 129  link:RelNotes/1.7.8.4.txt[1.7.8.4],
 130  link:RelNotes/1.7.8.3.txt[1.7.8.3],
 131  link:RelNotes/1.7.8.2.txt[1.7.8.2],
 132  link:RelNotes/1.7.8.1.txt[1.7.8.1],
 133  link:RelNotes/1.7.8.txt[1.7.8].
 134
 135* link:v1.7.7.7/git.html[documentation for release 1.7.7.7]
 136
 137* release notes for
 138  link:RelNotes/1.7.7.7.txt[1.7.7.7],
 139  link:RelNotes/1.7.7.6.txt[1.7.7.6],
 140  link:RelNotes/1.7.7.5.txt[1.7.7.5],
 141  link:RelNotes/1.7.7.4.txt[1.7.7.4],
 142  link:RelNotes/1.7.7.3.txt[1.7.7.3],
 143  link:RelNotes/1.7.7.2.txt[1.7.7.2],
 144  link:RelNotes/1.7.7.1.txt[1.7.7.1],
 145  link:RelNotes/1.7.7.txt[1.7.7].
 146
 147* link:v1.7.6.6/git.html[documentation for release 1.7.6.6]
 148
 149* release notes for
 150  link:RelNotes/1.7.6.6.txt[1.7.6.6],
 151  link:RelNotes/1.7.6.5.txt[1.7.6.5],
 152  link:RelNotes/1.7.6.4.txt[1.7.6.4],
 153  link:RelNotes/1.7.6.3.txt[1.7.6.3],
 154  link:RelNotes/1.7.6.2.txt[1.7.6.2],
 155  link:RelNotes/1.7.6.1.txt[1.7.6.1],
 156  link:RelNotes/1.7.6.txt[1.7.6].
 157
 158* link:v1.7.5.4/git.html[documentation for release 1.7.5.4]
 159
 160* release notes for
 161  link:RelNotes/1.7.5.4.txt[1.7.5.4],
 162  link:RelNotes/1.7.5.3.txt[1.7.5.3],
 163  link:RelNotes/1.7.5.2.txt[1.7.5.2],
 164  link:RelNotes/1.7.5.1.txt[1.7.5.1],
 165  link:RelNotes/1.7.5.txt[1.7.5].
 166
 167* link:v1.7.4.5/git.html[documentation for release 1.7.4.5]
 168
 169* release notes for
 170  link:RelNotes/1.7.4.5.txt[1.7.4.5],
 171  link:RelNotes/1.7.4.4.txt[1.7.4.4],
 172  link:RelNotes/1.7.4.3.txt[1.7.4.3],
 173  link:RelNotes/1.7.4.2.txt[1.7.4.2],
 174  link:RelNotes/1.7.4.1.txt[1.7.4.1],
 175  link:RelNotes/1.7.4.txt[1.7.4].
 176
 177* link:v1.7.3.5/git.html[documentation for release 1.7.3.5]
 178
 179* release notes for
 180  link:RelNotes/1.7.3.5.txt[1.7.3.5],
 181  link:RelNotes/1.7.3.4.txt[1.7.3.4],
 182  link:RelNotes/1.7.3.3.txt[1.7.3.3],
 183  link:RelNotes/1.7.3.2.txt[1.7.3.2],
 184  link:RelNotes/1.7.3.1.txt[1.7.3.1],
 185  link:RelNotes/1.7.3.txt[1.7.3].
 186
 187* link:v1.7.2.5/git.html[documentation for release 1.7.2.5]
 188
 189* release notes for
 190  link:RelNotes/1.7.2.5.txt[1.7.2.5],
 191  link:RelNotes/1.7.2.4.txt[1.7.2.4],
 192  link:RelNotes/1.7.2.3.txt[1.7.2.3],
 193  link:RelNotes/1.7.2.2.txt[1.7.2.2],
 194  link:RelNotes/1.7.2.1.txt[1.7.2.1],
 195  link:RelNotes/1.7.2.txt[1.7.2].
 196
 197* link:v1.7.1.4/git.html[documentation for release 1.7.1.4]
 198
 199* release notes for
 200  link:RelNotes/1.7.1.4.txt[1.7.1.4],
 201  link:RelNotes/1.7.1.3.txt[1.7.1.3],
 202  link:RelNotes/1.7.1.2.txt[1.7.1.2],
 203  link:RelNotes/1.7.1.1.txt[1.7.1.1],
 204  link:RelNotes/1.7.1.txt[1.7.1].
 205
 206* link:v1.7.0.9/git.html[documentation for release 1.7.0.9]
 207
 208* release notes for
 209  link:RelNotes/1.7.0.9.txt[1.7.0.9],
 210  link:RelNotes/1.7.0.8.txt[1.7.0.8],
 211  link:RelNotes/1.7.0.7.txt[1.7.0.7],
 212  link:RelNotes/1.7.0.6.txt[1.7.0.6],
 213  link:RelNotes/1.7.0.5.txt[1.7.0.5],
 214  link:RelNotes/1.7.0.4.txt[1.7.0.4],
 215  link:RelNotes/1.7.0.3.txt[1.7.0.3],
 216  link:RelNotes/1.7.0.2.txt[1.7.0.2],
 217  link:RelNotes/1.7.0.1.txt[1.7.0.1],
 218  link:RelNotes/1.7.0.txt[1.7.0].
 219
 220* link:v1.6.6.3/git.html[documentation for release 1.6.6.3]
 221
 222* release notes for
 223  link:RelNotes/1.6.6.3.txt[1.6.6.3],
 224  link:RelNotes/1.6.6.2.txt[1.6.6.2],
 225  link:RelNotes/1.6.6.1.txt[1.6.6.1],
 226  link:RelNotes/1.6.6.txt[1.6.6].
 227
 228* link:v1.6.5.9/git.html[documentation for release 1.6.5.9]
 229
 230* release notes for
 231  link:RelNotes/1.6.5.9.txt[1.6.5.9],
 232  link:RelNotes/1.6.5.8.txt[1.6.5.8],
 233  link:RelNotes/1.6.5.7.txt[1.6.5.7],
 234  link:RelNotes/1.6.5.6.txt[1.6.5.6],
 235  link:RelNotes/1.6.5.5.txt[1.6.5.5],
 236  link:RelNotes/1.6.5.4.txt[1.6.5.4],
 237  link:RelNotes/1.6.5.3.txt[1.6.5.3],
 238  link:RelNotes/1.6.5.2.txt[1.6.5.2],
 239  link:RelNotes/1.6.5.1.txt[1.6.5.1],
 240  link:RelNotes/1.6.5.txt[1.6.5].
 241
 242* link:v1.6.4.5/git.html[documentation for release 1.6.4.5]
 243
 244* release notes for
 245  link:RelNotes/1.6.4.5.txt[1.6.4.5],
 246  link:RelNotes/1.6.4.4.txt[1.6.4.4],
 247  link:RelNotes/1.6.4.3.txt[1.6.4.3],
 248  link:RelNotes/1.6.4.2.txt[1.6.4.2],
 249  link:RelNotes/1.6.4.1.txt[1.6.4.1],
 250  link:RelNotes/1.6.4.txt[1.6.4].
 251
 252* link:v1.6.3.4/git.html[documentation for release 1.6.3.4]
 253
 254* release notes for
 255  link:RelNotes/1.6.3.4.txt[1.6.3.4],
 256  link:RelNotes/1.6.3.3.txt[1.6.3.3],
 257  link:RelNotes/1.6.3.2.txt[1.6.3.2],
 258  link:RelNotes/1.6.3.1.txt[1.6.3.1],
 259  link:RelNotes/1.6.3.txt[1.6.3].
 260
 261* release notes for
 262  link:RelNotes/1.6.2.5.txt[1.6.2.5],
 263  link:RelNotes/1.6.2.4.txt[1.6.2.4],
 264  link:RelNotes/1.6.2.3.txt[1.6.2.3],
 265  link:RelNotes/1.6.2.2.txt[1.6.2.2],
 266  link:RelNotes/1.6.2.1.txt[1.6.2.1],
 267  link:RelNotes/1.6.2.txt[1.6.2].
 268
 269* link:v1.6.1.3/git.html[documentation for release 1.6.1.3]
 270
 271* release notes for
 272  link:RelNotes/1.6.1.3.txt[1.6.1.3],
 273  link:RelNotes/1.6.1.2.txt[1.6.1.2],
 274  link:RelNotes/1.6.1.1.txt[1.6.1.1],
 275  link:RelNotes/1.6.1.txt[1.6.1].
 276
 277* link:v1.6.0.6/git.html[documentation for release 1.6.0.6]
 278
 279* release notes for
 280  link:RelNotes/1.6.0.6.txt[1.6.0.6],
 281  link:RelNotes/1.6.0.5.txt[1.6.0.5],
 282  link:RelNotes/1.6.0.4.txt[1.6.0.4],
 283  link:RelNotes/1.6.0.3.txt[1.6.0.3],
 284  link:RelNotes/1.6.0.2.txt[1.6.0.2],
 285  link:RelNotes/1.6.0.1.txt[1.6.0.1],
 286  link:RelNotes/1.6.0.txt[1.6.0].
 287
 288* link:v1.5.6.6/git.html[documentation for release 1.5.6.6]
 289
 290* release notes for
 291  link:RelNotes/1.5.6.6.txt[1.5.6.6],
 292  link:RelNotes/1.5.6.5.txt[1.5.6.5],
 293  link:RelNotes/1.5.6.4.txt[1.5.6.4],
 294  link:RelNotes/1.5.6.3.txt[1.5.6.3],
 295  link:RelNotes/1.5.6.2.txt[1.5.6.2],
 296  link:RelNotes/1.5.6.1.txt[1.5.6.1],
 297  link:RelNotes/1.5.6.txt[1.5.6].
 298
 299* link:v1.5.5.6/git.html[documentation for release 1.5.5.6]
 300
 301* release notes for
 302  link:RelNotes/1.5.5.6.txt[1.5.5.6],
 303  link:RelNotes/1.5.5.5.txt[1.5.5.5],
 304  link:RelNotes/1.5.5.4.txt[1.5.5.4],
 305  link:RelNotes/1.5.5.3.txt[1.5.5.3],
 306  link:RelNotes/1.5.5.2.txt[1.5.5.2],
 307  link:RelNotes/1.5.5.1.txt[1.5.5.1],
 308  link:RelNotes/1.5.5.txt[1.5.5].
 309
 310* link:v1.5.4.7/git.html[documentation for release 1.5.4.7]
 311
 312* release notes for
 313  link:RelNotes/1.5.4.7.txt[1.5.4.7],
 314  link:RelNotes/1.5.4.6.txt[1.5.4.6],
 315  link:RelNotes/1.5.4.5.txt[1.5.4.5],
 316  link:RelNotes/1.5.4.4.txt[1.5.4.4],
 317  link:RelNotes/1.5.4.3.txt[1.5.4.3],
 318  link:RelNotes/1.5.4.2.txt[1.5.4.2],
 319  link:RelNotes/1.5.4.1.txt[1.5.4.1],
 320  link:RelNotes/1.5.4.txt[1.5.4].
 321
 322* link:v1.5.3.8/git.html[documentation for release 1.5.3.8]
 323
 324* release notes for
 325  link:RelNotes/1.5.3.8.txt[1.5.3.8],
 326  link:RelNotes/1.5.3.7.txt[1.5.3.7],
 327  link:RelNotes/1.5.3.6.txt[1.5.3.6],
 328  link:RelNotes/1.5.3.5.txt[1.5.3.5],
 329  link:RelNotes/1.5.3.4.txt[1.5.3.4],
 330  link:RelNotes/1.5.3.3.txt[1.5.3.3],
 331  link:RelNotes/1.5.3.2.txt[1.5.3.2],
 332  link:RelNotes/1.5.3.1.txt[1.5.3.1],
 333  link:RelNotes/1.5.3.txt[1.5.3].
 334
 335* link:v1.5.2.5/git.html[documentation for release 1.5.2.5]
 336
 337* release notes for
 338  link:RelNotes/1.5.2.5.txt[1.5.2.5],
 339  link:RelNotes/1.5.2.4.txt[1.5.2.4],
 340  link:RelNotes/1.5.2.3.txt[1.5.2.3],
 341  link:RelNotes/1.5.2.2.txt[1.5.2.2],
 342  link:RelNotes/1.5.2.1.txt[1.5.2.1],
 343  link:RelNotes/1.5.2.txt[1.5.2].
 344
 345* link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
 346
 347* release notes for
 348  link:RelNotes/1.5.1.6.txt[1.5.1.6],
 349  link:RelNotes/1.5.1.5.txt[1.5.1.5],
 350  link:RelNotes/1.5.1.4.txt[1.5.1.4],
 351  link:RelNotes/1.5.1.3.txt[1.5.1.3],
 352  link:RelNotes/1.5.1.2.txt[1.5.1.2],
 353  link:RelNotes/1.5.1.1.txt[1.5.1.1],
 354  link:RelNotes/1.5.1.txt[1.5.1].
 355
 356* link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
 357
 358* release notes for
 359  link:RelNotes/1.5.0.7.txt[1.5.0.7],
 360  link:RelNotes/1.5.0.6.txt[1.5.0.6],
 361  link:RelNotes/1.5.0.5.txt[1.5.0.5],
 362  link:RelNotes/1.5.0.3.txt[1.5.0.3],
 363  link:RelNotes/1.5.0.2.txt[1.5.0.2],
 364  link:RelNotes/1.5.0.1.txt[1.5.0.1],
 365  link:RelNotes/1.5.0.txt[1.5.0].
 366
 367* documentation for release link:v1.4.4.4/git.html[1.4.4.4],
 368  link:v1.3.3/git.html[1.3.3],
 369  link:v1.2.6/git.html[1.2.6],
 370  link:v1.0.13/git.html[1.0.13].
 371
 372============
 373
 374endif::stalenotes[]
 375
 376OPTIONS
 377-------
 378--version::
 379        Prints the Git suite version that the 'git' program came from.
 380
 381--help::
 382        Prints the synopsis and a list of the most commonly used
 383        commands. If the option '--all' or '-a' is given then all
 384        available commands are printed. If a Git command is named this
 385        option will bring up the manual page for that command.
 386+
 387Other options are available to control how the manual page is
 388displayed. See linkgit:git-help[1] for more information,
 389because `git --help ...` is converted internally into `git
 390help ...`.
 391
 392-c <name>=<value>::
 393        Pass a configuration parameter to the command. The value
 394        given will override values from configuration files.
 395        The <name> is expected in the same format as listed by
 396        'git config' (subkeys separated by dots).
 397
 398--exec-path[=<path>]::
 399        Path to wherever your core Git programs are installed.
 400        This can also be controlled by setting the GIT_EXEC_PATH
 401        environment variable. If no path is given, 'git' will print
 402        the current setting and then exit.
 403
 404--html-path::
 405        Print the path, without trailing slash, where Git's HTML
 406        documentation is installed and exit.
 407
 408--man-path::
 409        Print the manpath (see `man(1)`) for the man pages for
 410        this version of Git and exit.
 411
 412--info-path::
 413        Print the path where the Info files documenting this
 414        version of Git are installed and exit.
 415
 416-p::
 417--paginate::
 418        Pipe all output into 'less' (or if set, $PAGER) if standard
 419        output is a terminal.  This overrides the `pager.<cmd>`
 420        configuration options (see the "Configuration Mechanism" section
 421        below).
 422
 423--no-pager::
 424        Do not pipe Git output into a pager.
 425
 426--git-dir=<path>::
 427        Set the path to the repository. This can also be controlled by
 428        setting the GIT_DIR environment variable. It can be an absolute
 429        path or relative path to current working directory.
 430
 431--work-tree=<path>::
 432        Set the path to the working tree. It can be an absolute path
 433        or a path relative to the current working directory.
 434        This can also be controlled by setting the GIT_WORK_TREE
 435        environment variable and the core.worktree configuration
 436        variable (see core.worktree in linkgit:git-config[1] for a
 437        more detailed discussion).
 438
 439--namespace=<path>::
 440        Set the Git namespace.  See linkgit:gitnamespaces[7] for more
 441        details.  Equivalent to setting the `GIT_NAMESPACE` environment
 442        variable.
 443
 444--bare::
 445        Treat the repository as a bare repository.  If GIT_DIR
 446        environment is not set, it is set to the current working
 447        directory.
 448
 449--no-replace-objects::
 450        Do not use replacement refs to replace Git objects. See
 451        linkgit:git-replace[1] for more information.
 452
 453--literal-pathspecs::
 454        Treat pathspecs literally, rather than as glob patterns. This is
 455        equivalent to setting the `GIT_LITERAL_PATHSPECS` environment
 456        variable to `1`.
 457
 458
 459GIT COMMANDS
 460------------
 461
 462We divide Git into high level ("porcelain") commands and low level
 463("plumbing") commands.
 464
 465High-level commands (porcelain)
 466-------------------------------
 467
 468We separate the porcelain commands into the main commands and some
 469ancillary user utilities.
 470
 471Main porcelain commands
 472~~~~~~~~~~~~~~~~~~~~~~~
 473
 474include::cmds-mainporcelain.txt[]
 475
 476Ancillary Commands
 477~~~~~~~~~~~~~~~~~~
 478Manipulators:
 479
 480include::cmds-ancillarymanipulators.txt[]
 481
 482Interrogators:
 483
 484include::cmds-ancillaryinterrogators.txt[]
 485
 486
 487Interacting with Others
 488~~~~~~~~~~~~~~~~~~~~~~~
 489
 490These commands are to interact with foreign SCM and with other
 491people via patch over e-mail.
 492
 493include::cmds-foreignscminterface.txt[]
 494
 495
 496Low-level commands (plumbing)
 497-----------------------------
 498
 499Although Git includes its
 500own porcelain layer, its low-level commands are sufficient to support
 501development of alternative porcelains.  Developers of such porcelains
 502might start by reading about linkgit:git-update-index[1] and
 503linkgit:git-read-tree[1].
 504
 505The interface (input, output, set of options and the semantics)
 506to these low-level commands are meant to be a lot more stable
 507than Porcelain level commands, because these commands are
 508primarily for scripted use.  The interface to Porcelain commands
 509on the other hand are subject to change in order to improve the
 510end user experience.
 511
 512The following description divides
 513the low-level commands into commands that manipulate objects (in
 514the repository, index, and working tree), commands that interrogate and
 515compare objects, and commands that move objects and references between
 516repositories.
 517
 518
 519Manipulation commands
 520~~~~~~~~~~~~~~~~~~~~~
 521
 522include::cmds-plumbingmanipulators.txt[]
 523
 524
 525Interrogation commands
 526~~~~~~~~~~~~~~~~~~~~~~
 527
 528include::cmds-plumbinginterrogators.txt[]
 529
 530In general, the interrogate commands do not touch the files in
 531the working tree.
 532
 533
 534Synching repositories
 535~~~~~~~~~~~~~~~~~~~~~
 536
 537include::cmds-synchingrepositories.txt[]
 538
 539The following are helper commands used by the above; end users
 540typically do not use them directly.
 541
 542include::cmds-synchelpers.txt[]
 543
 544
 545Internal helper commands
 546~~~~~~~~~~~~~~~~~~~~~~~~
 547
 548These are internal helper commands used by other commands; end
 549users typically do not use them directly.
 550
 551include::cmds-purehelpers.txt[]
 552
 553
 554Configuration Mechanism
 555-----------------------
 556
 557Git uses a simple text format to store customizations that are per
 558repository and are per user.  Such a configuration file may look
 559like this:
 560
 561------------
 562#
 563# A '#' or ';' character indicates a comment.
 564#
 565
 566; core variables
 567[core]
 568        ; Don't trust file modes
 569        filemode = false
 570
 571; user identity
 572[user]
 573        name = "Junio C Hamano"
 574        email = "gitster@pobox.com"
 575
 576------------
 577
 578Various commands read from the configuration file and adjust
 579their operation accordingly.  See linkgit:git-config[1] for a
 580list and more details about the configuration mechanism.
 581
 582
 583Identifier Terminology
 584----------------------
 585<object>::
 586        Indicates the object name for any type of object.
 587
 588<blob>::
 589        Indicates a blob object name.
 590
 591<tree>::
 592        Indicates a tree object name.
 593
 594<commit>::
 595        Indicates a commit object name.
 596
 597<tree-ish>::
 598        Indicates a tree, commit or tag object name.  A
 599        command that takes a <tree-ish> argument ultimately wants to
 600        operate on a <tree> object but automatically dereferences
 601        <commit> and <tag> objects that point at a <tree>.
 602
 603<commit-ish>::
 604        Indicates a commit or tag object name.  A
 605        command that takes a <commit-ish> argument ultimately wants to
 606        operate on a <commit> object but automatically dereferences
 607        <tag> objects that point at a <commit>.
 608
 609<type>::
 610        Indicates that an object type is required.
 611        Currently one of: `blob`, `tree`, `commit`, or `tag`.
 612
 613<file>::
 614        Indicates a filename - almost always relative to the
 615        root of the tree structure `GIT_INDEX_FILE` describes.
 616
 617Symbolic Identifiers
 618--------------------
 619Any Git command accepting any <object> can also use the following
 620symbolic notation:
 621
 622HEAD::
 623        indicates the head of the current branch.
 624
 625<tag>::
 626        a valid tag 'name'
 627        (i.e. a `refs/tags/<tag>` reference).
 628
 629<head>::
 630        a valid head 'name'
 631        (i.e. a `refs/heads/<head>` reference).
 632
 633For a more complete list of ways to spell object names, see
 634"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
 635
 636
 637File/Directory Structure
 638------------------------
 639
 640Please see the linkgit:gitrepository-layout[5] document.
 641
 642Read linkgit:githooks[5] for more details about each hook.
 643
 644Higher level SCMs may provide and manage additional information in the
 645`$GIT_DIR`.
 646
 647
 648Terminology
 649-----------
 650Please see linkgit:gitglossary[7].
 651
 652
 653Environment Variables
 654---------------------
 655Various Git commands use the following environment variables:
 656
 657The Git Repository
 658~~~~~~~~~~~~~~~~~~
 659These environment variables apply to 'all' core Git commands. Nb: it
 660is worth noting that they may be used/overridden by SCMS sitting above
 661Git so take care if using Cogito etc.
 662
 663'GIT_INDEX_FILE'::
 664        This environment allows the specification of an alternate
 665        index file. If not specified, the default of `$GIT_DIR/index`
 666        is used.
 667
 668'GIT_OBJECT_DIRECTORY'::
 669        If the object storage directory is specified via this
 670        environment variable then the sha1 directories are created
 671        underneath - otherwise the default `$GIT_DIR/objects`
 672        directory is used.
 673
 674'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 675        Due to the immutable nature of Git objects, old objects can be
 676        archived into shared, read-only directories. This variable
 677        specifies a ":" separated (on Windows ";" separated) list
 678        of Git object directories which can be used to search for Git
 679        objects. New objects will not be written to these directories.
 680
 681'GIT_DIR'::
 682        If the 'GIT_DIR' environment variable is set then it
 683        specifies a path to use instead of the default `.git`
 684        for the base of the repository.
 685        The '--git-dir' command-line option also sets this value.
 686
 687'GIT_WORK_TREE'::
 688        Set the path to the root of the working tree.
 689        This can also be controlled by the '--work-tree' command line
 690        option and the core.worktree configuration variable.
 691
 692'GIT_NAMESPACE'::
 693        Set the Git namespace; see linkgit:gitnamespaces[7] for details.
 694        The '--namespace' command-line option also sets this value.
 695
 696'GIT_CEILING_DIRECTORIES'::
 697        This should be a colon-separated list of absolute paths.  If
 698        set, it is a list of directories that Git should not chdir up
 699        into while looking for a repository directory (useful for
 700        excluding slow-loading network directories).  It will not
 701        exclude the current working directory or a GIT_DIR set on the
 702        command line or in the environment.  Normally, Git has to read
 703        the entries in this list and resolve any symlink that
 704        might be present in order to compare them with the current
 705        directory.  However, if even this access is slow, you
 706        can add an empty entry to the list to tell Git that the
 707        subsequent entries are not symlinks and needn't be resolved;
 708        e.g.,
 709        'GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink'.
 710
 711'GIT_DISCOVERY_ACROSS_FILESYSTEM'::
 712        When run in a directory that does not have ".git" repository
 713        directory, Git tries to find such a directory in the parent
 714        directories to find the top of the working tree, but by default it
 715        does not cross filesystem boundaries.  This environment variable
 716        can be set to true to tell Git not to stop at filesystem
 717        boundaries.  Like 'GIT_CEILING_DIRECTORIES', this will not affect
 718        an explicit repository directory set via 'GIT_DIR' or on the
 719        command line.
 720
 721Git Commits
 722~~~~~~~~~~~
 723'GIT_AUTHOR_NAME'::
 724'GIT_AUTHOR_EMAIL'::
 725'GIT_AUTHOR_DATE'::
 726'GIT_COMMITTER_NAME'::
 727'GIT_COMMITTER_EMAIL'::
 728'GIT_COMMITTER_DATE'::
 729'EMAIL'::
 730        see linkgit:git-commit-tree[1]
 731
 732Git Diffs
 733~~~~~~~~~
 734'GIT_DIFF_OPTS'::
 735        Only valid setting is "--unified=??" or "-u??" to set the
 736        number of context lines shown when a unified diff is created.
 737        This takes precedence over any "-U" or "--unified" option
 738        value passed on the Git diff command line.
 739
 740'GIT_EXTERNAL_DIFF'::
 741        When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
 742        program named by it is called, instead of the diff invocation
 743        described above.  For a path that is added, removed, or modified,
 744        'GIT_EXTERNAL_DIFF' is called with 7 parameters:
 745
 746        path old-file old-hex old-mode new-file new-hex new-mode
 747+
 748where:
 749
 750        <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
 751                         contents of <old|new>,
 752        <old|new>-hex:: are the 40-hexdigit SHA-1 hashes,
 753        <old|new>-mode:: are the octal representation of the file modes.
 754+
 755The file parameters can point at the user's working file
 756(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 757when a new file is added), or a temporary file (e.g. `old-file` in the
 758index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
 759temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
 760+
 761For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
 762parameter, <path>.
 763
 764other
 765~~~~~
 766'GIT_MERGE_VERBOSITY'::
 767        A number controlling the amount of output shown by
 768        the recursive merge strategy.  Overrides merge.verbosity.
 769        See linkgit:git-merge[1]
 770
 771'GIT_PAGER'::
 772        This environment variable overrides `$PAGER`. If it is set
 773        to an empty string or to the value "cat", Git will not launch
 774        a pager.  See also the `core.pager` option in
 775        linkgit:git-config[1].
 776
 777'GIT_EDITOR'::
 778        This environment variable overrides `$EDITOR` and `$VISUAL`.
 779        It is used by several Git commands when, on interactive mode,
 780        an editor is to be launched. See also linkgit:git-var[1]
 781        and the `core.editor` option in linkgit:git-config[1].
 782
 783'GIT_SSH'::
 784        If this environment variable is set then 'git fetch'
 785        and 'git push' will use this command instead
 786        of 'ssh' when they need to connect to a remote system.
 787        The '$GIT_SSH' command will be given exactly two or
 788        four arguments: the 'username@host' (or just 'host')
 789        from the URL and the shell command to execute on that
 790        remote system, optionally preceded by '-p' (literally) and
 791        the 'port' from the URL when it specifies something other
 792        than the default SSH port.
 793+
 794To pass options to the program that you want to list in GIT_SSH
 795you will need to wrap the program and options into a shell script,
 796then set GIT_SSH to refer to the shell script.
 797+
 798Usually it is easier to configure any desired options through your
 799personal `.ssh/config` file.  Please consult your ssh documentation
 800for further details.
 801
 802'GIT_ASKPASS'::
 803        If this environment variable is set, then Git commands which need to
 804        acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
 805        will call this program with a suitable prompt as command line argument
 806        and read the password from its STDOUT. See also the 'core.askpass'
 807        option in linkgit:git-config[1].
 808
 809'GIT_CONFIG_NOSYSTEM'::
 810        Whether to skip reading settings from the system-wide
 811        `$(prefix)/etc/gitconfig` file.  This environment variable can
 812        be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
 813        predictable environment for a picky script, or you can set it
 814        temporarily to avoid using a buggy `/etc/gitconfig` file while
 815        waiting for someone with sufficient permissions to fix it.
 816
 817'GIT_FLUSH'::
 818        If this environment variable is set to "1", then commands such
 819        as 'git blame' (in incremental mode), 'git rev-list', 'git log',
 820        and 'git whatchanged' will force a flush of the output stream
 821        after each commit-oriented record have been flushed.   If this
 822        variable is set to "0", the output of these commands will be done
 823        using completely buffered I/O.   If this environment variable is
 824        not set, Git will choose buffered or record-oriented flushing
 825        based on whether stdout appears to be redirected to a file or not.
 826
 827'GIT_TRACE'::
 828        If this variable is set to "1", "2" or "true" (comparison
 829        is case insensitive), Git will print `trace:` messages on
 830        stderr telling about alias expansion, built-in command
 831        execution and external command execution.
 832        If this variable is set to an integer value greater than 1
 833        and lower than 10 (strictly) then Git will interpret this
 834        value as an open file descriptor and will try to write the
 835        trace messages into this file descriptor.
 836        Alternatively, if this variable is set to an absolute path
 837        (starting with a '/' character), Git will interpret this
 838        as a file path and will try to write the trace messages
 839        into it.
 840
 841GIT_LITERAL_PATHSPECS::
 842        Setting this variable to `1` will cause Git to treat all
 843        pathspecs literally, rather than as glob patterns. For example,
 844        running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
 845        for commits that touch the path `*.c`, not any paths that the
 846        glob `*.c` matches. You might want this if you are feeding
 847        literal paths to Git (e.g., paths previously given to you by
 848        `git ls-tree`, `--raw` diff output, etc).
 849
 850
 851Discussion[[Discussion]]
 852------------------------
 853
 854More detail on the following is available from the
 855link:user-manual.html#git-concepts[Git concepts chapter of the
 856user-manual] and linkgit:gitcore-tutorial[7].
 857
 858A Git project normally consists of a working directory with a ".git"
 859subdirectory at the top level.  The .git directory contains, among other
 860things, a compressed object database representing the complete history
 861of the project, an "index" file which links that history to the current
 862contents of the working tree, and named pointers into that history such
 863as tags and branch heads.
 864
 865The object database contains objects of three main types: blobs, which
 866hold file data; trees, which point to blobs and other trees to build up
 867directory hierarchies; and commits, which each reference a single tree
 868and some number of parent commits.
 869
 870The commit, equivalent to what other systems call a "changeset" or
 871"version", represents a step in the project's history, and each parent
 872represents an immediately preceding step.  Commits with more than one
 873parent represent merges of independent lines of development.
 874
 875All objects are named by the SHA-1 hash of their contents, normally
 876written as a string of 40 hex digits.  Such names are globally unique.
 877The entire history leading up to a commit can be vouched for by signing
 878just that commit.  A fourth object type, the tag, is provided for this
 879purpose.
 880
 881When first created, objects are stored in individual files, but for
 882efficiency may later be compressed together into "pack files".
 883
 884Named pointers called refs mark interesting points in history.  A ref
 885may contain the SHA-1 name of an object or the name of another ref.  Refs
 886with names beginning `ref/head/` contain the SHA-1 name of the most
 887recent commit (or "head") of a branch under development.  SHA-1 names of
 888tags of interest are stored under `ref/tags/`.  A special ref named
 889`HEAD` contains the name of the currently checked-out branch.
 890
 891The index file is initialized with a list of all paths and, for each
 892path, a blob object and a set of attributes.  The blob object represents
 893the contents of the file as of the head of the current branch.  The
 894attributes (last modified time, size, etc.) are taken from the
 895corresponding file in the working tree.  Subsequent changes to the
 896working tree can be found by comparing these attributes.  The index may
 897be updated with new content, and new commits may be created from the
 898content stored in the index.
 899
 900The index is also capable of storing multiple entries (called "stages")
 901for a given pathname.  These stages are used to hold the various
 902unmerged version of a file when a merge is in progress.
 903
 904FURTHER DOCUMENTATION
 905---------------------
 906
 907See the references in the "description" section to get started
 908using Git.  The following is probably more detail than necessary
 909for a first-time user.
 910
 911The link:user-manual.html#git-concepts[Git concepts chapter of the
 912user-manual] and linkgit:gitcore-tutorial[7] both provide
 913introductions to the underlying Git architecture.
 914
 915See linkgit:gitworkflows[7] for an overview of recommended workflows.
 916
 917See also the link:howto-index.html[howto] documents for some useful
 918examples.
 919
 920The internals are documented in the
 921link:technical/api-index.html[Git API documentation].
 922
 923Users migrating from CVS may also want to
 924read linkgit:gitcvs-migration[7].
 925
 926
 927Authors
 928-------
 929Git was started by Linus Torvalds, and is currently maintained by Junio
 930C Hamano. Numerous contributions have come from the Git mailing list
 931<git@vger.kernel.org>.  http://www.ohloh.net/p/git/contributors/summary
 932gives you a more complete list of contributors.
 933
 934If you have a clone of git.git itself, the
 935output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
 936the authors for specific parts of the project.
 937
 938Reporting Bugs
 939--------------
 940
 941Report bugs to the Git mailing list <git@vger.kernel.org> where the
 942development and maintenance is primarily done.  You do not have to be
 943subscribed to the list to send a message there.
 944
 945SEE ALSO
 946--------
 947linkgit:gittutorial[7], linkgit:gittutorial-2[7],
 948link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],
 949linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
 950linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
 951linkgit:gitworkflows[7]
 952
 953GIT
 954---
 955Part of the linkgit:git[1] suite