DragonFly BSD

TypicalGitUsage

Mastering the DragonFly git repository

  1. TypicalGitUsage
  2. Mastering the DragonFly git repository
    1. Clone the repository
    2. Prepare patches
      1. Example
    3. Working with branches
    4. Push your work upstream

Clone the repository

First you go in your work directory and clone the DragonFly repository. While crater is the official repo, you are urged to use one of our (generally much faster) mirrors instead. 

> git clone -o chlamydia git://chlamydia.fs.ei.tum.de/dragonfly.git

If you are a developer, you should create a remote entry for pushing to crater:

> git remote add crater ssh://crater.dragonflybsd.org/repository/git/dragonfly.git

Clone creates remote-tracking branches for all branches in the parent repo and creates a local master branch from the remote master branch.

> git branch -a


* master
  chlamydia/DragonFly_RELEASE_1_10
  chlamydia/DragonFly_RELEASE_1_12
  chlamydia/DragonFly_RELEASE_1_2
  chlamydia/DragonFly_RELEASE_1_4
  chlamydia/DragonFly_RELEASE_1_6
  chlamydia/DragonFly_RELEASE_1_8
  chlamydia/DragonFly_RELEASE_2_0
  chlamydia/HEAD
  chlamydia/master
  chlamydia/repo/hooks
  chlamydia/vendor/ATHEROS
  [...]
  chlamydia/vendor/ZLIB

Prepare patches

If you (as a non-developer) made some changes to the DragonFly source and want to get them included in the main repository, send your patches to submit@lists.dragonflybsd.org. git assists you in creating patches which are easy to handle for the developers.

Example

Note: The change in this example is completely useless, it only serves demonstration purposes!

At first edit the files you want to change:

> vim README

Then review your changes with git diff:

> git diff
diff --git a/README b/README
index 495a262..6a95d1f 100644
--- a/README
+++ b/README
@@ -59,7 +59,7 @@ lib           System libraries

 libexec                System daemons.

-nrelease       Framework for building the ***live*** CD image.
+nrelease       Framework for building the ***live CD*** image.

 sbin           System commands.

If you are satisfied with your changes, commit them. Note: The first line of your commit message should describe your change in a small sentence. Add more details after one newline.

> git commit -a
".git/COMMIT_EDITMSG" 10L, 342C written                                                                              
Created commit cbb871b: Change parentheses
 1 files changed, 1 insertions(+), 1 deletions(-)

Now you can use git format-patch to generate a patch file. This file is ready for submission to submit@. git format-patch will generate one file for every commit you did.

> git format-patch origin
0001-Change-parentheses.patch
> cat 0001-Change-parentheses.patch
From cbb871b4588c695f000bc701b4f3c16a0a518991 Mon Sep 17 00:00:00 2001
From: Matthias Schmidt <matthiasdragonflybsd.org>
Date: Tue, 2 Dec 2008 09:54:47 +0100
Subject: [PATCH] Change parentheses


---
 README |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)



diff --git a/README b/README
index 495a262..6a95d1f 100644
--- a/README
+++ b/README
@@ -59,7 +59,7 @@ lib           System libraries.

 libexec                System daemons.

-nrelease       Framework for building the ***live*** CD image.
+nrelease       Framework for building the ***live CD*** image.     

 sbin           System commands.
-- 
1.6.0.2

Attach the generated files to a mail and submit it. Write some lines about your intention and why you changed what ...

Working with branches

It is not recommended to work directly in your master branch, except maybe for one-liners. Branches in git are very cheap, so just keep your master branch pure, and always work on a different local branch.

Say you want to work on a simple change. Just create a temporary branch, make the change and commit it.

> git checkout -b work      # you're now in the work branch
> vim what/ever.c
> git commit -a

Now, you can switch back to master , merge in the changes in your work branch and push away:

> git checkout master      # you're now in the master branch
> git merge work           # now master has your changes

Afterwards, you may (or not, if you want to do further development) want to delete the work branch by

> git branch -d work

For more complex changes, you probably want to create a longer-lived branch. For example

> git checkout -b myfeature

You can work in the myfeature branch until your feature is ready. You can commit there as often as you like. If your work goes on for a significant amount of time, you will want to merge with the upstream master from time to time. It is recommended that you use git rebase, so that the merge points won't show up in the repo history on crater (they don't really add much information). For this, you'd do:

> git checkout master
> git pull
> git checkout myfeature
> git rebase master

Push your work upstream

When you judge that your code is ready for inclusion in mainline, you can merge it into your local master branch and push away:

> git checkout master
> git merge myfeature
> git push crater

as the command will not push any branch that is not in the remote repository.