Changes between Version 86 and Version 87 of DeveloperGuidelines/Git

Timestamp:

01/02/14 13:08:08 (12 years ago)

Author:

Pat Tressel

Comment:

--

DeveloperGuidelines/Git

@@ -104 +104 @@
 from trunk, then either "rebasing" or "merging" to include them in the branch you want to update.
 
-Rebasing lifts your commits off of the common base your branch shared with trunk, then inserts the new
-trunk revisions, then applies your commits on top of those.  Merging leaves your commits where they are,
-and adds the trunk revisions alongside them.
+Although rebasing and merging may end up with the same code, the process and "side effects" differ:
+* Rebasing lifts your commits off of the common base your branch shared with trunk, then inserts the new
+  trunk revisions, then applies your commits on top of those.  Merging leaves your commits where they are,
+  and adds the trunk revisions alongside them.
+* Rebasing ends with a linear sequence of commits -- each commit has a single child.  Merging ends up with
+  a directed acyclic graph of commits -- some commits will have multiple child commits, or multiple parents.
+* If you encounter conflicts while rebasing, you will fix up each of your commits to deal with the conflicts,
+  so when you're done, each of your commits will still be self-contained, free of conflicts, and consistent
+  with the trunk commits that are its ancestors. Conflicts during a merge are handled together at the end of
+  the merge, in a separate "merge commit" that consists of all the new commits that came from trunk, along
+  with any edits you make to deal with merge conflicts.  Your commits will still contain their conflicts --
+  those were fixed externally.
+* There is also a difference in how your commits will appear in the log, and in particular, what order
+  they will be in once they are accepted into trunk.  Rebased commits will be shown after the new trunk
+  commits -- this is the same order in which users of the code will receive the changes if they are updating
+  their deployments.  Merged commits are shown at the time they were written, not at the time they became
+  publicly available in trunk.
+
+For these reasons, it is preferable to use rebase rather than merge to include trunk changes into your local
+repository.
+
+Regardless of whether you rebase or merge, neither of these is a "safe" operation -- you may make a mistake
+during the process, or encounter errors or conflicts.  So before starting, a simple way to be sure you can
+go back to your unmodified branch is to make a copy of the branch.  This assumes you are working on branch
+mychanges and want to save your work on branch mychanges_backup, and that you have a remote called upstream
+that points to the trunk repository:
+
+{{{
+# Check whether you have uncommitted changes
+git log
+
+# Commit any new and changed files
+git add ...
+git commit ...
+
+# Make a backup branch
+git checkout -b mychanges_backup
+
+# Switch back to the branch you want to update
+git checkout mychanges
+
+# Update your branch from trunk
+git pull --rebase upstream master:mychanges
 ==== Resolving Merge Conflicts ====
 If you encounter conflicts during the rebase, the conflicts will be tagged in the files with: