UNIX 103: more progress on document
[kspaans/UnixTutorial] / code-management.pod
1 =head1 UNIX 103: Code Project Management and Version Control
2
3 Chances are you're in the Computer Science program. If so, or even if you are
4 in Mathematics, it's likely that you're going to have to manage a project that
5 involves some code. This can even be true for your non-Faculty of Math courses.
6 Consider a document that contains an essay. The essay is probably mostly text
7 and some images or data or references. If you consider just the text of the
8 essay, it's a lot like code too. All of this data needs to be managed somehow.
9 Version control software (VCS), sometimes also called source code management
10 (SCM), is a powerful tool that lets you track the changes to your code over
11 time (among other things). VCS is one of the tools you are most likely to
12 encounter in the workplace if you get a job doing any kind of software
13 development. This tutorial will attempt to be as tool-agnostic as possible to
14 make it easy for you to learn any of a wide variety of VCSs. However, due to
15 the vast differences in both interface and paradigm of VCS out there, this
16 tutorial will focus on two specific programs: Git and Subversion (SVN).
17
18 For more information and in-depth tutorials, see:
19
20 =over
21
22 =item Git
23
24 L<http://git-scm.com/>
25
26 =item Subversion
27
28 L<http://subversion.tigris.org/>
29
30 =back
31
32 =head2 Terms and Definitions
33
34 All VCS uses more or less the same ideas and works for things. We will explain
35 them here.
36
37 =over
38
39 =item Repository
40
41 The I<repository> is location where all of the data and meta data used by the
42 VCS is kept: your files, different versions of your files, extra logging data
43 that describes the changes, etc.  All actions performed by the VCS will happen
44 against the I<repository>.
45
46 =item History
47
48 VCS gives you a I<history> of all of the changes made to the repository. Useful
49 metadata like who made which changes to which files and when and why.
50
51 =item Diff
52
53 Because version control works with plaintext data, the common currency is the
54 I<diff>. It's a standard format that is both human and computer readable to
55 show the differences between two files. See the C<diff> utility for more
56 information, but often VCS have their own C<diff>.
57
58 =item Commit
59
60 A set of diffs get bundled into a I<commit> and saved in the repository's
61 history. The primary unit of currency in version control is the commit.
62
63 =item Patch
64
65 A patch is actually just a diff. A I<patch> can be applied to a file to make
66 the changes to that file that were described by the diff. See the C<patch>
67 utility.
68
69 =item Branch
70
71 A I<branch> is a copy of the contents of the repository. Branches can be used
72 to do non-linear development. That is, separate ideas or topics can be
73 developed in their own branches. Branches are great for doing experimental work
74 that you don't want to contaminate your main codebase with. Two branches of the
75 same code base will have identical ancestor commits somewhere in their
76 history.
77
78 =item Merge
79
80 Two branches can be I<merged> together. This will bring together the changes
81 from each branch into a single branch.
82
83 =back
84
85 =head2 Version Control in 30 Seconds
86
87 The very basics that you would want to do with your tool.
88
89 =head3 Git
90
91 =over
92
93 =item 1.
94
95 C<git init> to initialize a directory as a git repository
96
97 =item 2.
98
99 C<git add> F<file> to tell git to start tracking the contents of
100 F<file>. You could also add multiple files, or say C<git add .> if you have
101 a larger group of files that you want to start tracking under version control.
102
103 =item 3.
104
105 C<git commit> will start up a text edit to let you leave an initial commit
106 message. In this message you will probably want to explain the purpose of the
107 repository, or explain the purpose of any initial files in it.
108
109 =item 4.
110
111 Now edit the file or files that git is tracking.
112
113 =item 5.
114
115 C<git add> F<file> to tell git that you like the changes you've made
116
117 =item 6.
118
119 C<git commit> and remember to leave a meaningful commit message
120
121 =item 7.
122
123 Goto 4.
124
125 =back
126
127 =head3 Subversion
128
129 Someone will have to help me out here.
130
131 =cut
132
133 This is really all that you need if you are working alone and want a tool to
134 keep track of metadata for you. This way when you wake up the next morning, you
135 can remember why you made those particular changes to that file last night.
136 (Assuming you knew what you were doing in the first place!)
137
138 =head2 More Advanced Usage
139
140 Topic branches, merging, git specifics?
141
142 =head2 Sharing Repositories
143
144 Without VCS, sharing development of source code would be almost impossible.
145
146 =head3 Merge Conflicts
147
148 The biggest headache when you merge someone else's code is the conflicts that
149 can arise!
150
151 =head2 Disclaimer
152
153 There are a lot of really good tutorials out there. This tutorial can't hope to
154 be able to replicate them. It's merely trying to get you bootstrapped and
155 comfortable with the idea of version control, so that you can learn more on
156 your on. A starting point, if you will.
157
158 =head2 About the Authors (when they wrote this)
159
160 This document is maintained and copyright The University of Waterloo Computer
161 Science Club 2009 and is released under the terms of the Artistic Liscence
162 version 2.0 available at L<http://www.perlfoundation.org/artistic_license_2_0>.
163
164 =head3 Kyle Spaans (kspaans@student.math.uwaterloo.ca)
165
166 A 3rd year Computational Math student, Kyle has been in and around the CSC
167 since his first term at Waterloo. He's been using Linux for years now, and
168 thinks the command line and command line-based tools are important for every
169 *nix user to know.