/usr/share/doc/fcm/user_guide/code_management.html is in fcm 2016.12.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 | <!DOCTYPE html>
<html>
<head>
<title>FCM: User Guide: Code Management</title>
<meta name="author" content="FCM team" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="icon" href="../etc/fcm-icon.png" type="image/png" />
<link rel="shortcut icon" href="../etc/fcm-icon.png" type="image/png" />
<link href="../etc/bootstrap/css/bootstrap.min.css" rel="stylesheet" media="screen" />
<link href="../etc/fcm.css" rel="stylesheet" media="screen" />
</head>
<body>
<div class="navbar navbar-inverse">
<div class="container-fluid">
<div class="navbar-header">
<a class="navbar-brand" href=".."><span class="fcm-version">FCM</span></a>
</div>
<div class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li><a href="../installation/">Installation</a></li>
<li><a class="active" href="#">User Guide</a></li>
</ul>
</div>
</div>
</div>
<div class="page-header">
<div class="fcm-page-content pull-right well well-sm"></div>
<h1>FCM: User Guide: Code Management</h1>
</div>
<div class="container">
<div class="row">
<div class="col-md-12">
<h2 id="svn">Using Subversion</h2>
<p>One of the key strengths of Subversion is its documentation. <a href=
"http://svnbook.red-bean.com/en/1.8/">Version Control with Subversion</a>
(which we'll just refer to as the <cite>Subversion book</cite> from now on)
is an excellent book which explains in detail how to use Subversion and also
provides a good introduction to all the basic concepts of version control.
Rather than trying to write our own explanations (and not doing as good a
job) we will simply refer you to the <cite>Subversion book</cite>, where
appropriate, for the relevant information.</p>
<p>In general, the approach taken in this section is to make sure that you
first understand how to perform a particular action using the Subversion
tools and then describe how this differs using FCM.</p>
<h3 id="svn_concepts">Basic Concepts</h3>
<p>In order to use FCM you need to have a basic understanding of version
control. If you're not already familiar with Subversion or CVS then please
read the chapter <a href=
"http://svnbook.red-bean.com/en/1.8/svn.basic.html">Fundamental Concepts</a>
from the <cite>Subversion book</cite>. In particular, make sure that you
understand:</p>
<ul>
<li>The <q title=
"http://svnbook.red-bean.com/en/1.8/svn.basic.version-control-basics.html#svn.basic.vsn-models.copy-merge">
Copy-Modify-Merge</q> approach to file sharing.</li>
<li>Global Revision Numbers.</li>
</ul>
<p>Note that this chapter states that <q title=
"http://svnbook.red-bean.com/en/1.8/svn.basic.in-action.html#svn.basic.in-action.wc">
working copies do not always correspond to any single revision in the
repository</q>. However, the FCM working practices do not encourage this and
the wrapper scripts provided by FCM should ensure that your working copy (a
local copy of the repository's files and directories where you can prepare
changes) always corresponds to exactly one revision.</p>
<p><acronym title="Concurrent Versions System">CVS</acronym> users should
already be familiar with all the basic concepts. This is not surprising since
Subversion was designed as a replacement for CVS and it uses the same
development model. However, there are some important differences which may
confuse those more familiar with CVS. Fortunately, the appendix in the
<cite>Subversion book</cite> <a href=
"http://svnbook.red-bean.com/en/1.8/svn.forcvs.html">Subversion for CVS
Users</a> is specifically written for those moving from CVS to Subversion and
you should read this if you are a CVS user.</p>
<h3 id="svn_basic">Basic Command Line Usage</h3>
<p>Before we discuss the FCM system you need to have a good understanding of
how to perform most of the normal day-to-day tasks using Subversion.
Therefore, unless you are already familiar with Subversion, please read the
chapter <a href="http://svnbook.red-bean.com/en/1.8/svn.tour.html">Basic
Usage</a> from the <cite>Subversion book</cite>.</p>
<p>So, now you have an understanding of how to do basic tasks using
Subversion (you did read the <cite>Basic Usage</cite> chapter didn't you?),
how is using FCM different? Well, the key thing to remember is that, instead
of using the command <code>svn</code> you need to use the command
<code>fcm</code>. The advantages of this are as follows:</p>
<ul>
<li><code>fcm</code> implements all of the commands that <code>svn</code>
does (including all the command abbreviations).</li>
<li>In some cases <code>fcm</code> does very little and basically passes on
the command to <code>svn</code>.</li>
<li>In other cases <code>fcm</code> has a lot of additional functionality
compared with the equivalent <code>svn</code> command.</li>
<li><code>fcm</code> also implements several commands not provided by
<code>svn</code>.</li>
<li><code>fcm</code> provides support for URL and revision keywords.</li>
<li>Most of the additional features and commands are discussed later in
this section or in the following sections.</li>
</ul>
<p>Full details of all the <code>fcm</code> commands available are provided
in the <a href="command_ref.html">FCM Command Reference</a> section.</p>
<h4 id="svn_basic_keywords">URL And Revision Keywords</h4>
<p>URL keywords can be used to specify URLs in <code>fcm</code> commands. The
syntax is <code>fcm:<keyword></code>. Keywords can be defined in the
FCM keyword configuration file (i.e. <samp>$FCM/etc/fcm/keyword.cfg</samp>
and <samp>$HOME/.metomi/fcm/keyword.cfg</samp>).</p>
<p>For example, if you define a keyword in your configuration file as
follows:</p>
<pre>
location{primary}[um] = svn://fcm2/UM_svn/UM
</pre>
<p>then you can abbreviate the URL as in the following examples:</p>
<pre>
# fcm ls svn://fcm2/UM_svn/UM
fcm ls fcm:um
# fcm ls svn://fcm2/UM_svn/UM/trunk
fcm ls fcm:um_tr # OR: fcm ls fcm:um-tr
# fcm ls svn://fcm2/UM_svn/UM/branches
fcm ls fcm:um_br # OR: fcm ls fcm:um-br
# fcm ls svn://fcm2/UM_svn/UM/tags
fcm ls fcm:um_tg # OR: fcm ls fcm:um-tg
</pre>
<p>Using URL keywords has two advantages.</p>
<ul>
<li>They are shorter and easier to remember.</li>
<li>If the repository needs to be moved then only the keyword definitions
need to be updated (although any working copies you have will still need to
be <em>relocated</em> by issuing a <a href=
"http://svnbook.red-bean.com/en/1.8/svn.ref.svn.c.switch.html"><code>fcm
switch --relocate</code></a> command).</li>
</ul>
<p>In a similar way, revision keywords can be used to specify revision
numbers in <code>fcm</code> commands. The keyword can be used anywhere a
revision number can be used. Each keyword is associated with a URL keyword
and can only be used when referring to that repository.</p>
<p>For example, if you define a keyword in your configuration file as
follows:</p>
<pre>
revision[fcm:vn1.0] = 112
</pre>
<p>then the following commands are equivalent:<br />
<code>fcm log -r 112 svn://fcm1/FCM_svn/trunk</code><br />
<code>fcm log -r vn1.0 fcm:fcm_tr</code></p>
<p>You can use the <code>fcm keyword-print</code> command to print all
registered location keywords. You can also print the location keyword and the
revision keywords of a particular project. For example, to print the keywords
for the <samp>UM</samp> project, you can type <code>fcm keyword-print
fcm:um</code>.</p>
<h4 id="svn_basic_diff">Examining Changes</h4>
<p>Code differences can be displayed graphically using <code>xxdiff</code> by
using the <code>--graphical</code> (or <code>-g</code>) option to <code>fcm
diff</code>. This option can be used in combination with any other options
which are accepted by <code>svn diff</code>.</p>
<p>An example display from <code>xxdiff</code> is shown below.</p>
<p class="image"><img src="xxdiff1.png" alt="xxdiff 2-way display" /><br />
<code>xxdiff</code> 2-way display</p>
<p>Points to note:</p>
<ul>
<li>By default <code>xxdiff</code> is configured to show horizontal
differences. This means that the parts of the line which have changed are
highlighted (e.g. the text <samp>useful</samp> is highlighted in the
example above).</li>
<li>The number shown to the right of each file name shows the current line
number. The number on the far right is the number of differences found (2
in the example above).</li>
<li>You may find the following keyboard shortcuts useful.
<ul>
<li><kbd>N</kbd> - move to the next difference</li>
<li><kbd>P</kbd> - move to the previous difference</li>
<li><kbd>Ctrl-Q</kbd> - exit</li>
</ul>
</li>
<li>If you want to use another diff tool instead of <code>xxdiff</code> to
examine changes, you can define the <code>graphic-diff</code> setting in a
FCM external configuration file (i.e.<samp>$FCM/etc/fcm/external.cfg</samp>
or <samp>$HOME/.metomi/fcm/external.cfg</samp>). For example, to use <code>
tkdiff</code>, you can do:
<pre>
# in your site's $FCM/etc/fcm/external.cfg:
# OR: in your $HOME/.metomi/fcm/external.cfg:
graphic-diff = tkdiff
</pre>
</li>
</ul>
<h4 id="svn_basic_conflicts">Resolving Conflicts</h4>
<p>Your working copy may contain files or directories <em>in conflict</em> as
a result of an update or a merge (covered later). Conflicts arise from the
situation where two changes being applied to a file <em>overlap</em>. These
can be text-based, as in two changes to the same line of text in a file, or
filesystem-based, as in two different renamings of the same file.</p>
<p>For conflicts in normal (text) files, the command <code>fcm
conflicts</code> can be used to help resolve them. (A discussion on binary
files is given in the section <a href="working_practices.html#binary">Working
with Binary Files</a> later in this document.). For each file in <em>text
conflict</em>, the <code>fcm conflicts</code> command calls a graphical merge
tool (i.e. <code>xxdiff</code> by default) to display a 3-way diff.</p>
<p>An example display from <code>xxdiff</code> is shown below.</p>
<p class="image"><img src="xxdiff2.png" alt="xxdiff 3-way display" /><br />
<code>xxdiff</code> 3-way display</p>
<p>Points to note:</p>
<ul>
<li>The file in the middle is the common ancestor from the merge. The file
on the left is your original file and the file on the right is the file
containing the changes which you are merging in.</li>
<li><code>xxdiff</code> is configured to automatically select regions that
would end up being selected by an automatic merge (e.g. there are only
changes in one of the files). Any difference <em>hunks</em> which cannot be
resolved automatically are left <em>unselected</em>.</li>
<li>Before you can save a merged version you need to go through each
unselected difference hunk and decide which text you wish to use.
<ul>
<li>Selecting a diff hunk can be carried out by clicking on it with the
left mouse button (or refer to the keyboard shortcuts shown under the
<kbd>Region</kbd> menu). The colours update to display which side is
selected for output. You can select individual lines with the middle
mouse button.</li>
<li>If you want to select more than one side, you have to invoke the
<kbd>Region->Split/swap/join</kbd> command (keyboard shortcut:
<kbd>S</kbd>). This will split the current diff hunk so you can select
the pieces you want from both sides. Further invocations of this
command will cause swapping of the regions, looping through all the
different ordering possibilities, and finally joining the regions again
(preserving selections where it is possible).</li>
</ul>
</li>
<li>The number on the far right is the number of unselected difference
hunks (1 in the example above). Once this number is 0 then you are ready to
save the merged file.</li>
<li>If you want to see how the merged file will look with the current
selections then select <kbd>Windows->Toggle Merged View</kbd> (keyboard
shortcut: <kbd>Alt+Y</kbd>). An extra window then appears showing the
merged output that updates interactively as you make selections.</li>
<li>You may find the following keyboard shortcuts useful.
<ul>
<li><kbd>B</kbd> - move to the next unselected hunk</li>
<li><kbd>O</kbd> - move to the previous unselected hunk</li>
</ul>
</li>
<li>There are several different ways to exit the 3-way diff (available from
the <kbd>File</kbd> menu):
<ul>
<li>Exit with MERGE (keyboard shortcut: <kbd>M</kbd>) - This saves the
merge result. If there are any unselected difference hunks remaining
then you will be warned and given the option of saving the file with
conflict markers.</li>
<li>Exit with ACCEPT (keyboard shortcut: <kbd>A</kbd>) - This saves the
file you are merging in (i.e. the right one) as the merge result (i.e.
you have <em>accepted</em> all the changes).</li>
<li>Exit with REJECT (keyboard shortcut: <kbd>R</kbd>) - This saves the
original working copy file (i.e. the left one) as the merge result
(i.e. you have <em>rejected</em> all the changes).</li>
</ul>
<p>If you just want to exit without making any decisions you can also
just close the window.</p>
</li>
<li>For further details please read the <a href=
"http://furius.ca/xxdiff/doc/xxdiff-doc.html"><code>xxdiff</code> users
manual</a> (available from the <kbd>Help</kbd> menu). In particular, read
the section <a href=
"http://furius.ca/xxdiff/doc/xxdiff-doc.html#merging-files-and-resolving-conflicts">
<em>Merging files and resolving conflicts</em></a>.</li>
</ul>
<p>If you have resolved all the conflicts in a file then you will be prompted
on whether to run <code>svn resolved</code> on the file to signal that the
file is no longer in conflict.</p>
<pre>
(SHELL PROMPT)$ fcm conflicts
Conflicts in file: Gen_setup_local1.proc
You have chosen to ACCEPT all the changes
Would you like to run "svn resolved"?
Enter "y" or "n" (or just press <return> for "n"): y
Resolved conflicted state of 'Gen_setup_local1.proc'
Conflicts in file: Gen_setup_remote2.proc
Merge conflicts were not all resolved
Conflicts in file: Gen_setup_remote3.proc
All merge conflicts resolved
Would you like to run "svn resolved"?
Enter "y" or "n" (or just press <return> for "n"): y
Resolved conflicted state of 'Gen_setup_remote3.proc'
</pre>
<p>It is important to realise that there are some types of merge that
<code>xxdiff</code> will not be able to help you with.</p>
<ul>
<li>It you have 2 versions of a file, both with substantial changes to the
same piece of code, then the <code>xxdiff</code> display will be extremely
colourful and not very helpful.</li>
<li>In these cases it is often easier to start with one version of the file
and manually re-apply the changes from the other version. It might not be
obvious how to do this and you may need to speak to the author of the other
change to agree how this can be done. Fortunately this situation should be
very rare.</li>
<li>For a more detailed discussion please refer to <a href=
"http://software.ericsink.com/scm/scm_file_merge.html">Chapter 3: File
Merge</a> in the online book called <a href=
"http://software.ericsink.com/scm/source_control.html">Source Control
HOWTO</a>.</li>
</ul>
<p>For files in <em>tree conflict</em>, which is otherwise known as a
structural or filesystem-based conflict, the command <code>fcm
conflicts</code> will manually resolve the problem by prompting you to choose
a course of action. You can either keep the file as it was before the merge
(<em>keep local</em>), or accept the external changes to the file.</p>
<p>The most common way to generate a tree conflict after a merge is when a
file has been deleted or renamed on one branch, and modified on another.
These are incompatible changes, to Subversion, and it doesn't know which
action to take. This is the cause of the tree conflict dilemma which the user
must solve.</p>
<p>In the following example, the branch in the working copy has had a
deletion of a file. The branch that is being merged in has subsequently
modified the file, which means that you may want to incorporate these
changes. A tree conflict is therefore flagged up.</p>
<pre>
(SHELL PROMPT)$ fcm merge fcm:tutorial_br/dev/bfitz/r1_366
Merge(s) available from /tutorial/branches/dev/bfitz/r1_366: 1257
About to merge in changes from /tutorial/branches/dev/bfitz/r1_366@1257 compared with /tutorial/trunk@1
This merge will result in the following change:
--------------------------------------------------------------------------------
--- Merging r2 through r1257 into '.':
C src/subroutine/hello_sub.f90
Summary of conflicts:
Tree conflicts: 1
--------------------------------------------------------------------------------
Would you like to go ahead with the merge?
Enter "y" or "n" (or just press <return> for "n"): y
Performing merge ...
--- Merging r2 through r1257 into '.':
C src/subroutine/hello_sub.f90
Summary of conflicts:
Tree conflicts: 1
(SHELL PROMPT)$ fcm status
M .
! C src/subroutine/hello_sub.f90
> local missing, incoming edit upon merge
(SHELL PROMPT)$ fcm info src/subroutine/hello_sub.f90
Path: src/subroutine/hello_sub.f90
Name: hello_sub.f90
Node Kind: none
Tree conflict: local missing, incoming edit upon merge
Source left: (file) svn://fcm1/tutorial_svn/tutorial/trunk/src/subroutine/hello_sub.f90@1
Source right: (file) svn://fcm1/tutorial_svn/tutorial/branches/dev/bfitz/r1_366/src/subroutine/hello_sub.f90@1257
</pre>
<p>In this example, running <code>fcm conflicts</code> would give:</p>
<pre>
(SHELL PROMPT)$ fcm conflicts
[info] src/subroutine/hello_sub.f90: in tree conflict.
Locally: deleted
Externally: modified.
Answer (y) to leave the file deleted.
Answer (n) to add the file with the changes.
Keep the local version?
Enter "y" or "n" (or just press <return> for "n")
</pre>
<p>In this example, to keep the file as it was before (in a deleted state),
enter <samp>y</samp>.</p>
<p>Otherwise, to accept the merge branch version of the file (adding it with
the edited changes), enter <samp>n</samp>.</p>
<p>There are many other types of tree conflicts that can occur, and <code>fcm
conflicts</code> does not cover all of them. Tree conflicts arising from
updates and switches are not covered (which should be rare under FCM working
practice). More importantly, tree conflicts on directories are not covered,
because of the potential nesting of conflicts within the directories. It can
often be difficult to identify the problem and figure out the solution in the
case of directory conflicts, and the easiest solution may be to try to
resolve the discrepancy before the merge.</p>
<p>For further details, see the <a href=
"annex_quick_ref_tree_conflicts.html">Tree Conflict</a> annex</p>
<h4 id="svn_basic_check">Adding and Removing Files</h4>
<p>If your working copy contains files which are not under version control
then you can use the command <code>fcm add --check</code> to add them. This
will go through each of the files and prompt to see if you wish to put that
file under version control using <code>svn add</code>. For each file you can
enter <kbd>y</kbd> for yes, <kbd>n</kbd> for no or <kbd>a</kbd> to assume yes
for all following files.</p>
<pre>
(SHELL PROMPT)$ fcm add -c
? xxdiff1.png
? xxdiff2.png
? xxdiff3.png
? xxdiff4.png
Add file 'xxdiff1.png'?
Enter "y", "n" or "a" (or just press <return> for "n"): y
A xxdiff1.png
Add file 'xxdiff2.png'?
Enter "y", "n" or "a" (or just press <return> for "n"): n
Add file 'xxdiff3.png'?
Enter "y", "n" or "a" (or just press <return> for "n"): a
A xxdiff3.png
A xxdiff4.png
</pre>
<p>Similarly, if your working copy contains files which are missing (i.e. you
have deleted them without using <code>svn delete</code>) then you can use the
command <code>fcm delete --check</code> to delete them. This will go through
each of the files and prompt to see if you wish to remove that file from
version control using <code>svn delete</code>.</p>
<p>As noted in the <a href=
"http://subversion.apache.org/faq.html#wc-change-detection">Subversion
FAQ</a>, it can be dangerous using these commands. If you have moved or
copied a file then simply adding them would cause the history to be lost.
Therefore take care to only use these commands on files which really are new
or deleted.</p>
<h4 id="svn_basic_commit">Committing Changes</h4>
<p>The command <code>fcm commit</code> should be used for committing changes
back to the repository. It differs from the <code>svn commit</code> command
in a number of important ways:</p>
<ul>
<li>Your working copy <em>must</em> be up to date. <code>fcm commit</code>
will abort if it finds that any files are out of date with respect to the
repository. This ensures that your working copy reflects how the repository
will be after you have committed your changes.
<ul>
<li>This helps to ensure that any tests you have done prior to
committing are valid.</li>
<li><code>fcm commit</code> is not suitable if you need to commit
changes from a working copy containing mixed revisions. However, you
are very unlikely to need to do this.</li>
<li>Actually there is a small chance that your working copy might not
be up to date when you commit if someone else is committing some
changes at the same time. However, this should very seldom happen and,
even if it does, the commit would fail if any of the files being
changed became out of date (i.e. it is not possible to lose any
changes).</li>
</ul>
</li>
<li>If it discovers a file named <samp>#commit_message#</samp> in the top
level of your working copy it uses this to provide a template commit
message (which you can then edit).
<ul>
<li>If you have performed a merge then a message describing the merge
will have been added to this file. It is important that you leave this
included in the commit message and do not change its format, as it is
used by the <code>fcm branch-info</code> command.</li>
<li>You can, if you wish, add entries to this file as you go along to
record what changes you have prepared in your working copy. You can
also use the command <code>fcm commit --dry-run</code> to allow you to
edit the commit message without committing any changes.</li>
<li><samp>#commit_message#</samp> is ignored by Subversion (so you
won't see it show up as an unversioned files when you run <code>fcm
status</code>).</li>
</ul>
</li>
<li>It always operates from the top of your working copy. If you issue the
<code>fcm commit</code> command from a sub-directory of your working copy
then it will automatically work out the top directory and work from there.
<ul>
<li>This ensures that any template commit message gets picked up and
that you do not, for example, accidently commit a partial set of
changes from a merge.</li>
</ul>
</li>
<li>It always commits <em>all</em> the changes in your working copy (it
does not accept a list of files to commit).
<ul>
<li>Once again, this avoids any danger of accidently committing a
partial set of changes.</li>
<li>You should only work on one change within a working copy. If you
need to prepare another, unrelated change then use a separate working
copy.</li>
</ul>
</li>
<li>It runs <code>svn update</code> after the commit to ensure that your
working copy is at the latest revision and to avoid any confusion caused by
your working copy containing mixed revisions.</li>
</ul>
<pre>
(SHELL PROMPT)$ fcm commit
Starting editor to create commit message ...
Change summary:
------------------------------------------------------------------------
[Project: GEN]
[Branch : branches/test/frsn/r123_foo_bar]
[Sub-dir: <top>]
M src/code/GenMod_Control/GenMod_Control.f90
M src/code/GenMod_Control/Gen_SetupControl.f90
------------------------------------------------------------------------
Commit message is as follows:
------------------------------------------------------------------------
An example commit.
------------------------------------------------------------------------
Would you like to commit this change?
Enter "y" or "n" (or just press <return> for "n"): y
Sending src/code/GenMod_Control/GenMod_Control.f90
Sending src/code/GenMod_Control/Gen_SetupControl.f90
Transmitting file data ..
Committed revision 170.
=> svn update
At revision 170.
</pre>
<h3 id="svn_branching">Branching And Merging</h3>
<p>Branching is a fundamental concept common to most version control systems.
For a good introduction please read the chapter <a href=
"http://svnbook.red-bean.com/en/1.8/svn.branchmerge.html">Branching and
Merging</a> from the <cite>Subversion book</cite>. Even if you are already
familiar with branching using other version control systems you should still
read this chapter to see how branching is implemented in Subversion.</p>
<p>Having read this chapter from the <cite>Subversion book</cite> you should
understand:</p>
<ul>
<li>Why each project directory has sub-directories called <em>trunk</em>,
<em>branches</em> and <em>tags</em>. This structure is assumed by
<code>fcm</code> (Subversion recommends it but doesn't insist on it).</li>
<li>That when you make a branch you are taking a copy of the entire project
file tree. Fortunately, the design of the Subversion repository means that
these copies are <q title=
"http://svnbook.red-bean.com/en/1.8/svn.branchmerge.using.html#svn.branchmerge.using.create">
cheap</q> - they are quick to create and take very little space.</li>
<li>That Subversion has only implemented merge tracking recently,
long after FCM has implemented its own solution optimised for our
recommended working practice.</li>
<li>That each revision of your repository can also be thought of as a
<em>changeset</em>.</li>
<li>That once a change is committed to a repository it cannot be removed
(only reversed). Therefore you must take care not to committ a sensitive
document or a large data file unintentionally.</li>
</ul>
<p>FCM provides various commands which make working with branches easier (as
described in the following sections).</p>
<h4 id="svn_branching_create">Creating Branches</h4>
<p>The command <code>fcm branch-create</code> (or simply <code>fcm
bcreate</code> or even <code>fcm bc</code>) should be used for creating new
branches. It provides a number of features:</p>
<ul>
<li>It applies a standard naming convention for branches. The branch name
is automatically constructed for you depending on the option(s) supplied to
the command. The full detail of these options are described in the <a href=
"command_ref.html#fcm-branch-create">FCM Command Reference > fcm
branch-create</a> section.</li>
<li>By default, it assumes that you are branching from the last changed
revision of the <em>trunk</em>.
<ul>
<li>You can use the <code>--branch-of-branch</code> option if you need
to create a branch of a branch. A branch of a branch can be useful in
many situations. For example, consider a shared branch used by several
members of your team to develop, say, a new science scheme, and you
have come up with some different ideas of implementing the scheme. You
may want to create a branch of the shared branch to develop your idea
before merging it back to the shared branch. Note that you can only
merge a branch of a branch with it's parent or with another branch
created from the same parent. You can't, for example, merge it with the
trunk.</li>
<li>You can do <code>fcm bc NAME SOURCE@REV</code> if you
need to create a branch from an earlier revision of the SOURCE.</li>
</ul>
</li>
<li>Each branch always contains a full copy of the trunk (or its parent
branch) - you cannot create a branch from a sub-tree.
<ul>
<li>There would be no reason to only include a sub-tree in a
branch.</li>
</ul>
</li>
<li>It applies a standard commit message which defines how the branch has
been created. If a Trac ticket is specified using the <code>--ticket
<number></code> option, it is added to the commit log message. If you
need to add anything to the commit log message, please do so
<strong>above</strong> the line that says <samp>--Add your commit message
ABOVE - do not alter this line or those below--</samp>.</li>
</ul>
<p>The following is a list of the different types of branches available:</p>
<dl>
<dt>User development branches</dt>
<dd><samp>branches/dev/<Userid>/<Branch_Name></samp> These are
for changes which are intended to be merged back to the trunk once they are
complete. Most branches will belong to this type. e.g.
branches/dev/frdm/vn6.1_ImprovedDeepConvection,
branches/dev/frdm/r2134_NewBranchNamingConvention.</dd>
<dt>Shared development branches</dt>
<dd><samp>branches/dev/Share/<Branch_Name></samp></dd>
<dt>User test branches</dt>
<dd><samp>branches/test/<Userid>/<Branch_Name></samp> These are
for changes which are <em>not</em> intended for the trunk. e.g. Proof of
concept work, temporary code written for dealing with a one-off problem,
etc.</dd>
<dt>Shared test branches</dt>
<dd><samp>branches/test/Share/<Branch_Name></samp></dd>
<dt>User packages</dt>
<dd><samp>branches/pkg/<Userid>/<Branch_Name></samp> These are
branches which combine together a number of different development branches.
Sometimes this will simply be for testing purposes (i.e. for testing a
branch in combination with other branches). Other times it may be the
package which eventually gets merged to the trunk (rather than the
development branches). e.g.
branches/pkg/frdm/vn6.1_TestImprovedDeepConvection</dd>
<dt>Shared packages</dt>
<dd><samp>branches/pkg/Share/<Branch_Name></samp> E.g.
branches/pkg/Share/vn6.1_NewConvectionScheme.</dd>
<dt>Configurations</dt>
<dd><samp>branches/pkg/Config/<Branch_Name></samp> These are major
packages which combine together a number of different packages and
development branches. e.g. branches/pkg/Config/vn6.1_HadGEM1a.</dd>
<dt>Releases</dt>
<dd><samp>branches/pkg/Rel/<Branch_Name></samp> These may be bug-fix
branches for system releases, if required. They can also be branches on
which stable releases are prepared if you don't do this on the trunk
(although you lose the ability to branch from stable releases if you work
this way). e.g. branches/pkg/Rel/vn6.1_BugFixes.</dd>
</dl>
<pre>
(SHELL PROMPT)$ fcm bcreate -k 23 my_test_branch fcm:test
Starting nedit to create commit message ...
Change summary:
------------------------------------------------------------------------
A svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch
------------------------------------------------------------------------
Commit message is as follows:
------------------------------------------------------------------------
Create an example branch to demonstrate branch creation for the user guide.
#23: Created /OPS/branches/dev/frsn/r118_my_test_branch from /OPS/trunk@118.
------------------------------------------------------------------------
Would you like to go ahead and create this branch?
Enter "y" or "n" (or just press <return> for "n"): y
Creating branch svn://fcm1/repos/OPS/branches/dev/frsn/r118_my_test_branch ...
Committed revision 169.
</pre>
<h4 id="svn_branching_list">Listing Branches Created by You or Other
Users</h4>
<p>The command <code>fcm branch-list</code> (or simply <code>fcm bls</code>)
can be used to list the branches you have created at the HEAD of a
repository. If you specify the <code>--user <userid></code> option, the
branches created by <userid> are listed instead. You can specify
multiple users with multiple <code>--user <userid></code> options, or
with a colon (:) separated list to a single <code>--user
<userid:list></code> option. Note that you can also list shared
branches by specifying <userid> as <code>Share</code>, configuration
branches by specifying <userid> as <code>Config</code> and release
branches by specifying <userid> as <code>Rel</code>. The command
returns 0 (success) if one or more branches is found for the specified users,
or 1 (failure) if no branch is found.</p>
<pre>
(SHELL PROMPT)$ fcm branch-list fcm:gen
1 branch found for frsn in svn://fcm1/GEN_svn/GEN
fcm:GEN-br/dev/frsn/r1191_clean_up/
(SHELL PROMPT)$ echo $?
0
(SHELL PROMPT)$ fcm branch-list --user frbj --user frsn fcm:gen
2 branches found for frbj, frsn in svn://fcm1/GEN_svn/GEN
fcm:GEN-br/dev/frbj/r1177_gen_ui_for_scs/
fcm:GEN-br/dev/frsn/r1191_clean_up/
(SHELL PROMPT)$ echo $?
0
(SHELL PROMPT)$ fcm branch-list --user frva fcm:gen
0 branch found for frva in svn://fcm1/GEN_svn/GEN
(SHELL PROMPT)$ echo $?
1
</pre>
<h4 id="svn_branching_info">Getting Information About Branches</h4>
<p>The command <code>fcm branch-info</code> (or simply <code>fcm
binfo</code>) can be used to get various information about a branch. In
particular, it summarises information about merges to and from the branch and
its parent.</p>
<pre>
(SHELL PROMPT)$ fcm branch-info
URL: svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r1346_merge
Repository Root: svn://fcm1/FCM_svn
Revision: 1385
Last Changed Author: frsn
Last Changed Rev: 1385
Last Changed Date: 2006-04-20 11:08:45 +0100 (Thu, 20 Apr 2006)
--------------------------------------------------------------------------------
Branch Create Author: frsn
Branch Create Rev: 1354
Branch Create Date: 2006-04-04 14:27:47 +0100 (Tue, 04 Apr 2006)
Branch Parent: svn://fcm1/FCM_svn/FCM/trunk@1346
Last Merge From Parent, Revision: 1444
Last Merge From Parent, Delta: /FCM/trunk@1439 cf. /FCM/trunk@1395
Merges Avail From Parent: 1445
Merges Avail Into Parent: 1453 1452 1449 1446 1444 1443 1441 1434 1397 1396 ...
</pre>
<p>If you need information on the current children of the branch, use the
<code>--show-children</code> option of the <code>fcm branch-info</code>
command. If you need information on recent merges to and from the branch and
its siblings, use the <code>--show-siblings</code> option of the <code>fcm
branch-info</code> command.</p>
<p>To find out what changes have been made on a branch relative to its parent
you can use the command <code>fcm branch-diff</code> (or simply <code>fcm
bdi</code>.</p>
<ul>
<li>You can combine this with the options:
<dl>
<dt><code>--graphical</code></dt>
<dd>to display the differences using a graphical <em>diff</em>
tool</dd>
<dt><code>--trac</code></dt>
<dd>to display the differences using Trac</dd>
<dt><code>--wiki</code></dt>
<dd>to print a wiki syntax suitable for inserting into Trac</dd>
</dl>
</li>
<li>The base of the difference is adjusted to account for any merges from
the branch to its parent or vice-versa.</li>
</ul>
<h4 id="svn_branching_switch">Switching your working copy to point to another
branch</h4>
<p>The command <code>fcm switch</code> can be used to switch your working
copy to point to another branch. For example, if you have a working copy at
<samp>$HOME/work</samp>, currently pointing to the trunk or a branch of a
project at <samp>svn://fcm1/FCM_svn/FCM/trunk</samp>, you can switch the
working copy to point to another branch of same project:</p>
<pre>
(Shell prompt)$ cd $HOME/work
(Shell prompt)$ fcm sw dev/frsn/r959_blockdata
-> svn switch --revision HEAD svn://fcm1/FCM_svn/FCM/branches/dev/frsn/r959_blockdata
U doc/user_guide/getting_started.html
U doc/user_guide/code_management.html
U doc/user_guide/command_ref.html
U src/lib/FCM1/SrcFile.pm
U src/lib/FCM1/Util.pm
U src/lib/FCM1/Build.pm
U src/lib/FCM1/Cm.pm
U src/lib/FCM1/SrcPackage.pm
U src/bin/fcm_internal
U src/bin/fcm_gui
Updated to revision 1009.
</pre>
<p>Unlike <code>svn switch</code>, <code>fcm switch</code> does extra
checking to ensure that your whole working copy is switched to the new branch
at the correct level of sub-directory. In addition, you can specify only the
<em>branch</em> part of the URL, such as <samp>trunk</samp>,
<samp>branches/dev/fred/r1234_bob</samp> or even
<samp>dev/fred/r1234_bob</samp> and the command will work out the full URL
for you.</p>
<h4 id="svn_branching_delete">Deleting Branches</h4>
<p>The command <code>fcm branch-delete</code> (or simply <code>fcm
bdel</code>) can be used to delete branches which are no longer required.
Before being asked to confirm that you want to delete the branch, you will
first see the same output as from <code>fcm branch-info</code>. This allows
you to check, for example, whether your branch is being used anywhere else or
whether the latest changes on your branch have been merged to the trunk. You
will be prompted to edit your commit log message. If you need to add anything
to the commit log message, please do so <strong>above</strong> the line that
says <samp>--Add your commit message ABOVE - do not alter this line or those
below--</samp>.</p>
<h4 id="svn_branching_merge">Merging</h4>
<p>As mentioned earlier, <code>fcm</code> has its own merge tracking solution
which is optimised for our recommended working practice. The solution assumes
the following:</p>
<ul>
<li>That all merges are performed using FCM and are identified using a
standard template in the commit log message.</li>
<li>That you only ever merge all the changes available on the source branch
up to a chosen point (i.e. you can't only include a subset of the changes
made to the branch).</li>
<li>That the source and target are both branches (or the trunk) in the same
FCM project.</li>
<li>That the source and target are directly related, i.e. they must either
have a parent/child relationship or they are siblings from the same parent
branch.</li>
</ul>
<p>Note that the term <em>source branch</em> and <em>target branch</em>
referred to above can also mean the trunk.</p>
<p>To perform a merge, use the command <code>fcm merge <source></code>.
This includes a number of important features:</p>
<ul>
<li>If it finds any local modifications in your working copy then it checks
whether you wish to continue (in most cases you won't want to mix a merge
with other changes).</li>
<li>It determines the base revision and path of the <em>common
ancestor</em> to be used for the merge, taking into account any merges from
the <em>source</em> to the <em>target</em> or vice-versa.</li>
<li>Before doing the merge, (unless you specify the
<code>--non-interactive</code> option), it reports what changes will result
from performing the merge and checks that you wish to continue.</li>
<li>It adds details of the merge, using a standard template, into the
commit message file (<samp>#commit_message#</samp>). If you need to add any
extra comment, you should do so <strong>above</strong> the line that says
<samp>--Add your commit message ABOVE - do not alter this line or those
below--</samp>.
<ul>
<li>If you decide to revert the merge, you should remove the template
line manually from the commit message file, making sure that you do not
alter the standard template by accident.</li>
<li>If the <code>--auto-log</code> option is specified, it adds the log
messages of the merged revisions as well as the standard template. This
is particularly useful when a small change is prepared in a branch, and
often the same commit log messages have to be repeated when the change is
merged and committed to the trunk. The option does not work very well if
the branch contains merges from another branch.</li>
</ul>
</li>
</ul>
<pre>
(SHELL PROMPT)$ fcm merge trunk # merge changes from the trunk into the branch
Eligible merge(s) from FCM/trunk: 1383 1375
Enter a revision (or just press <return> for "1383"):
Merge: /FCM/trunk@1383
c.f.: /FCM/trunk@1371
-------------------------------------------------------------------------dry-run
A doc/fortran_standards/index.html
U src/lib/FCM1/ReposBranch.pm
-------------------------------------------------------------------------dry-run
Would you like to go ahead with the merge?
Enter "y" or "n" (or just press <return> for "n"): y
Merge succeeded.
</pre>
<h3 id="svn_gui">Using the GUI</h3>
<p>So far, all the tools described have been command line tools. Many people
will be happy with these but, for those who prefer it, there is also a simple
Graphical User Interface (GUI).</p>
<h4 id="svn_gui_start">Starting the GUI</h4>
<p>To run the GUI simply issue the command <code>fcm gui</code> from the
directory you want as your working directory.</p>
<p>The GUI consists of several sections:</p>
<ul>
<li>The top section contains a row of buttons to allow you to select which
command you want to run.</li>
<li>Beneath this is shown the current working directory and the top level
directory of your working copy (these may be the same).</li>
<li>Beneath this come various buttons and entry boxes to allow you to
configure the command you have selected. These vary according to the
command.</li>
<li>Beneath this comes a further row of buttons
<ul>
<li><em>Quit</em> - this exits the GUI.</li>
<li><em>Help</em> - this displays the help message for the selected
command.</li>
<li><em>Clear</em> - this empties the text window.</li>
<li><em>Run</em> - this allows you to run your command.</li>
</ul>
</li>
<li>Beneath this comes a scrolling text window where the output from the
commands is displayed.</li>
<li>The bottom section displays help information when you position the
cursor over various parts of the GUI.</li>
</ul>
<p class="image"><img src="gui1.png" alt=
"Example GUI screen with the Status commands selected" /><br />
Example GUI screen with the <kbd>Status</kbd> commands selected</p>
<p>If you run a more complicated command, like <code>fcm
branch-create</code>, which prompts for input then extra entry windows will
pop up.</p>
<p class="image"><img src="gui2.png" alt="Example GUI pop-up window" /><br />
Example GUI pop-up window</p>
<h4 id="svn_gui_commands">GUI Commands</h4>
<p>The commands available from the GUI should be self explanatory. A few
points to note:</p>
<ul>
<li>If the current directory is not a working copy, you will only be able
to Checkout a working copy or create a branch from the GUI.</li>
<li>The <kbd>Checkout</kbd> command is only available if you start the GUI
in a directory which is not already a working copy. After successfully
running a checkout the GUI automatically sets the working directory to the
top of this new working copy.</li>
<li>With some commands (Status, Diff, Add, Delete, Conflicts) you can
choose whether to run from the top level of your working copy or from your
working directory. With the remaining commands this would not make sense
and they can only be run from the top level.</li>
<li>You can only issue commands from the GUI if they do not need to prompt
you for authentication (i.e. the Subversion command can be run with the
<code>--non-interactive</code> option).
<ul>
<li>If authentication is required then the command issued by the GUI
will fail. For the <code>branch-create</code>,
<code>branch-delete</code> and <code>commit</code> commands, which
support the <code>--password</code> option, you should specify your
password in <kbd>Other options</kbd> and click <kbd>Run</kbd> again.
For other commands, you should run the command in interactive mode on
the command line. Use the command displayed in the GUI text window but
remove the <code>--non-interactive</code> option.</li>
<li>Most repositories will be configured so that you only need
authentication for writing (not reading). Therefore, the first command
requiring authentication will probably be creating a branch or
commiting to the trunk.</li>
<li>You should only need to do this the first time you ever issue such
a command on a each repository (unless the repository is moved to a new
location) since the Subversion client caches this information for
future comamnds .</li>
</ul>
</li>
</ul>
<h3 id="svn_problems">Known Problems with Subversion</h3>
<p>There is a limitation with Subversion which you should be aware of. The
<code>svn rename</code> command is not a true rename/move operation, but is
implemented as a copy and delete. As a result, if you rename an item in a
branch, and later attempt to merge it back to the trunk, the operation may
not be handled correctly by <code>svn merge</code> (see <a href=
"http://subversion.tigris.org/issues/show_bug.cgi?id=898">subversion issue
898</a> for further details). Until such time as support for a <q title=
"http://subversion.tigris.org/issues/show_bug.cgi?id=898">true rename</q> is
implemented in Subversion, you should avoid renaming of files or directories
unless you can ensure that no-one is working in parallel on the affected
areas of the project.</p>
<h2 id="trac">Using Trac</h2>
<p><cite>Trac</cite> has a simple and intuitive web interface which is
relatively easy to pick up. It also includes a <a href=
"http://trac.edgewall.org/wiki/TracGuide">User and Administration Guide</a>
which is full of helpful information (and is referred to extensively in this
section).</p>
<p>Trac contains a menu bar at the top of each page (which we will refer to
as the <cite>Trac menu</cite>). This provides access to all the main
features.</p>
<h3 id="trac_login">Logging In</h3>
<p>Although different projects may choose their own rules, we expect that
most systems will have Trac configured so that all the information is
viewable by anyone. However, in order to make any changes you will need to
login. This ensures that any changes are identified with the appropriate
userid.</p>
<p>In the rest of this section it is assumed that you have logged in to Trac
and are therefore able to make changes.</p>
<p>If you haven't yet got a Trac userid (which should be the same as the
userid you use for committing changes to Subversion) then please contact your
system manager.</p>
<h3 id="trac_wiki">Using the Wiki Pages</h3>
<p>A wiki enables documents to be written in a simple markup language using a
web browser. See the Trac Guide for information on the <a href=
"http://trac.edgewall.org/wiki/TracWiki">Trac Wiki Engine</a>. Make sure that
you read the information provided on:</p>
<ul>
<li><a href="http://trac.edgewall.org/wiki/WikiFormatting">Wiki
Formatting</a> which explains how to format your wiki pages.</li>
<li><a href="http://trac.edgewall.org/wiki/WikiPageNames">Wiki Page
Names</a> which explains how <em>CamelCase</em> is used to create <a href=
"http://trac.edgewall.org/wiki/WikiNewPage">New Wiki Pages</a>.</li>
<li><a href="http://trac.edgewall.org/wiki/TracLinks">Trac Links</a> which
allow hyperlinking between Trac entities (tickets, reports, changesets,
Wiki pages, milestones and source files). This is a fundamental feature of
Trac which makes it easy, for example, to link a bug report (ticket) to the
changeset which fixed the bug (and vice-versa).</li>
</ul>
<p>Whenever you are viewing a wiki page in Trac you should see several
buttons at the bottom of the page:</p>
<ul>
<li><kbd>Edit This Page</kbd> - Clicking this will bring up a page where
you can edit the page contents. Before saving your changes you can preview
how the modified page will appear. You can also leave a comment explaining
what changes you made.</li>
<li><kbd>Attach File</kbd> - Allows you to attach files to a page, e.g. an
image.</li>
<li>If you have admin rights then you will also see
<ul>
<li><kbd>Delete This Version</kbd> - Delete the particular version of
the page you are viewing.</li>
<li><kbd>Delete Page</kbd> - Delete the page and all its history.</li>
</ul>Use with care - these operations are irreversible!
</li>
</ul>
<p>At the top of each wiki page at the right hand side you can select
<kbd>Page History</kbd>. This shows you the full history of each page with
details of when each change was made, who made the change and what the
changes were.</p>
<h3 id="trac_browser">Using the Repository Browser</h3>
<p>The <a href="http://trac.edgewall.org/wiki/TracBrowser">Trac Browser</a>
is used to view the contents of your repository. To get to it just select
<kbd>Browse Source</kbd> from the Trac menu. You can view directories and
files at any version, see their revision histories and view <a href=
"http://trac.edgewall.org/wiki/TracChangeset">changesets</a>. Any wiki
formatting in log messages is recognised and interpreted so you can easily
link a changeset to a Trac ticket by using <a href=
"http://trac.edgewall.org/wiki/TracLinks">Trac Links</a>.</p>
<h3 id="trac_tickets">Using the Issue Tracker</h3>
<p>The Trac issue database provides a way of tracking issues within a project
(e.g. bug reports, feature requests, software support issues, project tasks).
Within Trac an issue is often referred to as a <em>Ticket</em>.</p>
<p>Please refer to the Trac Guide for the following information:</p>
<ul>
<li>
<a href="http://trac.edgewall.org/wiki/TracTickets">The Trac Ticket
System</a> - Creating and modifying tickets.
<ul>
<li>Only Trac accounts with admin rights can modify ticket
descriptions.</li>
</ul>
</li>
<li><a href="http://trac.edgewall.org/wiki/TracQuery">Trac Ticket
Queries</a> - List tickets matching your chosen criterion.</li>
</ul>
<h3 id="trac_roadmap">Using the Roadmap</h3>
<p>Each ticket can be assigned to a milestone. The Trac Roadmap can then be
used to provide a view on the ticket system. This can useful to see what
changes went into a particular system release or what changes are outstanding
before a milestone can be reached.</p>
<p>Please refer to the Trac Guide for further information on the <a href=
"http://trac.edgewall.org/wiki/TracRoadmap">Trac Roadmap</a>.</p>
<ul>
<li>Only Trac accounts with admin rights can add, modify and remove
milestones using the web interface.</li>
</ul>
<h3 id="trac_timeline">Using the Timeline</h3>
<p>The <a href="http://trac.edgewall.org/wiki/TracTimeline">Trac Timeline</a>
allows you to list all the activity on a project over any given period. It
can list:</p>
<ul>
<li>Creation and changes to wiki pages.</li>
<li>Creation, closure and changes to tickets.</li>
<li>Commits to the Subversion repository.</li>
<li>Milestones reached.</li>
</ul>
</div>
</div>
</div>
<hr/>
<div class="container-fluid text-center">
<div class="row"><div class="col-md-12">
<address><small>
© British Crown Copyright 2006-16
<a href="http://www.metoffice.gov.uk">Met Office</a>.
See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
This document is released under the British <a href=
"http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
"license">Open Government Licence</a>.<br />
</small></address>
</div></div>
</div>
<script type="text/javascript" src="../etc/jquery.min.js"></script>
<script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
<script type="text/javascript" src="../etc/fcm.js"></script>
<script type="text/javascript" src="../etc/fcm-version.js"></script>
</body>
</html>
|