More on commit editing

[git-wiki.git] / pep-git.txt

diff --git a/pep-git.txt b/pep-git.txt
index e51ae53d5e24a23d68ef325421a49beab0ca007d..0d33a63fd8fd6f9331cd182a43677b2b6e8d6d08 100644 (file)
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -23,6 +23,7 @@ Python development from Mercurial to git.
 The author of the PEP doesn't currently plan to write a Process PEP on
 migration from Mercurial to git.
 
+
 Documentation
 =============
 
@@ -64,6 +65,7 @@ Offline documentation
 Git has builtin help: run ``git help TOPIC``. For example, run
 ``git help git`` or ``git help help``.
 
+
 Quick start
 ===========
 
@@ -89,6 +91,63 @@ important so let repeat it here::
     $ git config --global user.name "User Name"
     $ git config --global user.email user.name@example.org
 
+
+Examples in this PEP
+====================
+
+Examples of git commands in this PEP use the following approach. It is
+supposed that you, the user, works with a local repository named
+``python`` that has an upstream remote repo named ``origin``. Your
+local repo has two branches ``v1`` and ``v2``. Usually the currently
+checked out branch is ``v2``. That is, it's assumed you did something
+like::
+
+    $ git clone -b v1 http://git.python.org/python.git
+    $ cd python
+    $ git fetch origin v2:v2
+    $ git checkout -b v2
+
+
+Commit editing and caveats
+==========================
+
+A warning not to edit published (pushed) commits also appears in
+documentation but it's also repeated here as it's very important.
+
+It is possible to recover from forced push but it's PITA for the
+entire team. Please avoid it.
+
+To see what commits have not been published yet compare the head of the
+branch with its upstream remote branch::
+
+    $ git log origin/v2..
+
+For every branch that has an upstream remote branch git maintains an
+alias @{upstream} (short version @{u})::
+
+    $ git log @{u}..
+    $ git log v1@{u}..v1
+
+To see the status of all branches::
+
+    $ git branch -avv
+
+To compare the status of local branches with remote repo::
+
+    $ git remote show origin
+
+Read `how to recover from upstream rebase
+<https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
+It is in ``git help rebase``.
+
+On the other hand don't be too afraid about commit editing. You can
+safely edit, remove, reorder, combine and split commits that hasn't
+been pushed yet. You can even push commits to your own (backup) repo,
+edit them later and force-push edited commits to replace what has
+already been pushed. Not a problem until commits are in a public
+repository.
+
+
 References
 ==========