Unix 103: probably all of the topics
[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 (notice the F<.git>
96 directory that has been created)
97
98 =item 2.
99
100 C<git add> F<file> to tell git to start tracking the contents of
101 F<file>. You could also add multiple files, or say C<git add .> if you have
102 a larger group of files that you want to start tracking under version control.
103
104 =item 3.
105
106 C<git commit> will start up a text edit to let you leave an initial commit
107 message. In this message you will probably want to explain the purpose of the
108 repository, or explain the purpose of any initial files in it.
109
110 =item 4.
111
112 Now edit the file or files that git is tracking.
113
114 =item 5.
115
116 C<git add> F<file> to tell git that you like the changes you've made
117
118 =item 6.
119
120 C<git commit> and remember to leave a meaningful commit message
121
122 =item 7.
123
124 C<git log> to see the history of what you've done.
125
126 =item 8.
127
128 Goto 4.
129
130 =back
131
132 =head3 Subversion
133
134 Someone will have to help me out here.
135
136 =cut
137
138 This is really all that you need if you are working alone and want a tool to
139 keep track of metadata for you. This way when you wake up the next morning, you
140 can remember why you made those particular changes to that file last night.
141 (Assuming you knew what you were doing in the first place!)
142
143 =head2 Slightly More Advanced Usage
144
145 Making changes to your project and telling git about them is fine, but
146 sometimes you want git to tell I<you> things about your project. First, a
147 couple of definitions that are specific to git will have to be covered.
148
149 =head3 Git Definitions
150
151 =over
152
153 =item Working Directory
154
155 When you make changes to files in your respository, you are editing the
156 I<Working Directory>. Any changes will always be relative to your working
157 directory, and any playing with branch operations requires a clean working
158 directory.
159
160 =item Index
161
162 When you add files with C<git add>, they get into the I<index>. Only changes
163 which have been added to the index will be included in a commit. You can see
164 a diff of the changes in the index using the command C<git diff --cached>.
165
166 =back
167
168 =head3 Get oriented with C<git status>
169
170 To find out which files have been changed, which ones have been added, and
171 which branch you are on, use the C<git status> command. It's important to note
172 that only changes that are explicitly added will be included in a commit.
173 C<git status> will show this.
174
175 =head3 Compare two files with C<git diff>
176
177 Typing C<git diff> at any time will print the difference between the latest
178 commit in the repository and what is in the working directory. When changes are
179 added to the index, it will show the differences between the working directory
180 and the index. To see the differences between the I<index> and the latest
181 commit, type C<git diff --cached>.
182
183 =head3 Checking out old versions of files with C<git checkout>
184
185 The C<git checkout> command is used for checking out different versions of
186 files or for switching branches (which we will cover later). By default
187 issuing C<git checkout F<file>> will update F<file> using the contents of the
188 index. Alternatively C<git checkout I<version> F<file>> will update F<file>
189 using the contents from I<version>, which can be a commit.
190
191 E.G. C<git checkout HEAD^ hello.c>
192
193 =head2 More Advanced Usage
194
195 Some less common or more tool-specific commands.
196
197 =head3 More advanced output from git log.
198
199 You can see more than just author information and commit messages from
200 C<git log>. The C<--stat> option will give what is called a diffstat, showing
201 you which files have been changed. The C<-p> option, for patch, will output a
202 patch representing each commit.
203
204 =head3 Branches
205
206 Branching is as easy as C<git branch some-branch>. Use C<git checkout> to
207 switch branches. Branches are good for expermients or seperate topics on the
208 same code base. If an experiment is successful, you can merge it back into your
209 I<master> branch with
210  git checkout master
211  git merge some-branch
212
213 =head3 Inspecting History: Since when?
214
215 What has happened since the last three commits? C<git log HEAD^^^.. F<file>>
216 which is the same as C<git log HEAD~3.. F<file>>.
217
218 =head3 Searching Through your Code
219
220 You can search every file tracked by git in your current directory for a
221 regular expression pattern using C<git grep "pattern">.
222
223 =head2 Sharing Repositories
224
225 Without VCS, sharing development of source code would be almost impossible.
226
227 =head3 Merge Conflicts
228
229 The biggest headache when you merge someone else's code is the conflicts that
230 can arise!
231
232 =head2 Disclaimer
233
234 There are a lot of really good tutorials out there. This tutorial can't hope to
235 be able to replicate them. It's merely trying to get you bootstrapped and
236 comfortable with the idea of version control, so that you can learn more on
237 your on. A starting point, if you will.
238
239 =head2 About the Authors (when they wrote this)
240
241 This document is maintained and copyright The University of Waterloo Computer
242 Science Club 2009 and is released under the terms of the Artistic Liscence
243 version 2.0 available at L<http://www.perlfoundation.org/artistic_license_2_0>.
244
245 =head3 Kyle Spaans (kspaans@student.math.uwaterloo.ca)
246
247 A 3rd year Computational Math student, Kyle has been in and around the CSC
248 since his first term at Waterloo. He's been using Linux for years now, and
249 thinks the command line and command line-based tools are important for every
250 *nix user to know.