Version 9 (modified by neverpanic (Clemens Lang), 8 years ago) (diff) |
---|
This page should contain information about how to work with git, specifically from the point of view of someone familiar with Subversion.
Common git
tasks while working with ports
To start:
svn checkout https://svn.macports.org/repository/macports/trunk/dports
becomes
git clone git@github.com:macports/ports.git
When you clone you will get the entire history of the ports tree, with the latest version being checked out in the filesystem.
After you make a change, you can run git status
and get something like this.
On branch master Your branch is up-to-date with 'origin/master'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: aqua/iTerm2/Portfile no changes added to commit (use "git add" and/or "git commit -a")
What this tells me, is that I've changed a Portfile, but not done anything.
After that, you can add the files that you want to add to your commit using git add aqua/iTerm2/Portfile
.
Now, git status
will look like:
On branch master Your branch is up-to-date with 'origin/master'. Changes to be committed: (use "git reset HEAD <file>..." to unstage) modified: aqua/iTerm2/Portfile
Then run git commit
and everything is set. On your machine. To push to github you then have to run git push
.
Common git
tasks while working with MacPorts base
Checking out a working copy
The source code of MacPorts itself is no longer managed in the same repository as all ports. Contrary to Subversion, checking out a sub-directory of a repository is not possible with Git. In order to avoid that all port maintainers have to clone the complete history of MacPorts base as well, the Subversion repository has been split into multiple separate repositories. MacPorts base is now available using
git clone git@github.com:macports/base.git # or git clone https://github.com/macports/base.git # if SSH does not work on your network
See the section on repository splitting during the export to get an overview of where a path in the old Subversion history is now available in Git.
Committing changes in your working copy
A fundamental difference between Subversion and Git working copies is that svn commit
by default commits all changes in your working copy, but git commit
by default commits none. Git uses a staging area called "index" that allows you to mark changes for inclusion in the next commit. To add changes to the next commit, use
git add <filename>...
git status
gives you an overview of the current index and your working copy. Additionally, it lists the commands to revert local uncommitted modifications (git checkout -- <filename>
) and to remove files from the next commit, but preserve the modifications in your working copy (git reset HEAD <filename>
).
Once you have chosen which files to include in your next commit using git add
, it is a good practice to review this list using
git status
and show the diff to be committed using
git diff --cached
If you are not satisfied with your changes, you can keep changing your files. Note that you will have to add any new modifications to the index using git add
again. Once you are satisfied with your change run
git commit
which prompts you for the commit message. See the section on commit messages in git for more information on git conventions and expectations in commit messages.
Because of Git's distributed nature, a commit on your local machine is not immediately available on the central server, like it was the case with Subversion. This means that you can continue to prepare further changes in additional commits before you publish your changes as a set. In fact, it is a very common practice in Git to do many small changes that are logically consistent in themselves and then publish them in one step.
If you have commit access, you can publish your commits using git push <remote-name> <branch-name>
. <remote-name>
is the name of the repository to which you want to push. The most common push target is the location you initially cloned, which is automatically named origin
. <branch-name>
is the name of the branch you want to push. The Git equivalent to Subversion's trunk
is called master
. In most cases you do not need to specify <remote-name>
or <branch-name>
:
git push
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
WIP
Repository split
WIP
Attachments (1)
-
commit-history-with-excessive-merging.png (345.7 KB) - added by neverpanic (Clemens Lang) 8 years ago.
Attach picture that shows the result of excessive merging
Download all attachments as: .zip