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