Docstring update: documented parameters and exceptions of conf.read().
[public/pyceo-broken.git] / docs / GIT-HOWTO
1 Getting the Source
2 ------------------
3
4 The sources for this project are in a git repository. Git is a distributed
5 revision control tool originally created by Linus Torvalds to track the Linux
6 kernel tree. With git, there is generally no central repository that everyone
7 commits their changes to. Instead, collaboration is done by "pulling" changes
8 from the repositories of other contributors.
9
10 When you check out the sources, you will get the entire history along with
11 the latest version. You also don't need any special permissions (e.g. UNIX
12 group membership) to clone a repository and start making changes.
13
14 To get started, you must first decide whether you wish to use git or cogito
15 as your front-end of choice. For the most part you can use them
16 interchangeably, but you will probably want to choose one and stick to it.
17 Cogito will provide you with an interface that looks and acts slightly more
18 like CVS and Subversion than native git does.
19
20 In order to get a copy of the sources, you need to clone an existing
21 repository. To do this, type a command such as:
22
23     git clone /users/git/mspang/csc.git
24
25 Or, with cogito:
26
27     cg clone /users/git/mspang/csc.git
28
29 This will give you the latest copy of my source tree. Once other CSC
30 members publish their repositories, you can clone your tree from theirs
31 instead if you so desire. You do not need to run this command more than
32 once, and you are not limited to pulling changes from the repository
33 you cloned from.
34
35
36 Making Changes
37 --------------
38
39 Now that you have your own repository, you can start making changes. You
40 may can add, update, or delete files as necessary and then commit these
41 changes to your local repository. Then you can make these changes available
42 to others. Read the documentation to learn more about basic git usage.
43
44 For a tutorial on plain git, see [1] generally and [2] if you are used to
45 CVS. For a tutorial on cogito, see [3] if you are used to CVS and [4] if
46 you are used to Subversion.
47
48 The manpages for git and cogito commands are also invaluable, use `man
49 git-foo` or `man cg-foo` to retrieve them, or look online at [5] and [6].
50
51 Finally, if you're interested in how git works internally, see [7] for
52 documentation of the "core" commands, and [8] for documentation of the
53 repository format. 
54
55 [1] http://www.kernel.org/pub/software/scm/git/docs/tutorial.html
56 [2] http://www.kernel.org/pub/software/scm/git/docs/cvs-migration.html
57 [3] http://git.or.cz/course/cvs.html
58 [4] http://git.or.cz/course/svn.html
59 [5] http://www.kernel.org/pub/software/scm/git/docs/
60 [6] http://www.kernel.org/pub/software/scm/cogito/docs/
61 [7] http://www.kernel.org/pub/software/scm/git/docs/core-tutorial.html
62 [8] http://www.kernel.org/pub/software/scm/git/docs/repository-layout.html
63
64
65 Setting up a Public Repository
66 ------------------------------
67
68 If you make changes, you will probably want to share them with the other
69 contributors. This is especially true if you are not on the CSC
70 Systems Committee, since in that case you can't deploy your changes
71 yourself. Even if you are a committee member, confusion is sure to follow
72 if you install an updated package and don't publish your updates.
73
74 The only thing other people need to fetch your changes into their own
75 repository is the location of your repository and read access to it. With
76 that they can use `git fetch` or `cg fetch` to retrieve your changes.
77
78 If you will be making lots of changes, it may be a good idea to put a link
79 to your repository (or even an actual repository) in /users/git. To do this
80 you will need to be added to the git group. Email systems-committee and
81 someone will add you. It doesn't matter whether your repository itself is
82 in /users/git or just a symlink, as it will count toward your quota regardless.
83
84 If you will be building and installing the package (i.e. you are the
85 Sysadmin or a Systems Committee member) then please do create a public
86 repository in /users/git so the next person who installs can incorporate
87 all of your changes.
88
89 If you want to make changes but not publish them immediately after
90 each commit, create a second repository and "push" your changes
91 into your public repository. Refer to the Internet for more details.