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