The department of $EMPLOYER for which I work is introducing Subversion as
its source control mechanism. Until now, we've been using the base case
of IBM ClearCase, approximately equivalent in power to networked RCS.
I just wrote this FAQ to help my colleagues learn the new system.
Unfortunately, I'm very familiar with the command-line client tools,
but not with Tortoise, so it's to some extent a matter of the one-eyed
leading the blind. I'd like a review of what follows from two points of
view, if possible: 1) Is it clear and correct? 2) Is it sufficiently
newbie-friendly, telling people what they need to know to get started
with Tortoise?
=====================================================================
This is draft 1. Please check it over for clarity (and if you find
errors, of course let me know). There will be later drafts.
1) I've got the TortoiseSVN client installed. How do I set up my
Subversion working directory so I can make changes to shared files?
Create a directory where you want to keep your working directories.
I recommend that this be directly under C: (or D: or whatever disk you
have room on), but it can be anywhere you like. Open its parent directory
(C:, for example) in the Windows Explorer. Then right-click on your
new directory and choose SVN Checkout. A dialogue box will appear.
Enter the URL of the Subversion repository [details to follow] in the
"URL of repository" box. The checkout directory will be set for you
automatically. Click OK. Another box will pop up listing all the files
being loaded to your system. Wait a long time while everything from
the repository is copied to your system.
2) Okay, all set. Now I want to check out a file so I can start working
on it.
There is nothing to do. Just open the file in your editor and begin
making changes. All the files should be writable already.
3) I need to hijack a file because a colleague is working on it.
If possible, get the colleague to commit their changes first. Then do
an update so you can see those changes. But if not, just open the file
in your editor and make your changes. Any discrepancies will be fixed
later when you commit your changes, or you can just revert them if they
are only temporary.
4) I want to update my working directory to reflect what's out on
the server.
Right click on a directory in Windows Explorer, either your main working
directory if you want to update everything, or a subdirectory of it to
just update some things. Choose SVN Update. A dialogue box will show
you which files are being updated. If any of them are shown in red in
the dialogue box, there are conflicts (see below), and you will need to
resolve them.
5) Okay, I'm done making changes to one or more files. Now what?
Unless you know that your changes don't affect anybody else right now,
DO A BUILD FIRST and fix any errors. Then choose a directory that
includes all your changed files (it can be the main working directory
or one further down in the tree), right-click, and choose SVN Commit.
A dialogue box will appear.
There will be a number of files listed in this dialogue box, representing
the files that have been changed or added since the last commit.
Make sure that all the correct files, and only the correct files,
are checked. If not enough files are shown, click Cancel and try again
further up the directory tree.
Type text into the Message box explaining the purpose of this change.
Click OK. A dialogue box will track the progress of the commit.
All changes to all files will be committed simultaneously or will all fail
to commit. If the commit succeeds, the version number of the repository
will be increased by 1. (Individual files do not have separate version
numbers in Subversion).
6) Commit failed! What now??
If you are modifying a file that has been modified by someone else, the
file will appear in red in the dialogue box. The commit will fail and
your file will be altered. In this case, you should open the file in
an editor and look for the strings "<<<<" and ">>>>". These mark places
in which the file was changed in two inconsistent ways. Use the editor
to fix up the problem, including getting rid of those special strings.
Build or otherwise test the file for correctness.
Now you must instruct Subversion that the conflict has been resolved.
Right-click on the repaired file and choose TortoiseSVN / Resolved.
Click OK and try the commit process again. If it fails again, you
probably forgot to mark the file as resolved, or there are other files
whose conflicts have not yet been resolved.
7) I want to add a file to Subversion.
Right click on the file and choose TortoiseSVN / Add. This will mark
the file to be added at the next commit. You don't actually need to
do this, because new files will be shown in the commit list anyway,
but one that has been marked for addition will already appear checked.
8) I want to rename a file.
Right click on the file and choose TortoiseSVN / Rename. Type in the
new name. The rename will happen at once locally, and will be sent to
the server at the next commit. DO NOT USE simple Rename, or Subversion
will get confused. Renaming directories uses the same procedure as
renaming single files.
9) I want to rename a file to mark it not to be used any more.
Delete it instead. Right click on the file and choose TortoiseSVN
/ Delete. The file will not be deleted at once locally, but on the
next commit. DO NOT USE simple delete, or the file will reappear after
the next update. You can delete whole directories in the same way if
they are not being used any more.
10) Oopsie. I need a deleted file back again.
Right-click on the directory containing the deleted file, and choose
TortoiseSVN / Show log. Scroll down to the change that deleted the file.
(You did write a commit message making it easy to spot, didn't you?)
Right click on the last change made to the file before its deletion and
choose "Browse repository".
The file should be visible in the next dialog window. Right-click and
choose "Copy to working copy". Save the file in the place where it
belongs; it will appear to be a new file but will keep its history. Commit
the change.
11) I want to see diffs for a file.
Right click on the file and choose TortoiseSVN / Diff or Diff with
previous version. You will be shown different versions of the file side
by side.
12) I don't like the changes I made and want to revert them. They are
not yet committed.
Right click on the file and choose TortoiseSVN / Revert.
13) There are changes to my file made by someone else that I don't
understand. Who should I ask about them?
Right click on the file and choose TortoiseSVN / Blame. Click OK.
You'll eventually see a view of the file that shows for each line in the
file who made the last change to that line. (Blame can often be Praise
just as well, of course.)
14) What do the cool little colored icon overlays mean?
A green check mark means the file has not been changed since your last
update from the server. A red stop sign means you have changed it.
A yellow warning sign means there is a conflict and resolution is
needed. A blue cross means the file will be added at the next commit.
A wobbly red X means the file will be deleted at the next commit. When
applied to directories, the icons show the status of some of the files
they contain. For example, if a directory contains files that have been
changed, it will have a red stop sign. There are other possibilities.
15) Why do I sometimes see the wrong icon?
Windows can't always keep up smoothly with changes to Subversion status.
Moving up and down the directory tree, or closing the Windows Explorer
window and reopening it, will usually fix things up.
16) I'm ready to make a schema release.
See the separate Release Branching Cheet Sheet and FAQ.
17) I am writing a script, or just prefer to use the command line. Can I?
Yes. The equivalent command-line commands are "svn checkout", "svn
commit", "svn add", "svn diff", "svn rename", "svn copy", and so on.
To set a commit message, use the -m switch to "svn commit" and put
your message in quotes. "Svn help" will give you a list of available
commands. You can do everything from the command line that you can do
from TortoiseSVN and a lot more.
18) I want more information.
Ask me or another local Subversion expert.
Or see the TortoiseSVN Daily Use Guide at
<http://tortoisesvn.net/docs/nightly/TortoiseSVN_en/tsvn-dug.html>.
Or just google for [subversion what you want to know about].
=====================================================================
Any feedback will be greatly appreciated.
--
John Cowan <cowan@ccil.org> http://www.ccil.org/~cowan
Pour moi, les villes du Silmarillion ont plus de réalité que Babylone.
--Christopher Tolkien, as interviewed by Le Monde
------------------------------------------------------
http://tortoisesvn.tigris.org/ds/viewMessage.do?dsForumId=4061&dsMessageId=3037009
To unsubscribe from this discussion, e-mail: [users-unsubscribe_at_tortoisesvn.tigris.org].
Received on 2012-12-19 07:30:20 CET