[MacPorts] WorkingWithGit modified

[MacPorts]

Page "WorkingWithGit" was changed by cal at macports.org
Diff URL: <https://trac.macports.org/wiki/WorkingWithGit?action=diff&version=8>
Revision 8
Comment: Explain updating your local copy and the pitfalls of merging and/or rebasing
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: WorkingWithGit
=========================================================================
--- WorkingWithGit (version: 7)
+++ WorkingWithGit (version: 8)
@@ -82,7 +82,57 @@
 
 
 == Common `git` tasks & notes about MacPorts' Subversion export ==
+=== Fetching the latest changes ===
+Git's equivalent to `svn update` is a little more complicated due to Git's distributed nature. Most of the complexity is not visible if you do not have commits in your working copy that have not been pushed yet. If both the local and the remote repository have changes (git calls them "diverged"), you will run into one of Git's core principles: Every commit has (at least) one parent commit, i.e. the commit history forms a directed acyclic graph.
+
+==== Background knowledge ====
+
+A picture is worth a thousand words:
+{{{
+ A --- B --- C ---- R1 ---- R2 ---- R3  <= origin/master
+              \
+               +--- L1 ---- L2          <= master
+}}}
+A, B and C are commits that are both in your local and in the remote repository. R1-3 are commits that have been pushed into the remote repository "origin"'s master branch while you were working. L1 and L2 are commits you prepared locally on your master branch. Git offers two different ways to bring R1-3 into your local branch:
+
+===== Merging =====
+A merge commit, created by `git merge`, is a commit that has multiple parents. If no conflict occurs, merge commits do not usually have a diff attached (i.e. they do not modify files). On conflict, merge commits contain the diff that resolves the conflict. In pictures:
+{{{
+ A --- B --- C ---- R1 ---- R2 ---- R3   <= origin/master
+              \                      \
+               +--- L1 ---- L2 ------ M  <= master
+}}}
+The new commit M is the merge commit and can be pushed back to origin. This preserves the information that work was done in parallel, but unfortunately tends to mess up the history graph. See the attached screenshot of a commit history that always merges. To avoid this, you can instead rebase your changes.
+
+===== Rebasing =====
+Rebasing commits rewrites their parent commit IDs and avoids the need for a merge commit. Running `git rebase origin/master` will take all commits in your local working copy that are not yet pushed and attach them after the end of `origin/master`, which yields this picture:
+{{{
+ A --- B --- C ---- R1 ---- R2 ---- R3   <= origin/master
+                                      \
+                                       L1' ---- L2'  <= master
+
+}}}
+Note that L1 and L2 have been modified by this operation; their commit IDs changed because of that. This new state can be pushed back to origin without the need for a merge commit, and the history graph will stay linear. '''We recommend that all developers rebase their changes rather than merge when conflicts occur during pushing.'''
+
+==== Putting the background knowledge into production ====
+First, get all new commits from the remote repository using `git fetch <remote-name>`, where `<remote-name>` identifies the repository from which you want to fetch and defaults to "origin":
+{{{
+git fetch
+}}}
+Then, rebase your local changes (if any) on top of any new changes in the remote repository and fix any conflicts that occur:
+{{{
+git rebase origin/master
+}}}
+
+Because these two operations are very common, Git offers a shorthand for them:
+{{{
+git pull --rebase
+}}}
+
+'''Warning:''' `git pull` without the `--rebase` flag is a shorthand for `git fetch && git merge origin/master`, which will automatically create a merge commit if it thinks that's necessary.
+
 === Commit messages === #commitmessages
 WIP
+
 === Repository split === #reposplit
 WIP
-------8<------8<------8<------8<------8<------8<------8<------8<--------

--
Page URL: <https://trac.macports.org/wiki/WorkingWithGit>
MacPorts <https://www.macports.org/>
Ports system for OS X

This is an automated message. Someone added your email address to be
notified of changes on 'WorkingWithGit' page.
If it was not you, please report to .