Merge branch 'ks/maint-1.6.0-mailinfo-folded' into maint-1.6.1
[gitweb.git] / Documentation / git-push.txt
index 05859491378243639e81c9c8ab7deffb90d83d07..ac6421178c1a62ca62fb335d9939ec36368c7e82 100644 (file)
@@ -9,8 +9,9 @@ git-push - Update remote refs along with associated objects
 SYNOPSIS
 --------
 [verse]
-'git-push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
-           [--repo=all] [-f | --force] [-v | --verbose] [<repository> <refspec>...]
+'git push' [--all | --mirror | --tags] [--dry-run] [--receive-pack=<git-receive-pack>]
+          [--repo=<repository>] [-f | --force] [-v | --verbose]
+          [<repository> <refspec>...]
 
 DESCRIPTION
 -----------
@@ -27,84 +28,106 @@ OPTIONS
 -------
 <repository>::
        The "remote" repository that is destination of a push
-       operation.  See the section <<URLS,GIT URLS>> below.
-
-<refspec>::
-       The canonical format of a <refspec> parameter is
-       `+?<src>:<dst>`; that is, an optional plus `+`, followed
-       by the source ref, followed by a colon `:`, followed by
-       the destination ref.
+       operation.  This parameter can be either a URL
+       (see the section <<URLS,GIT URLS>> below) or the name
+       of a remote (see the section <<REMOTES,REMOTES>> below).
+
+<refspec>...::
+       The format of a <refspec> parameter is an optional plus
+       `{plus}`, followed by the source ref <src>, followed
+       by a colon `:`, followed by the destination ref <dst>.
+       It is used to specify with what <src> object the <dst> ref
+       in the remote repository is to be updated.
 +
-The <src> side represents the source branch (or arbitrary
-"SHA1 expression", such as `master~4` (four parents before the
-tip of `master` branch); see linkgit:git-rev-parse[1]) that you
-want to push.  The <dst> side represents the destination location.
+The <src> is often the name of the branch you would want to push, but
+it can be any arbitrary "SHA-1 expression", such as `master~4` or
+`HEAD` (see linkgit:git-rev-parse[1]).
 +
-The local ref that matches <src> is used
-to fast forward the remote ref that matches <dst> (or, if no <dst> was
-specified, the same ref that <src> referred to locally).  If
-the optional leading plus `+` is used, the remote ref is updated
-even if it does not result in a fast forward update.
+The <dst> tells which ref on the remote side is updated with this
+push. Arbitrary expressions cannot be used here, an actual ref must
+be named. If `:`<dst> is omitted, the same ref as <src> will be
+updated.
 +
-Note: If no explicit refspec is found, (that is neither
-on the command line nor in any Push line of the
-corresponding remotes file---see below), then "matching" heads are
-pushed: for every head that exists on the local side, the remote side is
-updated if a head of the same name already exists on the remote side.
+The object referenced by <src> is used to fast forward the ref <dst>
+on the remote side. If the optional leading plus `{plus}` is used, the
+remote ref is updated even if it does not result in a fast forward
+update.
 +
 `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
 +
-A parameter <ref> without a colon pushes the <ref> from the source
-repository to the destination repository under the same name.
-+
 Pushing an empty <src> allows you to delete the <dst> ref from
 the remote repository.
-
-\--all::
++
+The special refspec `:` (or `+:` to allow non-fast forward updates)
+directs git to push "matching" branches: for every branch that exists on
+the local side, the remote side is updated if a branch of the same name
+already exists on the remote side.  This is the default operation mode
+if no explicit refspec is found (that is neither on the command line
+nor in any Push line of the corresponding remotes file---see below).
+
+--all::
        Instead of naming each ref to push, specifies that all
        refs under `$GIT_DIR/refs/heads/` be pushed.
 
-\--mirror::
+--mirror::
        Instead of naming each ref to push, specifies that all
-       refs under `$GIT_DIR/refs/heads/` and `$GIT_DIR/refs/tags/`
+       refs under `$GIT_DIR/refs/` (which includes but is not
+       limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
        be mirrored to the remote repository.  Newly created local
        refs will be pushed to the remote end, locally updated refs
        will be force updated on the remote end, and deleted refs
-       will be removed from the remote end.
+       will be removed from the remote end.  This is the default
+       if the configuration option `remote.<remote>.mirror` is
+       set.
 
-\--dry-run::
+--dry-run::
        Do everything except actually send the updates.
 
-\--tags::
+--tags::
        All refs under `$GIT_DIR/refs/tags` are pushed, in
        addition to refspecs explicitly listed on the command
        line.
 
-\--receive-pack=<git-receive-pack>::
+--receive-pack=<git-receive-pack>::
+--exec=<git-receive-pack>::
        Path to the 'git-receive-pack' program on the remote
        end.  Sometimes useful when pushing to a remote
        repository over ssh, and you do not have the program in
        a directory on the default $PATH.
 
-\--exec=<git-receive-pack>::
-       Same as \--receive-pack=<git-receive-pack>.
-
--f, \--force::
+-f::
+--force::
        Usually, the command refuses to update a remote ref that is
        not an ancestor of the local ref used to overwrite it.
        This flag disables the check.  This can cause the
        remote repository to lose commits; use it with care.
 
-\--repo=<repo>::
-       When no repository is specified the command defaults to
-       "origin"; this overrides it.
+--repo=<repository>::
+       This option is only relevant if no <repository> argument is
+       passed in the invocation. In this case, 'git-push' derives the
+       remote name from the current branch: If it tracks a remote
+       branch, then that remote repository is pushed to. Otherwise,
+       the name "origin" is used. For this latter case, this option
+       can be used to override the name "origin". In other words,
+       the difference between these two commands
++
+--------------------------
+git push public         #1
+git push --repo=public  #2
+--------------------------
++
+is that #1 always pushes to "public" whereas #2 pushes to "public"
+only if the current branch does not track a remote branch. This is
+useful if you write an alias or script around 'git-push'.
 
-\--thin, \--no-thin::
-       These options are passed to `git-send-pack`.  Thin
+--thin::
+--no-thin::
+       These options are passed to 'git-send-pack'.  Thin
        transfer spends extra cycles to minimize the number of
        objects to be sent and meant to be used on slower connection.
 
--v, \--verbose::
+-v::
+--verbose::
        Run verbosely.
 
 include::urls-remotes.txt[]
@@ -169,15 +192,20 @@ git push origin master::
        with it.  If `master` did not exist remotely, it would be
        created.
 
-git push origin :experimental::
-       Find a ref that matches `experimental` in the `origin` repository
-       (e.g. `refs/heads/experimental`), and delete it.
+git push origin HEAD::
+       A handy way to push the current branch to the same name on the
+       remote.
 
-git push origin master:satellite/master::
-       Find a ref that matches `master` in the source repository
-       (most likely, it would find `refs/heads/master`), and update
-       the ref that matches `satellite/master` (most likely, it would
-       be `refs/remotes/satellite/master`) in `origin` repository with it.
+git push origin master:satellite/master dev:satellite/dev::
+       Use the source ref that matches `master` (e.g. `refs/heads/master`)
+       to update the ref that matches `satellite/master` (most probably
+       `refs/remotes/satellite/master`) in the `origin` repository, then
+       do the same for `dev` and `satellite/dev`.
+
+git push origin HEAD:master::
+       Push the current branch to the remote ref matching `master` in the
+       `origin` repository. This form is convenient to push the current
+       branch without thinking about its local name.
 
 git push origin master:refs/heads/experimental::
        Create the branch `experimental` in the `origin` repository
@@ -186,9 +214,14 @@ git push origin master:refs/heads/experimental::
        the local name and the remote name are different; otherwise,
        the ref name on its own will work.
 
+git push origin :experimental::
+       Find a ref that matches `experimental` in the `origin` repository
+       (e.g. `refs/heads/experimental`), and delete it.
+
+
 Author
 ------
-Written by Junio C Hamano <junkio@cox.net>, later rewritten in C
+Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C
 by Linus Torvalds <torvalds@osdl.org>
 
 Documentation
@@ -197,4 +230,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT
 ---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite