2
<p>IVLE's file browser features an integrated <strong>Subversion</strong>
3
client. Students are encouraged to place all of their files under <em>revision
4
control</em> with Subversion. This provides the following functionality:</p>
6
<li>Backup of files (protection from accidental deletion or
8
<li>Ability to roll back a file to a previous version; sort of a long-term,
10
<li>Ability to check the difference between previous versions of a file,</li>
11
<li>Sharing files among project group members</li>
13
<h2>Subversion in IVLE</h2>
14
<p>IVLE automatically creates Subversion repositories and workspaces, so
15
Subversion "just works" from the start. All of the default directories you see
16
in IVLE are Subversion workspaces by default.</p>
17
<p>The home directory in IVLE is <em>not</em> a Subversion directory. Any
18
files you create in this directory cannot be committed or reverted, so we
19
recommend you don't put any files here (if you do create files here, they will
20
appear under the heading "Junk").</p>
21
<p>IVLE creates a Subversion workspace for each of the following:</p>
23
<li>For each subject you are enrolled in, a workspace called "mywork". This is
24
where you should place all of your personal files for the subject, including
25
any solo projects.</li>
26
<li>For each project group you are enrolled in, a workspace with your group
27
name. This workspace is shared among all group members, and you should place
28
all group project files here.</li>
29
<li>A workspace called "stuff". This is where you should place any work not
30
associated with a subject.</li>
32
<p>The workspaces are not checked out by default. Therefore, when you first
33
log into IVLE, you should see all of the aforementioned workspaces with
34
"(missing)" and a "Checkout" button. Press each of the Checkout buttons to
35
create the workspaces.</p>
36
<h2>Subversion status icons</h2>
37
<p>IVLE shows the status of each file as an icon to the left. This shows the
38
status of each file in the working directory with respect to its backed up
39
state in the repository.</p>
40
<p>The statuses are:</p>
42
<li><img src="/+media/ivle.webapp.core/images/svn/unversioned.png" />
43
<strong>Temporary file</strong>: The file is not committed to the
44
repository, and Subversion knows nothing about this. You will not be able to
45
restore this file if it is deleted, and group members cannot see it. Use
46
"Add", then "Commit" to fix this. Note that files which aren't part of your
47
project and don't need to be saved, such as ".pyc" files, should be left as
48
temporary files, and not added to the repository.</li>
49
<li><img src="/+media/ivle.webapp.core/images/svn/added.png" />
50
<strong>Added</strong>: The file is not committed to the repository, but has
51
been added with the "Add" command. It will be placed under revision control
53
<li><img src="/+media/ivle.webapp.core/images/svn/normal.png" />
54
<strong>Permanent file</strong>: The file is committed to the repository and
55
has no local changes. However, it may still be out-of-date with the version
56
in the repository if you have not run "Update".</li>
57
<li><img src="/+media/ivle.webapp.core/images/svn/modified.png" />
58
<strong>Modified</strong>: The file is committed, but you have modified it
59
since the last commit. The changes are not backed up and group members
60
cannot see them. Commit the file at regular intervals to synchronise the
61
changes with the repository.</li>
62
<li><img src="/+media/ivle.webapp.core/images/svn/conflicted.png" />
63
<strong>Conflicted</strong>: Local changes were made, then you ran
64
"Update", and the update included conflicting or incompatible changes. You
65
should edit the file to fix up these conflicts (which should be clearly
66
visible), then run "Resolve" to set the file back to normal "Modified"
68
<li><img src="/+media/ivle.webapp.core/images/svn/missing.png" />
69
<strong>Missing</strong>: The file is in the repository, but not in the
70
workspace. Likely it was deleted without using Subversion commands. You can
71
"Revert" to get it back.</li>
72
<li><img src="/+media/ivle.webapp.core/images/svn/deleted.png" />
73
<strong>Deleted</strong>: The file is in the repository, but has been
74
deleted using the "Remove" command. This means it has been deleted from the
75
workspace, and will be removed from the repository if committed.</li>
76
<li><img src="/+media/ivle.webapp.core/images/svn/replaced.png" />
77
<strong>Replaced</strong>: The file has been deleted and then a new file
78
has been added in its place.</li>
79
<li><img src="/+media/ivle.webapp.core/images/svn/revision.png" />
80
<strong>Past Permanent file (revision)</strong>: You are browsing the
81
Subversion history — this reflects the state of the file at some point
82
in the past, not the current file. This happens if you use the history
83
browser under "View Log", or if you verify a project submission.</li>
85
<h2>Subversion commands</h2>
86
<p>Within each of the workspaces (and their subdirectories, if versioned), the
87
Subversion commands will be available. These are available under the "More
88
actions" drop-down under the "Subversion" heading. Some are available on the
89
current directory, if no files are selected. Others are available on the
90
currently selected files.</p>
91
<p>This section offers only a brief guide to the Subversion commands. For a
92
complete guide to Subversion, see <a
93
href="http://svnbook.red-bean.com/">Version Control with Subversion</a>.
94
This section is specific to the Subversion integration within IVLE.</p>
95
<p>Note that none of the commands have any effect on the repository until the
96
<strong>Commit</strong> action is applied.</p>
97
<p>The commands are:</p>
99
<li><strong>Svn Cut</strong>: This command works similar to the regular file
100
action, "Cut". It doesn't execute any commands, but the nominated files will
101
be moved to the new location upon performing the regular directory action,
102
"Paste". Unlike "Cut", "Svn Cut" will move the files using the <code>svn
103
move</code> command, so the file will be moved inside the repository too (once
104
committed). Note that you can't move files between repositories, so you can
105
cut and paste between your personal workspaces, but not between your personal
106
and group workspaces.</li>
107
<li><strong>Svn Copy</strong>: Same as "Svn Cut", but upon pasting, will
108
execute <code>svn copy</code> instead of <code>svn move</code>.</li>
109
<li><strong>Add</strong>: Schedule a temporary (unversioned) file to be added
110
to the repository. This changes the file's status from <img
111
src="/+media/ivle.webapp.core/images/svn/unversioned.png" /> "temporary" to
112
<img src="/+media/ivle.webapp.core/images/svn/added.png" /> "added".</li>
113
<li><strong>Remove</strong>: Delete the file from the workspace, and schedule
114
a permanent file to be deleted from the repository. This changes the file's
115
status to <img src="/+media/ivle.webapp.core/images/svn/deleted.png" />
116
"deleted". You will still be able to browse the past versions of this file; it
117
just won't appear in the repository from now on.</li>
118
<li><strong>Diff</strong>: Show exactly the lines of the selected files, or
119
the files in the current directory, that have been changed since the last
120
commit. This is <em>extremely useful</em> before a commit, so you can see
121
exactly what you're about to commit.</li>
122
<li><strong>Revert</strong>: Undo all changes to the selected file since the
123
last commit, and go back to the most recently committed version. Be very
124
careful using this command! (Check the "Diff" first, to see what you're going
125
to delete). Running this on a missing or deleted file will restore the
127
<li><strong>Update</strong>: Fetch all changes from the repository and
128
synchronise them with your workspace. This is only useful when working in a
129
group repository — this updates your workspace with changes made by
130
other team members. This can create <img
131
src="/+media/ivle.webapp.core/images/svn/conflicted.png" /> conflicts, if you
132
both edited the same part of the same file — see above for advice on
133
resolving these.</li>
134
<li><strong>Commit</strong>: Send all of your changes to the repository. This
135
makes a permanent "snapshot" of the current directory state, and lets your
136
team members see your changes. You should commit your work often. You will
137
need to enter a log message, which helps if you need to view a past version.
138
If you get the error "File or directory is out of date; try updating", it
139
means a team member has committed changes since your last update. You can't
140
commit until you run "Update" first, to synchronise your workspace with the
141
team repository.</li>
142
<li><strong>Mark Resolved</strong>: Once you have finished dealing with
143
conflicted files, use Mark resolved to set their status back from <img
144
src="/+media/ivle.webapp.core/images/svn/conflicted.png" /> "conflicted" to a
145
<img src="/+media/ivle.webapp.core/images/svn/modified.png" /> normal status.
146
You can't commit while you have conflicted files.</li>
147
<li><strong>View Log</strong>: Show a summary of the history of a file or
148
directory. This shows all of the log messages from past commits, and lets you
149
view the "diff" between any two past revisions.</li>
150
<li><strong>Cleanup</strong>: This attempts to fix problems with your
151
Subversion workspace. Try this if you are having trouble committing or
152
updating due to "working copy locked" errors.</li>
154
<h2>Projects and group work</h2>
155
<p>You are required to place all of your projects under Subversion in order to
156
submit them. See <a href="../Submitting%20a%20project">Submitting a
157
project</a> for help on submissions.</p>
158
<p>On group projects, it is a little bit trickier, as you don't have any
159
shared directories — only a shared repository. In general, programmers
160
find it very difficult to work with others if you are sharing a directory,
161
constantly writing over each others files! So instead, you each get your own
162
directory, and share files by <strong>committing</strong> (that sends changes
163
out to the team) and <strong>updating</strong> (that receives changes from the
165
<p>As stated above, each project group you are in gets one shared repository,
166
which you can check out from your home screen. Note that if you do several
167
projects with the same group, you will continue using the same repository
168
throughout the subject.</p>
169
<p>Firstly, you should all agree on a Subversion process, and spend some time
170
practicing committing and updating while you are all in the same room. Your
171
workflow should go something like this:</p>
173
<li>Whenever you start work, run the <strong>Update</strong> command, ensuring
174
that your workspace includes all of the latest changes made by team members.
175
(You may even wish to <strong>View Log</strong> after updating, to see what
176
your team members have been up to.)</li>
177
<li>Make your changes <img
178
src="/+media/ivle.webapp.core/images/svn/modified.png" />. You should make
179
only small changes at a time, and then make sure your programs and documents
180
are still valid. Be sure to <img
181
src="/+media/ivle.webapp.core/images/svn/added.png" /> add any new files you
182
create. Random files which aren't part of your project and don't need to be
183
saved, such as ".pyc" files, should not be added.</li>
184
<li>Run <strong>Update</strong> again, to make sure nobody has committed
185
anything in the meantime. If they have, it will <em>merge</em> those changes
186
into your changes, so you end up with the absolute latest version. In very
187
rare cases, you may see the dreaded <img
188
src="/+media/ivle.webapp.core/images/svn/conflicted.png" /> "conflicted"
189
status on some files, meaning that both you and a team mate changed the same
190
part of the same file, and you will have to manually resolve it. See above for
191
advice on this issue.</li>
192
<li>View the <strong>Diff</strong>. This gives you a good overview of the
193
changes you have made, so that a) you know you haven't accidentally changed
194
something you didn't mean to, and b) you have a good idea of what to write in
195
the log message.</li>
196
<li>Run <strong>Commit</strong>. Enter a log message which summarises the
197
changes, so your team mates can quickly find out what you've changed. If all
198
goes well, the files you are committing will go back to <img
199
src="/+media/ivle.webapp.core/images/svn/normal.png" /> permanent files, so
200
you know that the repository is synchronised with your changes.</li>
201
<li>Repeat steps 2-5.</li>
203
<p>With a bit of practice, the whole update-diff-commit process can take less
204
than one minute. It's important to commit often, and commit small changes with
205
useful commit logs, so your team mates can follow the changes you are
added
removed
ivle/webapp/filesystem/browser/help-svn.html
