Creating a version control repository
From Second Life Wiki
This article is intended as a beginner's guide to setting up and using a version control repository.
Contents |
Introduction
If you make extensive changes to the source download packages, it is easy to lose track of what files you changed, as well as remembering what you did and when. A version control repository keeps track of these file changes for you automatically, and allows you to track your changes over time and to revert to a previous state if you don't like the way a project is going.
For information about Linden Lab's repository refer to the article Version control repository. This article is intended for programmers already experienced with using repositories.
Version control for beginners: Mercurial
Many of the developers on SLDev recommend starting out by using Mercurial and the compressed packages on the source downloads page. Although this does not provide a direct one-to-one link to the official Linden Lab Subversion repository, it is easier to get started by learning from a local repository.
Preparing to use Mercurial
Generally all you need to do to get started is to:
- Download and install Mercurial on your system
- Specify a username and email to use in your branches
- Set up ignore files for items you don't want to track
Identifying yourself to Mercurial
Mercurial is built with the intent that you will share your work with others, and as you create new branches it adds comments and your name and email to each change. If you don't specify this information, it will use the login account name and your computer's DNS name to auto-generate an email address which will likely be wrong.
Specifying your name and email is done with a SET command, added to your home directory login script, or with a file named ".hgrc" in your home directory:
# This is a Mercurial configuration file. [ui] username = Firstname Lastname <email.address@domain.net>
Windows users can specify these environment variables with these steps:
- Open Control Panels, and select Classic View (if not already set)
- Open System, and click on the Advanced tab
- At the bottom, click the "Environment Variables" button
- At the top of the new window, under "User variables for..", Click "New", and add the variables:
- HGUSER - Your username ("John Smith")
- EMAIL - Your email address ("jsmith@foo.com")
Setting up an ignore file
There are many files produced in the process of compiling which are temporary and which you will never directly modify yourself. Hence there is no reason to clutter up the repository with these files, and they will make it seem like more files are changing than you are actually editing. Mercurial can be told to ignore these files and not track their status using an .hgignore file placed in the root of the linden directory you are versioning:
.hgignore file placed in \linden:
# Ignore file constructed using Visual Studio 2003 # and viewer release source 1_20_15. This ignore # file may need additions for other compilers and # future client releases. # use glob syntax. syntax: glob # Ignore this ignore file and hgrc if present # .hgignore .hgrc # Ignore VS2003 compiler project/solution files *.vcproj *.sln # Ignore VS2003 compiler temporary files for 1_20_15 *.ilk *.res *.pyn *.pyc *.ncb *.suo *.pch *.obj *.pdb *.idb *.lib BuildLog.* *.map # Ignore compiled binaries # *.dll *.exe # Ignore everything in linden libraries zipfile # Ignore 3rd party libraries (fmod, quicktime, ..) # LICENSE-libraries-win32.txt libraries\* indra\newview\app_settings\mozilla\* indra\newview\app_settings\mozilla_debug\* indra\newview\fonts\* # Ignore build artifacts produced by compiler. # # * Do not attempt to modify these files, these # are overwritten with every compile. # indra\lscript\lscript_compile\lex_yy.cpp indra\lscript\lscript_compile\ytab.cpp indra\lscript\lscript_compile\ytab.h indra\lscript\lscript_compile\ytab.output # # To edit the default viewer preferences file, # the original is located in: # linden\etc\message.xml # # To edit the viewer protocol definitions file, # the original is located in: # linden\scripts\messages\message_template.msg # indra\newview\app_settings\message.xml indra\newview\app_settings\message_template.msg
Initializing a new repository
The first step to using a repository is to create the initial state of the repository. This takes a snapshot of all source files as they were when you first downloaded and unzipped the packages, and then all changes you make after this point refer back to this state.
- Create a source working directory, without spaces in the name
- From a command line prompt go into this path until you see the \linden\ directory
- Initialize the repository using the entire indra directory tree:
- hg init linden
- cd linden
- hg add
- hg commit
When it commits it opens up a text editor (such as Notepad on Windows) where you type a comment about this commit at the very top. To complete the commit, save the file and exit, whether or not you type a description; if you just close the editor without saving, the repository changes will not commit.
Multiple separate repositories
For each source release, you use Mercurial to create a separate repository for each one, each segregated by directory name.
So rather than having one huge version control library containing every version of the source for all time (as with the Linden SVN) instead each release gets its own Mercurial repository on your local computer.
To work with the example repository created above, you need to be inside the "linden" directory for Mercurial to find the repository associated with this directory:
C:\SL_Viewer_Builds\1_20_15>hg log abort: There is no Mercurial repository here (.hg not found)! C:\SL_Viewer_Builds\1_20_15>cd linden C:\SL_Viewer_Builds\1_20_15\linden>hg log changeset: 0:(hex-ident) tag: tip user: (Your name) date: (Commit date) summary: (Your comment)
(This article is a work in progress by someone without a lot of experience with repositories. More info and notes will be added later.)
