[dragonfly.git] / share / man / man7 / development.7

.\"
.\" Copyright (c) 2008
.\"	The DragonFly Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $DragonFly: src/share/man/man7/development.7,v 1.12 2008/07/27 22:23:42 thomas Exp $
.\"
.Dd December 1, 2008
.Dt DEVELOPMENT 7
.Os
.Sh NAME
.Nm development
.Nd quick starter for development with the DragonFly codebase
.Sh DESCRIPTION
.Dx
uses the
.Xr git 1
distributed revision control system.
If it is not already on the system, it needs to be installed via
.Xr pkgsrc 7
.Pa ( /usr/pkgsrc/devel/scmgit ) .
.Pp
The
.Sx EXAMPLES
section gives initial information to get going with development on
.Dx .
Please refer to the
.Xr git 1
manual pages and other related documents for further information on git's
capabilities and how to use them.
.Pp
For information on how to build the
.Dx
system from source code, see
.Xr build 7 .
For information on how to build a LiveCD, see
.Xr release 7 .
.Sh EXAMPLES
A fresh copy of the repository can be cloned anywhere.
Note that the directory to clone into
.Pa ( /usr/src
in the following example) must not exist, so all previous work in this
directory has to be saved and the directory be removed prior to cloning.
.Pp
To clone the repository and check out the master branch (this will take
some time):
.Bd -literal -offset 4n
cd /usr
git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src
cd src
.Ed
.Pp
The repository can be held up to date by pulling frequently (to set up a
.Xr cron 8
job,
.Xr git 1 Ap s
.Fl Fl git-dir
option can be used):
.Bd -literal -offset 4n
cd /usr/src
git pull
.Ed
.Pp
It is not recommended to work directly in the master branch.
To create and checkout a working branch:
.Bd -literal -offset 4n
git checkout -b work
.Ed
.Pp
To create and checkout a branch of the
.Dx 2.0
release (called
.Sy rel2_0 ) :
.Bd -literal -offset 4n
git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0
.Ed
.Pp
Branches can be deleted just as easy:
.Bd -literal -offset 4n
git branch -d work
.Ed
.Pp
After changes have been made to a branch, they can be committed:
.Bd -literal -offset 4n
git commit -a
.Ed
.Pp
.Xr git-commit 1 Ap s
.Fl m
and
.Fl F
options can be used to specify a commit message on the command line or read
it from a file, respectively.
.Pp
Finally, branches can be merged with the (updated) master by using
.Cm rebase :
.Bd -literal -offset 4n
git checkout master
git pull
git checkout work
git rebase master
.Ed
.Sh SEE ALSO
.Xr git 1 Pq Pa pkgsrc/devel/scmgit ,
.Xr build 7 ,
.Xr committer 7 ,
.Xr release 7
.Sh HISTORY
The
.Nm
manual page was originally written by
.An Matthew Dillon Aq dillon@FreeBSD.org
and first appeared
in
.Fx 5.0 ,
December 2002.
It was rewritten when
.Dx
switched to
.Xr git 1 .
Commit	Line	Data
984263bc	1	.\"
a63d9f6f SW	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	.\"
71bdc883	32	.\" $DragonFly: src/share/man/man7/development.7,v 1.12 2008/07/27 22:23:42 thomas Exp $
984263bc	33	.\"
a63d9f6f	34	.Dd December 1, 2008
984263bc MD	35	.Dt DEVELOPMENT 7
	36	.Os
	37	.Sh NAME
	38	.Nm development
a63d9f6f	39	.Nd quick starter for development with the DragonFly codebase
984263bc	40	.Sh DESCRIPTION
8c1a5cc4	41	.Dx
a63d9f6f SW	42	uses the
	43	.Xr git 1
	44	distributed revision control system.
	45	If it is not already on the system, it needs to be installed via
	46	.Xr pkgsrc 7
	47	.Pa ( /usr/pkgsrc/devel/scmgit ) .
984263bc	48	.Pp
a63d9f6f SW	49	The
	50	.Sx EXAMPLES
	51	section gives initial information to get going with development on
	52	.Dx .
	53	Please refer to the
	54	.Xr git 1
	55	manual pages and other related documents for further information on git's
	56	capabilities and how to use them.
	57	.Pp
	58	For information on how to build the
8c1a5cc4	59	.Dx
a63d9f6f SW	60	system from source code, see
	61	.Xr build 7 .
	62	For information on how to build a LiveCD, see
	63	.Xr release 7 .
	64	.Sh EXAMPLES
	65	A fresh copy of the repository can be cloned anywhere.
	66	Note that the directory to clone into
	67	.Pa ( /usr/src
	68	in the following example) must not exist, so all previous work in this
	69	directory has to be saved and the directory be removed prior to cloning.
	70	.Pp
	71	To clone the repository and check out the master branch (this will take
	72	some time):
984263bc MD	73	.Bd -literal -offset 4n
984263bc MD	74	cd /usr
a63d9f6f SW	75	git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src
a63d9f6f SW	76	cd src
984263bc MD	77	.Ed
984263bc MD	78	.Pp
a63d9f6f SW	79	The repository can be held up to date by pulling frequently (to set up a
	80	.Xr cron 8
	81	job,
	82	.Xr git 1 Ap s
	83	.Fl Fl git-dir
	84	option can be used):
984263bc MD	85	.Bd -literal -offset 4n
984263bc MD	86	cd /usr/src
a63d9f6f	87	git pull
984263bc MD	88	.Ed
984263bc MD	89	.Pp
a63d9f6f SW	90	It is not recommended to work directly in the master branch.
a63d9f6f SW	91	To create and checkout a working branch:
984263bc	92	.Bd -literal -offset 4n
a63d9f6f	93	git checkout -b work
984263bc MD	94	.Ed
984263bc MD	95	.Pp
a63d9f6f SW	96	To create and checkout a branch of the
	97	.Dx 2.0
	98	release (called
	99	.Sy rel2_0 ) :
984263bc	100	.Bd -literal -offset 4n
a63d9f6f	101	git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0
984263bc	102	.Ed
984263bc	103	.Pp
a63d9f6f	104	Branches can be deleted just as easy:
984263bc	105	.Bd -literal -offset 4n
a63d9f6f	106	git branch -d work
984263bc MD	107	.Ed
984263bc MD	108	.Pp
a63d9f6f	109	After changes have been made to a branch, they can be committed:
95b3720c	110	.Bd -literal -offset 4n
a63d9f6f	111	git commit -a
95b3720c HP	112	.Ed
95b3720c HP	113	.Pp
a63d9f6f SW	114	.Xr git-commit 1 Ap s
	115	.Fl m
	116	and
	117	.Fl F
	118	options can be used to specify a commit message on the command line or read
	119	it from a file, respectively.
95b3720c	120	.Pp
a63d9f6f SW	121	Finally, branches can be merged with the (updated) master by using
a63d9f6f SW	122	.Cm rebase :
984263bc	123	.Bd -literal -offset 4n
a63d9f6f SW	124	git checkout master
	125	git pull
	126	git checkout work
	127	git rebase master
984263bc	128	.Ed
984263bc	129	.Sh SEE ALSO
a63d9f6f	130	.Xr git 1 Pq Pa pkgsrc/devel/scmgit ,
984263bc	131	.Xr build 7 ,
71bdc883	132	.Xr committer 7 ,
a63d9f6f	133	.Xr release 7
984263bc MD	134	.Sh HISTORY
	135	The
	136	.Nm
	137	manual page was originally written by
	138	.An Matthew Dillon Aq dillon@FreeBSD.org
	139	and first appeared
	140	in
	141	.Fx 5.0 ,
	142	December 2002.
a63d9f6f SW	143	It was rewritten when
	144	.Dx
	145	switched to
	146	.Xr git 1 .