UNIX 103: version control -- initial document
authorKyle Spaans <kspaans@student.math.uwaterloo.ca>
Sun, 28 Jun 2009 01:19:11 +0000 (21:19 -0400)
committerKyle Spaans <kspaans@student.math.uwaterloo.ca>
Sun, 28 Jun 2009 01:19:11 +0000 (21:19 -0400)
Starting out thoughts about what could go into this tutorial, as well
as some of the meat of it. Git and SVN will be used in the tutorial,
hopefully this is a smart choice. Someone will have to help me with the svn
side of things. I also hope it's reasonable to expect that this tutorial can be
at least a little tool-agnostic, and not just a ripoff of one of the many VCS
tutorials out there.

code-management.pod [new file with mode: 0644]

diff --git a/code-management.pod b/code-management.pod
new file mode 100644 (file)
index 0000000..2b04041
--- /dev/null
@@ -0,0 +1,150 @@
+=head1 UNIX 103: Code Project Management and Version Control
+
+Chances are you're in the Computer Science program. If so, or even if you are
+in Mathematics, it's likely that you're going to have to manage a project that
+involves some code. This can even be true for your non-Faculty of Math courses.
+Consider a document that contains an essay. The essay is probably mostly text
+and some images or data or references. If you consider just the text of the
+essay, it's a lot like code too. All of this data needs to be managed somehow.
+Version control software (VCS), sometimes also called source code management
+(SCM), is a powerful tool that lets you track the changes to your code over
+time (among other things). VCS is one of the tools you are most likely to
+encounter in the workplace if you get a job doing any kind of software
+development. This tutorial will attempt to be as tool-agnostic as possible to
+make it easy for you to learn any of a wide variety of VCSs. However, due to
+the vast differences in both interface and paradigm of VCS out there, this
+tutorial will focus on two specific programs: Git and Subversion (SVN).
+
+For more information and in-depth tutorials, see:
+
+=over
+
+=item Git
+
+L<http://git-scm.com/>
+
+=item Subversion
+
+L<http://subversion.tigris.org/>
+
+=back
+
+=head2 Terms and Definitions
+
+All VCS uses more or less the same ideas and works for things. We will explain
+them here.
+
+=over
+
+=item Repository
+
+=item Commit
+
+=item Diff
+
+Because version control works with plaintext data, the common currency is the
+I<diff>. It's a standard format that is both human and computer readable to
+show the differences between two files. See the C<diff> utility for more
+information, but often VCS have their own C<diff>.
+
+=item Patch
+
+A patch is actually just a diff. A I<patch> can be applied to a file to make
+the changes to that file that were described by the diff. See the C<patch>
+utility.
+
+=item History
+
+VCS gives you a I<history> of all of the commits to the repository. You can
+use the I<history> to generate patches to give to other people, or just look at
+diffs between two versions of a file.
+
+=item Branch
+
+=back
+
+=head2 Version Control in 30 Seconds
+
+The very basics that you would want to do with your tool.
+
+=head3 Git
+
+=over
+
+=item 1.
+
+C<git init> to initialize a directory as a git repository
+
+=item 2.
+
+C<git add> F<file> to tell git to start tracking the contents of
+F<file>. You could also add multiple files, or say C<git add .> if you have
+a larger group of files that you want to start tracking under version control.
+
+=item 3.
+
+C<git commit> will start up a text edit to let you leave an initial commit
+message. In this message you will probably want to explain the purpose of the
+repository, or explain the purpose of any initial files in it.
+
+=item 4.
+
+Now edit the file or files that git is tracking.
+
+=item 5.
+
+C<git add> F<file> to tell git that you like the changes you've made
+
+=item 6.
+
+C<git commit> and remember to leave a meaningful commit message
+
+=item 7.
+
+Goto 4.
+
+=back
+
+=head3 Subversion
+
+Someone will have to help me out here.
+
+=cut
+
+This is really all that you need if you are working alone and want a tool to
+keep track of metadata for you. This way when you wake up the next morning, you
+can remember why you made those particular changes to that file last night.
+(Assuming you knew what you were doing in the first place!)
+
+=head2 More Advanced Usage
+
+Topic branches, merging, git specifics?
+
+=head2 Sharing Repositories
+
+Without VCS, sharing development of source code would be almost impossible.
+
+=head3 Merge Conflicts
+
+The biggest headache when you merge someone else's code is the conflicts that
+can arise!
+
+=head2 Disclaimer
+
+There are a lot of really good tutorials out there. This tutorial can't hope to
+be able to replicate them. It's merely trying to get you bootstrapped and
+comfortable with the idea of version control, so that you can learn more on
+your on. A starting point, if you will.
+
+=head2 About the Authors (when they wrote this)
+
+This document is maintained and copyright The University of Waterloo Computer
+Science Club 2009 and is released under the terms of the Artistic Liscence
+version 2.0 available at L<http://www.perlfoundation.org/artistic_license_2_0>.
+
+=head3 Kyle Spaans (kspaans@student.math.uwaterloo.ca)
+
+A 3rd year Computational Math student, Kyle has been in and around the CSC
+since his first term at Waterloo. He's been using Linux for years now, and
+thinks the command line and command line-based tools are important for every
+*nix user to know.