user-manual: failed push to public repository
More details on the case of a failed push to a public (non-shared) repository. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
J. Bruce Fields committed
Nov 25, 2007 at 17:54 UTC
81eb417ad423ef7e8d088d517f89d3bda92f9c06
1 file changed
+49
-9
Documentation/user-manual.txt
+49
-9
@@ -1929,15 +1929,9 @@ or just
1929
$ git push ssh://yourserver.com/~you/proj.git master
1930
-------------------------------------------------
1931
1932
-As with git-fetch, git-push will complain if this does not result in
1933
-a <<fast-forwards,fast forward>>. Normally this is a sign of
1934
-something wrong. However, if you are sure you know what you're
1935
-doing, you may force git-push to perform the update anyway by
1936
-proceeding the branch name by a plus sign:
1937
-
1938
--------------------------------------------------
1939
-$ git push ssh://yourserver.com/~you/proj.git +master
1940
--------------------------------------------------
1932
+As with git-fetch, git-push will complain if this does not result in a
1933
+<<fast-forwards,fast forward>>; see the following section for details on
1934
+handling this case.
1935
1936
Note that the target of a "push" is normally a
1937
<<def_bare_repository,bare>> repository. You can also push to a
@@ -1965,6 +1959,52 @@ See the explanations of the remote.<name>.url, branch.<name>.remote,
1959
and remote.<name>.push options in gitlink:git-config[1] for
1960
details.
1961
1962
+[[forcing-push]]
1963
+What to do when a push fails
1964
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1965
+
1966
+If a push would not result in a <<fast-forwards,fast forward>> of the
1967
+remote branch, then it will fail with an error like:
1968
+
1969
+-------------------------------------------------
1970
+error: remote 'refs/heads/master' is not an ancestor of
1971
+ local 'refs/heads/master'.
1972
+ Maybe you are not up-to-date and need to pull first?
1973
+error: failed to push to 'ssh://yourserver.com/~you/proj.git'
1974
+-------------------------------------------------
1975
+
1976
+This can happen, for example, if you:
1977
+
1978
+ - use `git reset --hard` to remove already-published commits, or
1979
+ - use `git commit --amend` to replace already-published commits
1980
+ (as in <<fixing-a-mistake-by-editing-history>>), or
1981
+ - use `git rebase` to rebase any already-published commits (as
1982
+ in <<using-git-rebase>>).
1983
+
1984
+You may force git-push to perform the update anyway by preceding the
1985
+branch name with a plus sign:
1986
+
1987
+-------------------------------------------------
1988
+$ git push ssh://yourserver.com/~you/proj.git +master
1989
+-------------------------------------------------
1990
+
1991
+Normally whenever a branch head in a public repository is modified, it
1992
+is modified to point to a descendent of the commit that it pointed to
1993
+before. By forcing a push in this situation, you break that convention.
1994
+(See <<problems-with-rewriting-history>>.)
1995
+
1996
+Nevertheless, this is a common practice for people that need a simple
1997
+way to publish a work-in-progress patch series, and it is an acceptable
1998
+compromise as long as you warn other developers that this is how you
1999
+intend to manage the branch.
2000
+
2001
+It's also possible for a push to fail in this way when other people have
2002
+the right to push to the same repository. In that case, the correct
2003
+solution is to retry the push after first updating your work by either a
2004
+pull or a fetch followed by a rebase; see the
2005
+<<setting-up-a-shared-repository,next section>> and
2006
+link:cvs-migration.html[git for CVS users] for more.
2007
+
2008
[[setting-up-a-shared-repository]]
2009
Setting up a shared repository
2010
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~