1.\" 2.\" Copyright (c) 2008 3.\" The DragonFly Project. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 3. Neither the name of The DragonFly Project nor the names of its 16.\" contributors may be used to endorse or promote products derived 17.\" from this software without specific, prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $DragonFly: src/share/man/man7/development.7,v 1.12 2008/07/27 22:23:42 thomas Exp $ 33.\" 34.Dd August 6, 2009 35.Dt DEVELOPMENT 7 36.Os 37.Sh NAME 38.Nm development 39.Nd quick starter for development with the DragonFly codebase 40.Sh DESCRIPTION 41.Dx 42uses the 43.Xr git 1 44distributed revision control system. 45If it is not already on the system, it needs to be installed via 46.Xr pkgsrc 7 47.Pa ( /usr/pkgsrc/devel/scmgit ) . 48.Pp 49The 50.Sx EXAMPLES 51section gives initial information to get going with development on 52.Dx . 53Please refer to the 54.Xr git 1 55manual pages and other related documents for further information on git's 56capabilities and how to use them. 57The 58.Sx SEE ALSO 59section below has some links. 60.Pp 61For information on how to build the 62.Dx 63system from source code, see 64.Xr build 7 . 65For information on how to build the LiveCD, LiveDVD or thumb drive image, see 66.Xr release 7 . 67.Sh EXAMPLES 68A fresh copy of the repository can be cloned anywhere. 69Note that the directory to clone into 70.Pa ( /usr/src 71in the following example) must not exist, so all previous work in this 72directory has to be saved and the directory be removed prior to cloning. 73Also note that while the main repository is on 74.Pa crater , 75it is recommended that one of the 76.Dx 77mirrors be used instead. 78.Pp 79Simple setup and updating of local repository is done using 80.Pa /usr/Makefile : 81.Bd -literal -offset 4n 82cd /usr 83make help # get help 84make git-clone # initial setup 85make git-update 86.Ed 87.Pp 88Somewhat finer control can be achieved using 89.Xr git 1 90directly. 91To clone the repository and check out the master branch (this will take 92some time): 93.Bd -literal -offset 4n 94cd /usr 95git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src 96cd src 97.Ed 98.Pp 99The repository can be held up to date by pulling frequently (to set up a 100.Xr cron 8 101job, 102.Xr git 1 Ap s 103.Fl Fl git-dir 104option can be used): 105.Bd -literal -offset 4n 106cd /usr/src 107git pull 108.Ed 109.Pp 110It is not recommended to work directly in the master branch. 111To create and checkout a working branch: 112.Bd -literal -offset 4n 113git checkout -b work 114.Ed 115.Pp 116To create and checkout a branch of the 117.Dx 2.0 118release (called 119.Sy rel2_0 ) : 120.Bd -literal -offset 4n 121git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0 122.Ed 123.Pp 124Branches can be deleted just as easy: 125.Bd -literal -offset 4n 126git branch -d work 127.Ed 128.Pp 129After changes have been made to a branch, they can be committed: 130.Bd -literal -offset 4n 131git commit -a 132.Ed 133.Pp 134.Xr git-commit 1 Ap s 135.Fl m 136and 137.Fl F 138options can be used to specify a commit message on the command line or read 139it from a file, respectively. 140.Pp 141Finally, branches can be merged with the (updated) master by using 142.Cm rebase : 143.Bd -literal -offset 4n 144git checkout master 145git pull 146git checkout work 147git rebase master 148.Ed 149.Sh VENDOR IMPORTS 150When importing vendor sources, make sure that you don't import 151too many unnecessary sources. 152Especially test suites that are not used by the 153.Dx 154build are good candidates for being stripped away. 155These instructions assume that you have already extracted 156the source package into its final directory and that they are 157trimmed appropriately. 158.Pp 159.Em \&Do not change the vendor sources before importing them 160on the vendor branch! 161Necessary changes to the vendor sources can be applied to 162.Pa master 163after the import. 164.Pp 165For the following commands, we will import the imaginary package 166.Nm foo-2.3 167into 168.Pa /usr/src/contrib/foo . 169If this is the first import of 170.Nm foo , 171you will have to choose the name of the vendor branch. 172Customarily, this will be 173.Pa vendor/FOO . 174However, if you intend to maintain multiple vendor sources for the 175same package 176.Em concurrently , 177you should choose a branch name which includes part of the version, 178i.e.\& 179.Pa vendor/FOO2 . 180.Pp 181As a first step, we trick git to work on the vendor branch instead of on 182.Pa master . 183Be careful, since after issuing this command all your commits will go to the 184vendor branch, but you will commit 185.Em the whole working tree 186and not just the vendor sources! 187Thus you have to specify the exact directory for 188.Li git commit . 189In order to commit, you will have to add the new sources first. 190.Bd -literal -offset 4n 191git symbolic-ref HEAD refs/heads/vendor/FOO 192git add contrib/foo 193git commit -m "Import foo-2.3" contrib/foo 194.Ed 195.Pp 196With these commands we have imported the vendor sources on their own branch. 197In the next step, we merge the vendor branch into master. 198.Bd -literal -offset 4n 199git checkout master 200git merge vendor/FOO 201.Ed 202.Pp 203Now you are free to change the sources in contrib/foo, since you are 204back on the 205.Pa master 206branch. 207The first thing to do is to add 208.Pa README.DRAGONFLY 209and 210.Pa README.DELETED . 211The former documents how the imported sources can be obtained, including 212a checksum of the tarball. 213The latter lists all files and directories that have been removed from the 214source package. 215You should use the 216.Pa /usr/src/tools/tools/genreadmedeleted/genreadmedeleted 217shell script to generate this file. 218Commit the 219.Pa README Ns s 220first, then commit your local changes to the sources: 221.Bd -literal -offset 4n 222git add contrib/foo/README.D* 223git commit -m "foo: add our READMEs" 224.Ed 225.Pp 226Finally, push master and the vendor branch to crater: 227.Bd -literal -offset 4n 228git push crater master vendor/FOO 229.Ed 230.Sh SEE ALSO 231.Xr git 1 Pq Pa pkgsrc/devel/scmgit , 232.Xr build 7 , 233.Xr committer 7 , 234.Xr release 7 235.Rs 236.%T "Git User's Manual" 237.%O "http://www.kernel.org/pub/software/scm/git/docs/user-manual.html" 238.Re 239.Rs 240.%T "Git Magic" 241.%O "http://www-cs-students.stanford.edu/~blynn/gitmagic/" 242.Re 243.Sh HISTORY 244The 245.Nm 246manual page was originally written by 247.An Matthew Dillon Aq dillon@FreeBSD.org 248and first appeared 249in 250.Fx 5.0 , 251December 2002. 252It was rewritten when 253.Dx 254switched to 255.Xr git 1 . 256