Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Changed main document class to koma script book (scrbook) and added chapter headings to all chapters |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | 2ndEdition |
Files: | files | file ages | folders |
SHA1: |
7d50e0d156b82660fae3cc091265cddd |
User & Date: | frans 2012-11-28 20:49:03.819 |
Context
2012-11-28
| ||
21:37 | Minor corrections in document layout check-in: 7530de7b06 user: frans tags: 2ndEdition | |
20:49 | Changed main document class to koma script book (scrbook) and added chapter headings to all chapters check-in: 7d50e0d156 user: frans tags: 2ndEdition | |
20:09 | Initial commit, all content is identical, but moved the book to a main tex file with a chapter listing as \include{} check-in: 71c9156209 user: frans tags: 2ndEdition | |
Changes
Changes to Chapters/commands.tex.
1 2 |
| | | | | | 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 | \chapter{Fossil Commands} \section{Introduction} This section will go through the various Fossil command line commands. This will be divided into sections, the first will detail the must know commands. These are the ones you will be using all the time and will probably have memorized in short order. The other commands will be divided into Maintenance, Advanced, and Miscellaneous. These you will probably be checking as reference before use. The most important command is \textbf{help}. You can always type \textbf{fossil help} at the command line and it will list out all the commands it has. Then typing f\textbf{ossil help <command> }will print out the detailed information on that command. You always have that as your reference. This section of the book will try to supplement the built in help with some examples and further explanation of what a command does. All of the commands will be placed in the index for easy searching \textbf{NOTE:} Fossil is a moving target, commands might be added and others removed future versions. Type \textbf{fossil help }on your version to get the latest list. The following applies to the fossil I used when I wrote this and your version might be different. \section{Basic Commands} \subsection{help\index{help}} This command is used to dump the current command set and version of Fossil. It can also be used in the form \textbf{fossil help <command> }to get further information on any command. \begin{figure}[H] \noindent \begin{centering} \includegraphics{Images/Commands/help1} \par\end{centering} |
︙ | ︙ | |||
51 52 53 54 55 56 57 | \caption{Help detail} \end{figure} | | | 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | \caption{Help detail} \end{figure} \subsection{add\index{add}} The add command is used to add files into a repository. It is recursive and will pull in all files in subdirectories of the current. Fossil will not overwrite any of the files already present in the repository so it is safe to add all the files at any time. Only new files will be added. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil}{\scriptsize{}~}\textbf{\scriptsize help~add}{\scriptsize \par} |
︙ | ︙ | |||
86 87 88 89 90 91 92 | fossil~add~. \end{lyxcode} will add all files in the current directory and subdirectories. Note none of these files are put in the repository untill a commit is done. | | | 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | fossil~add~. \end{lyxcode} will add all files in the current directory and subdirectories. Note none of these files are put in the repository untill a commit is done. \subsection{rm\index{rm} or del\index{del}} The rm command is used to remove files from the repository. The file is not deleted from the file system but it will be dropped from the repository on the next commit. This file will still be available in earlier versions of the repository but not in later ones. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~rm}{\scriptsize \par} |
︙ | ︙ | |||
119 120 121 122 123 124 125 | You can delete groups of files by using wild-cards in their names. Thus if I had a group of files like com\_tr.c, com\_rx.c and com\_mgmt.c I could remove them all with: \begin{lyxcode} fossil~rm~com\_{*}.c \end{lyxcode} By running a ``fossil status'' you can see what files will be deleted on the next commit. | | | 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | You can delete groups of files by using wild-cards in their names. Thus if I had a group of files like com\_tr.c, com\_rx.c and com\_mgmt.c I could remove them all with: \begin{lyxcode} fossil~rm~com\_{*}.c \end{lyxcode} By running a ``fossil status'' you can see what files will be deleted on the next commit. \subsection{rename\index{rename} or mv\index{mv}} This command is used to rename a file in the repository. This does not rename files on disk so is usually used after you have renamed files on the disk then want to change this in the repository. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~rename}{\scriptsize \par} |
︙ | ︙ | |||
146 147 148 149 150 151 152 | \caption{rename detail} \end{figure} Just like add or rm you can use wild cards in the names and rename groups of files. Like them ``fossil status'' will show you the current state. | | | 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | \caption{rename detail} \end{figure} Just like add or rm you can use wild cards in the names and rename groups of files. Like them ``fossil status'' will show you the current state. \subsection{status\index{status}} The status command is used to show you the current state of your files relative to the repository. It will show you files added, deleted, and changed. This is only the condition of files that are already in the repository or under control of fossil. It also shows from where in the timeline you are checked out and where your repository is kept. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~status}{\scriptsize \par} |
︙ | ︙ | |||
179 180 181 182 183 184 185 | \end{figure} The listing above shows where my cloned copy of the repository is kept, where I am working, and the tags show me that I am checked out of the trunk. Finally it shows the status of the files: I am working on two of them. | | | | 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 | \end{figure} The listing above shows where my cloned copy of the repository is kept, where I am working, and the tags show me that I am checked out of the trunk. Finally it shows the status of the files: I am working on two of them. \subsection{changes\index{changes}} This lists the changed files like status but does not show the other information that status does. \begin{figure} \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~changes}{\scriptsize \par} {\scriptsize Usage:~fossil~changes}{\scriptsize \par} {\scriptsize Report~on~the~edit~status~of~all~files~in~the~current~checkout.}{\scriptsize \par} {\scriptsize See~also~the~\textquotedbl{}status\textquotedbl{}~and~\textquotedbl{}extra\textquotedbl{}~commands.}{\scriptsize \par} \end{lyxcode} \caption{changes details} \end{figure} \subsection{extra\index{extra}} The extra command is used to find files you have added to your working directory but are not yet under Fossil control. This is important because if you move your working directory or others attempt to use the repository they won't have these files. \begin{figure}[H] \begin{lyxcode} {\scriptsize Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~extra}{\scriptsize \par} |
︙ | ︙ | |||
243 244 245 246 247 248 249 | {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~\textbf{fossil~extra} Images/Commands/help1.epsf fossilbook.lyx\textasciitilde{} \end{lyxcode} | | | 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 | {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~\textbf{fossil~extra} Images/Commands/help1.epsf fossilbook.lyx\textasciitilde{} \end{lyxcode} \subsection{revert\index{revert}} The revert command is used to take a file back to the value in the repository. This is useful when you make a error in editing or other mistake. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~revert}{\scriptsize \par} |
︙ | ︙ | |||
272 273 274 275 276 277 278 | \end{figure} With no parameters it will revert the file to the current revision, see Figure \vref{fig:status-run}. The -r option allows you to pick any revision from the time line. | | | 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 | \end{figure} With no parameters it will revert the file to the current revision, see Figure \vref{fig:status-run}. The -r option allows you to pick any revision from the time line. \subsection{update\index{update}} The update option will update a file or files to match the repository. With multiple users it should be done before you start working on any files. This ensures you have the latest version of all the files. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~update}{\scriptsize \par} |
︙ | ︙ | |||
335 336 337 338 339 340 341 | fossil~update~{*}.c \end{lyxcode} and it would update all C files. Since this is a rather large set of changes it has a special ``dry run'' mode. If you add -n on the command it will just print out what will be done but not do it. This is very useful to do this trial if you are unsure what might happen. The -v command (which can be used with -n or alone) prints out the action for each file even if it does nothing. | | | 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 | fossil~update~{*}.c \end{lyxcode} and it would update all C files. Since this is a rather large set of changes it has a special ``dry run'' mode. If you add -n on the command it will just print out what will be done but not do it. This is very useful to do this trial if you are unsure what might happen. The -v command (which can be used with -n or alone) prints out the action for each file even if it does nothing. \subsection{checkout\index{checkout} or co\index{co}} This command is similar to update. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~checkout}{\scriptsize \par} |
︙ | ︙ | |||
368 369 370 371 372 373 374 | \caption{checkout or co details} \end{figure} | | | 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 | \caption{checkout or co details} \end{figure} \subsection{undo\index{undo}} This is used to undo the last update, merge, or revert operation. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~undo}{\scriptsize \par} |
︙ | ︙ | |||
401 402 403 404 405 406 407 | \end{figure} It acts on a single file or files if specified, otherwise if no file given, it undoes all of the last changes. | | | 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 | \end{figure} It acts on a single file or files if specified, otherwise if no file given, it undoes all of the last changes. \subsection{diff\index{diff}} The diff command is used to produce a text listing of the difference of a file in the working directory and that same file in the repository. If you don't specify a file it will show the differences between all the changed files in the working directory vs the repository. If you use the --from and --to options you can specify which versions to check and to compare between two different versions in the repository. Not using the --to means compare with the working directory. If you have configured an external diff program it will be used unless you use the -i option which uses the diff built into Fossil. \begin{figure}[H] \begin{lyxcode} |
︙ | ︙ | |||
456 457 458 459 460 461 462 | \caption{diff details} \end{figure} | | | 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 | \caption{diff details} \end{figure} \subsection{gdiff\index{gdiff}} This is the same as the diff command but uses (if configured) a graphical diff program you have on your system. See the settings command for details on how to set the graphical diff program. \begin{figure} \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~gdiff}{\scriptsize \par} |
︙ | ︙ | |||
503 504 505 506 507 508 509 | \caption{gdiff details} \end{figure} | | | 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 | \caption{gdiff details} \end{figure} \subsection{ui\index{ui} } The ui command is used to start Fossil in a local webserver. The --port option is used to specify the port it uses, by default it uses 8080. It should automatically start the system's web browser and it will come up with the repository web page. If run within a working directory it will bring up the web page for that repository. If run outside the working directory you can specify the repository on the command line. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~ui}{\scriptsize \par} |
︙ | ︙ | |||
548 549 550 551 552 553 554 | {\scriptsize various~repositories.}{\scriptsize \par} \end{lyxcode} \caption{ui details} \end{figure} | | | 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 | {\scriptsize various~repositories.}{\scriptsize \par} \end{lyxcode} \caption{ui details} \end{figure} \subsection{server\index{server}} This is a more powerful version of the ui command. This allows you to have multiple repositories supported by a single running Fossil webserver. This way you start the server and instead of a paricular repository you specify a directory where a number of repositories reside (all having the extension .fossil) then you can open and use any of them. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~server}{\scriptsize \par} |
︙ | ︙ | |||
589 590 591 592 593 594 595 | \caption{server detail\label{fig:server-detail}} \end{figure} | | | 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 | \caption{server detail\label{fig:server-detail}} \end{figure} \subsection{commit\index{commit} or ci\index{ci}} This is the command used to put the current changes in the working directory into the repository, giving this a new version and updating the timeline. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~commit}{\scriptsize \par} |
︙ | ︙ | |||
676 677 678 679 680 681 682 | \end{figure} It's a very good idea to always put a comment (-comment or -m) text on any commit. This way you get documentation in the timeline. | | | | 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 | \end{figure} It's a very good idea to always put a comment (-comment or -m) text on any commit. This way you get documentation in the timeline. \section{Maintenance commands} These commands you will probably use less often since the actions they perform are not needed in normal operation. You will have to use them and referring here or to \textbf{fossil help} will probably be required before use. Some of them like new or clone are only needed when you start a repository. Others like rebuild or reconstruct are only needed to fix or update a repository. \subsection{new\index{new}} This command is used to create a new repository. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~new}{\scriptsize \par} |
︙ | ︙ | |||
722 723 724 725 726 727 728 | \end{figure} The file name specifies the new repository name. The options provided allow you to specify the admin user name if you want it to be different than your current login and the starting date if you want it to be different than now. | | | 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 | \end{figure} The file name specifies the new repository name. The options provided allow you to specify the admin user name if you want it to be different than your current login and the starting date if you want it to be different than now. \subsection{clone\index{clone}} The clone command is used to create your own local version of the master repository. If you are supporting multiple users via a network accessible version of the original repository (see Section\vref{sub:Server-Setup}), then this command will copy that repository to your machine. Also it will make a link between your copy and the master, so that changes made in your copy will be propagated to the master. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~help~clone}{\scriptsize \par} |
︙ | ︙ | |||
771 772 773 774 775 776 777 | http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi \end{lyxcode} Putting that into a browser should get you the home page for this book. (See Figure \vref{fig:Web-access-to}). After you have verified that, then running the clone command should work. Don't forget (as I always do) to put in the file name for the local repository, (see FILENAME above) | | | 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 | http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi \end{lyxcode} Putting that into a browser should get you the home page for this book. (See Figure \vref{fig:Web-access-to}). After you have verified that, then running the clone command should work. Don't forget (as I always do) to put in the file name for the local repository, (see FILENAME above) \subsection{open\index{open}} The open command is used to copy the files in a repository to a working directory. Doing this allows you to build or modify the product. The command also links this working directory to the repository so commits will go into the repository. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~open}{\scriptsize \par} |
︙ | ︙ | |||
806 807 808 809 810 811 812 | \end{figure} If you have multiple users or have a branched repository then it is probably wise to specify the particular version you want. When you run this it will create all the files and directories in the repository in your work area. In addition the files \_FOSSIL\_, manifiest and manifest.uuid will be created by Fossil. | | | 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 | \end{figure} If you have multiple users or have a branched repository then it is probably wise to specify the particular version you want. When you run this it will create all the files and directories in the repository in your work area. In addition the files \_FOSSIL\_, manifiest and manifest.uuid will be created by Fossil. \subsection{close\index{close}} This is the opposite of open, in that it breaks the connection between this working directory and the Fossil repository. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~close}{\scriptsize \par} |
︙ | ︙ | |||
833 834 835 836 837 838 839 | \end{figure} This is useful if you need to abandon the current working directory. Fossil will not let you do this if there are changes between the current directory and the repository. With the force flag you can explicitly cut the connection even if there are changes. | | | 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 | \end{figure} This is useful if you need to abandon the current working directory. Fossil will not let you do this if there are changes between the current directory and the repository. With the force flag you can explicitly cut the connection even if there are changes. \subsection{version\index{version}} This command is used to show the current version of fossil. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~version}{\scriptsize \par} |
︙ | ︙ | |||
862 863 864 865 866 867 868 | \end{figure} The above figure shows the help and example of running the command. When you have problems with fossil it is very important to have this version information. You can then inquire of the Fossil news group about this problem and with the version information they can easily tell you if the problem is fixed already or is new. | | | 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 | \end{figure} The above figure shows the help and example of running the command. When you have problems with fossil it is very important to have this version information. You can then inquire of the Fossil news group about this problem and with the version information they can easily tell you if the problem is fixed already or is new. \subsection{rebuild\index{rebuild}} If you update your copy of Fossil you will want to run this command against all the repositories you have. This will automatically update them to the new version of Fossil. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~rebuild}{\scriptsize \par} |
︙ | ︙ | |||
885 886 887 888 889 890 891 | \caption{rebuild details} \end{figure} | | | 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 | \caption{rebuild details} \end{figure} \subsection{all\index{all}} This command is actually a modifier and when used before certain commands will run them on all the repositories. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~all}{\scriptsize \par} |
︙ | ︙ | |||
928 929 930 931 932 933 934 | \caption{all details} \end{figure} | | | 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 | \caption{all details} \end{figure} \subsection{push\index{push}} This command will push changes in the local repository to the master or remote repository. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~push}{\scriptsize \par} |
︙ | ︙ | |||
965 966 967 968 969 970 971 | \caption{push details} \end{figure} | | | 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 | \caption{push details} \end{figure} \subsection{pull\index{pull}} This command will copy changes from the remote repository to the local repository. You could then use \textbf{update} to apply these changes to checked out files. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~pull}{\scriptsize \par} |
︙ | ︙ | |||
1004 1005 1006 1007 1008 1009 1010 | \caption{pull details} \end{figure} | | | 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 | \caption{pull details} \end{figure} \subsection{sync\index{sync}} This command is used to sync a remote copy with the original copy of the repository, it does both a push and pull. This can also be used to switch a local repository to a different main repository by specifying the URL of a remote repository. If you want to run the update command with -n where it does a dry run, this does not do a sync first so doing fossil sync then fossil update -n will do that for you. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~sync}{\scriptsize \par} |
︙ | ︙ | |||
1047 1048 1049 1050 1051 1052 1053 | \caption{sync details} \end{figure} | | | 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 | \caption{sync details} \end{figure} \subsection{clean\index{clean}} This call can be used to remove all the ``extra'' files in a source tree. This is useful if you wish to tidy up a source tree or to do a clean build. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~clean}{\scriptsize \par} |
︙ | ︙ | |||
1082 1083 1084 1085 1086 1087 1088 | \caption{clean details} \end{figure} | | | 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 | \caption{clean details} \end{figure} \subsection{branch\index{branch}} This command is used if you want to create or list branches in a repository. Previously we discussed forks ( See Section \vref{sub:Complications}); branches are the same idea but under user control. This would be where you have version 1.0 of something but want to branch off version 2.0 to add new features but want to keep a 1.0 branch for maintenance. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~branch}{\scriptsize \par} |
︙ | ︙ | |||
1113 1114 1115 1116 1117 1118 1119 | \caption{branch details} \end{figure} | | | 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 | \caption{branch details} \end{figure} \subsection{merge\index{merge}} This command does the opposite of branch, it brings two branches together. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~merge}{\scriptsize \par} |
︙ | ︙ | |||
1160 1161 1162 1163 1164 1165 1166 | \caption{merge details} \end{figure} | | | 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 | \caption{merge details} \end{figure} \subsection{tag\index{tag}} This command can be used to control ``tags'' which are attributes added to any entry in the time line. You can also add/delete/control these tags from the UI by going into the timeline, picking an entry then doing an edit. See Figure \vref{fig:Remove-Leaf}. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~tag}{\scriptsize \par} |
︙ | ︙ | |||
1231 1232 1233 1234 1235 1236 1237 | \caption{tag details} \end{figure} | | | 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 | \caption{tag details} \end{figure} \subsection{settings\index{settings}} This command is used to set or unset a number of properties for fossil. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~settings}{\scriptsize \par} |
︙ | ︙ | |||
1344 1345 1346 1347 1348 1349 1350 | \caption{settings details} \end{figure} | | | | 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 | \caption{settings details} \end{figure} \section{Miscellaneous } These are commands that don't seem to fit in any category but are useful. \subsection{zip\index{zip}} You can do what this command does from the web based user interface. In Figure \vref{fig:Timeline-Detail} you can download a ZIP archive of the particular version of the files. This command lets you do it from the command line. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~zip}{\scriptsize \par} |
︙ | ︙ | |||
1376 1377 1378 1379 1380 1381 1382 | \caption{zip detail} \end{figure} | | | 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 | \caption{zip detail} \end{figure} \subsection{user\index{user}} This command lets you modify user information. Again this is a command line duplication of what you can do from the user interface in the browser, see Figure \vref{fig:New-Editor-user}. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~user}{\scriptsize \par} |
︙ | ︙ | |||
1423 1424 1425 1426 1427 1428 1429 | \caption{user detail} \end{figure} | | | 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 | \caption{user detail} \end{figure} \subsection{finfo\index{finfo}} This command will print the history of any particular file. This can be useful if you need this history in some other system. You can pass this text file to the other system which can than parse and use the data. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~finfo}{\scriptsize \par} |
︙ | ︙ | |||
1494 1495 1496 1497 1498 1499 1500 | {\scriptsize{}~~~~~~~~~~~artifact:~{[}b870231e48{]})}{\scriptsize \par} {\scriptsize 2010-04-25~{[}8fa0708186{]}~Initial~Commit~(user:~jim,~artifact:~{[}34a460a468{]})}{\scriptsize \par} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}{\scriptsize \par} \end{lyxcode} | | | 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 | {\scriptsize{}~~~~~~~~~~~artifact:~{[}b870231e48{]})}{\scriptsize \par} {\scriptsize 2010-04-25~{[}8fa0708186{]}~Initial~Commit~(user:~jim,~artifact:~{[}34a460a468{]})}{\scriptsize \par} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}{\scriptsize \par} \end{lyxcode} \subsection{timeline\index{timeline}} This prints out the timeline of the project in various ways. The command would be useful if you were building a GUI front end for Fossil and wanted to display the timeline. You could issue this command and get the result back and display it in your UI. There are a number of options in the command to control the listing. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~timeline}{\scriptsize \par} |
︙ | ︙ | |||
1547 1548 1549 1550 1551 1552 1553 | \caption{timeline detail} \end{figure} | | | 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 | \caption{timeline detail} \end{figure} \subsection{wiki\index{wiki}} This command allows you to have command line control of the wiki. Again this is useful if you were writing a shell to control Fossil or wanted to add a number of computer generated pages to the Wiki. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~wiki}{\scriptsize \par} |
︙ | ︙ | |||
1614 1615 1616 1617 1618 1619 1620 | \caption{wiki detail} \end{figure} | | | | 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 | \caption{wiki detail} \end{figure} \section{Advanced} These are commands that you will rarely have to use. These are functions that are needed to do very complicated things with Fossil. If you have to use these you are probably way beyond the audience for this book. \subsection{scrub\index{scrub}} This is used to removed sensitive information like passwords from a repository. This allows you to then send the whole repository to someone else for their use. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~scrub}{\scriptsize \par} |
︙ | ︙ | |||
1658 1659 1660 1661 1662 1663 1664 | \caption{scrub detail} \end{figure} | | | | 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 | \caption{scrub detail} \end{figure} \subsection{search\index{search}} This is used to search the timeline entries for a pattern. This can also be done in your browser on the timeline page. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~search}{\scriptsize \par} {\scriptsize COMMAND:~search}{\scriptsize \par} {\scriptsize fossil~search~pattern...}{\scriptsize \par} {\scriptsize Search~for~timeline~entries~matching~the~pattern.}{\scriptsize \par} \end{lyxcode} \caption{search detail} \end{figure} \subsection{sha1sum\index{sha1sum}} This can compute the sha1 value for a particular file. These sums are the labels that Fossil uses on all objects and should be unique for any file. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~sha1sum}{\scriptsize \par} |
︙ | ︙ | |||
1702 1703 1704 1705 1706 1707 1708 | \caption{sha1sum detail} \end{figure} | | | 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 | \caption{sha1sum detail} \end{figure} \subsection{rstats\index{rstats}} \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~rstats}{\scriptsize \par} {\scriptsize Usage:~fossil~rstats}{\scriptsize \par} |
︙ | ︙ | |||
1741 1742 1743 1744 1745 1746 1747 | Number~Of~Wiki~Pages:~2 ~~~Number~Of~Tickets:~6 ~Duration~Of~Project:~23~days \end{lyxcode} | | | 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 | Number~Of~Wiki~Pages:~2 ~~~Number~Of~Tickets:~6 ~Duration~Of~Project:~23~days \end{lyxcode} \subsection{configuration\index{configuration}} This command allows you to save or load a custom configuration of Fossil. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~fossil~}\textbf{\scriptsize help~configuration}{\scriptsize \par} |
︙ | ︙ | |||
1808 1809 1810 1811 1812 1813 1814 | \caption{configuration detail} \end{figure} | | | 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 | \caption{configuration detail} \end{figure} \subsection{descendants\index{descendants}} This is used to find where the checked out files are in the time line. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~help~descendants}{\scriptsize \par} |
︙ | ︙ |
Changes to Chapters/foreword.tex.
1 | \chapter{Foreword} | > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | \chapter{Foreword} \medskip{} Pandora Products has carefully checked the information in this document and believes it to be accurate. However, Pandora Products assumes no responsibility for any inaccuracies that this document may contain. In no event will Pandora Products be liable for direct, indirect, special, exemplary, incidental, or consequential damages resulting from any defect or omission in this document, even if advised of the possibility of such damages. In the interest of product development, Pandora Products reserves the right to make improvements to the information in this document and the products that it describes at any time, without notice or obligation. Additional Contributors \begin{itemize} \item Marilyn Noz - Editor \item Wolfgang Stumvoll - Fossil Merge use and Windows use \item javalinBCD@gmail.com - found bugs \item arnel\_legaspi@msn.com - found bugs \end{itemize} \newpage{} |
Changes to Chapters/forks_branches.tex.
|
| < | | | | | | 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 | \chapter{Forks \& Branches} \section{Introduction} This chapter will cover forking and branching in Fossil. Forking is where you unintentially create two places to check into a repository. Branching is where you intentially do this because you want to maintain two or more versions of the code in the same repository. We illustrated forking and it's solutions in Section \vref{sub:Complications}. If, instead of fixing (merging) the file then doing the commit, we forced the commit, Fossil would fork the repository. Forking is something to avoid because it creates two checkin paths for the code. Thus different users will be on different paths and can check in contradictory changes. Branches on the other hand are forks that you desire. These occur when you want to have two different versions of the code base in development at the same time. This was described in \vref{versioning} where you have a production verison of code under maintenance and a development version both served from the same repository. In this case development changes should only be checked into the development branch. Maintanence changes might have to be checked into both. Instead of using the book repository for these examples we will use a JSON\cite{JSON}parser program that has a number of files and documentation. This will make it simpler to illustrate branching and tagging. There is a good discussion of these topics on the Fossil Web site \url{http://www.fossil-scm.org/index.html/doc/tip/www/branching.wiki}. \section{Forks, Branch \& Merge} In this case the JSON code has just been placed in Fossil and two developers check out copies to work on. Jim wants to fix a number of compiler warnings that appear and Marilyn wants to fix the documentation. In both cases they proceeed as shown in Chapter \vref{sec:Multiple-Users}. The JSON code has been placed in a distributed location, each of them clones the repository, and opens a working copy of the code. \subsection{Marilyn's Actions} She looks through the documentation and finds a number of problems and fixes them (the documentation uses \LyX{} and PDF's). When she is satisfied with what she has done, she checks the current version of the documentation in: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Advanced/Simple_Merge/sm_Marilyn} \caption{\label{fig:Marilyn's-work}Marilyn's work} \end{figure} \subsection{Jim's Actions} At the same time, Jim gets a working copy of version {[}6edbaf5fa8{]} of the code, puts in a ticket {[}d23bf4bbbb{]} as shown in Figure \ref{fig:Marilyn's-work}. After fixing the warnings, Jim is done and goes to commit. He does this AFTER Marilyn has done her commit. \begin{figure}[H] \begin{lyxcode} {\footnotesize 551~jsonp>~}\textbf{\footnotesize fossil~commit~-m~\textquotedbl{}{[}d23bf4bbbb{]}~Remove~warnings\textquotedbl{}}{\footnotesize \par} |
︙ | ︙ | |||
104 105 106 107 108 109 110 | \end{figure} Not good, there are two \textbf{Leaf}'s and Marilyn would commit code to her fork and Jim would be commiting code to his. So Jim must fix this by merging the code. Jim wants to merge versions {[}b72e96832e{]} of Marilyn and his {[}1beab85441{]}. | | | 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | \end{figure} Not good, there are two \textbf{Leaf}'s and Marilyn would commit code to her fork and Jim would be commiting code to his. So Jim must fix this by merging the code. Jim wants to merge versions {[}b72e96832e{]} of Marilyn and his {[}1beab85441{]}. \subsection{Fixing the fork} So Jim who's checked out code is from Leaf {[}1beab85441{]} does a merge with Marilyn's leaf {[}b72e96832e{]} like so: \begin{figure}[H] \begin{lyxcode} {\footnotesize 556~jsonp>~}\textbf{\footnotesize fossil~merge~b72e96832e}{\footnotesize \par} |
︙ | ︙ | |||
224 225 226 227 228 229 230 | \caption{Marilyn's Update} \end{figure} | | | | | 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 | \caption{Marilyn's Update} \end{figure} \subsection{Commands used} \begin{itemize} \item \textbf{fossil merge <fork>} Used to merge a fork (specified by hash value) to current check out. \item \textbf{fossil update <version>} Used to update current check out to specified version, if version not present use default tag for check out (see fossil status) \end{itemize} \section{Merge without fork} In this case I will show how to merge in code changes from multiple users without causing a fork. In this case Marilyn has put in a BSD license text into all the code files while Jim is adding a help function to the code. In this case both of them put in tickets saying what they are doing but acting independently. \subsection{Check in attempt} Marilyn finished first and checks in her changes. Jim builds, tests and tries to check in his code and gets: \begin{figure}[H] \begin{lyxcode} {\footnotesize 502~jsonp>~}\textbf{\footnotesize make}{\footnotesize \par} |
︙ | ︙ | |||
296 297 298 299 300 301 302 | \caption{Jim's check in attempt} \end{figure} | | | 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 | \caption{Jim's check in attempt} \end{figure} \subsection{Update} The next action Jim takes is to do the update but without doing changes, using the -n flag which tells it to just show what's going to happen without making any file changes. \begin{figure}[H] \begin{lyxcode} 507~jsonp>~\textbf{fossil~update~-n} |
︙ | ︙ | |||
336 337 338 339 340 341 342 | \caption{Merged repository} \end{figure} | | | | | | 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 | \caption{Merged repository} \end{figure} \subsection{Commands used} \begin{itemize} \item \textbf{fossil update -n} Does a dry run of an update to show what files will changed. \begin{itemize} \item UPDATE Implies file will be replaced by repository file \item MERGE Implies file will be mixed text from repository and check out \end{itemize} \end{itemize} \section{Branching} \subsection{Introduction} We have discussed this before but branching is the intential splitting of the code in the repository into multiple paths. This will usually be done with production code where we have maintenance branch and a development branch. The maintenance branch is in use and would get bug fixes based on experience. The development branch would get those changes if applicable plus be modified to add features. The JSON code parser has been tested and works so will be released to general use. Also we wish to modify it to add support for UTF-8 characters so it matches the JSON standard. The current version just works with ASCII 7 bit characters which is not standard. We wish to split the code into a VER\_1.0 branch which is the current code in use and VER\_2.0 branch which will add UTF-8 character support. \subsection{Branch the repository} Before proceeding we will make sure we have the current trunk code in our check out. \begin{figure}[H] \begin{lyxcode} {\footnotesize {[}Pandora-2:jschimpf/Public/jsonp{]}~jim\%~}\textbf{\footnotesize fossil~status}{\footnotesize \par} |
︙ | ︙ | |||
436 437 438 439 440 441 442 | \includegraphics[scale=0.6]{Images/Advanced/Branching/branch} \caption{Branch Timeline} \end{figure} | | | | 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 | \includegraphics[scale=0.6]{Images/Advanced/Branching/branch} \caption{Branch Timeline} \end{figure} \subsection{Color Setup} As you see above the two branches have different colors in the timeline. This was due to the \textbf{-bgcolor} option added when we created each branch. (See Figure \ref{fig:Branch-commands}). But we want this color to appear on subsequent checkins of each of these branches. To make that happen we have to set the options using the UI and picking a particular leaf on the timeline. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Advanced/Branching/color_setup} \caption{Setting Timeline color} \end{figure} Under the \textbf{Background Color} section I have checked \textbf{Propagate color to descendants }so future checkins will have the same color. \subsection{Check out the branches} Now the the repository is branched we can check out the two sets of code into different directories. We create jsonp1 and jsonp2 and proceed to open the different branches into them. \begin{figure}[H] \begin{lyxcode} {\footnotesize {[}Pandora-2:jschimpf/Public/jsonp1{]}~}\textbf{\footnotesize jim\%~fossil~open~../FOSSIL/jsonp.fossil~VER\_1.0}{\footnotesize \par} |
︙ | ︙ | |||
553 554 555 556 557 558 559 | \caption{VER\_2.0 checkout} \end{figure} Notice on both of these the tags show which branch we are attached to. | | | 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 | \caption{VER\_2.0 checkout} \end{figure} Notice on both of these the tags show which branch we are attached to. \subsection{Correcting errors (in both)} After doing this work I found that the main.c file had a warning about an unused variable. I wanted to correct this in both branches. At this point all the files in both branches are the same so correcting the file in either branch and copying it to the other is possible. I put in a ticket for the change and edit main.c. I copy it to both checkouts for the both branches and then check both in. \begin{figure} \begin{lyxcode} {\footnotesize {[}Pandora-2:jschimpf/Public/jsonp1{]}~jim\%~}\textbf{\footnotesize fossil~commit~-m~\textquotedbl{}{[}2795e6c74d{]}~Fix~unused~variable\textquotedbl{}}{\footnotesize \par} |
︙ | ︙ | |||
657 658 659 660 661 662 663 | \caption{Correcting both branches} \end{figure} | | | 656 657 658 659 660 661 662 663 664 665 666 | \caption{Correcting both branches} \end{figure} \subsection{Commands used} \begin{itemize} \item \textbf{fossil branch }Used to generate a branch of the repository. The command can optionally color the branch in the display. \end{itemize} |
Changes to Chapters/introduction.tex.
|
| | < | | | | | | | | | 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 | \chapter{Source Control \& Why you need it} \section{What is it} A source control system is software that manages the files in a project. A project (like this book or a software application) usually has a number of files. You then put all these files in a directory and at times subdivide even that with subdirectories. At any particular time this set of files in their present edited state make up a working version of the project. If other people are using the project you give them this and as is usually the case, they find problems and you fix them. This results in another version of the project slightly changed which goes through the cycle again. (This is why books have editions and software has versions...) Software developers on large projects with multiple developers could see this cycle and realized they needed a tool to control the changes. With multiple developers sometimes the same file would be edited by two different people changing it in different ways or records of what got changed would be lost. It was hard to bring out a new release of the software and be sure that all the bugs were fixed and enhancements made. A tool called Source Code Control System \cite{SCCS} was developed at Bell Labs in 1972 to track changes in files. It would remember each of the changes made to a file and store comments about why this was done. It also limited who could edit the file so conflicting edits would not be done. \cite{USE-SCCS} \label{versioning}This was important but developers could see more was needed. They needed to be able to save the state of all the files in a project and give it a name (i.e., Release 3.14). As software projects mature you will have a released version of the software being used as well as bug reports written against it, while the next release of the software is being developed adding new features. The source control system would have to handle what are now called branches. One branch has say Version 1 which is released but continues to have fixes added to create Version 1.1, 1.2, etc. At the same time you also have another branch which contains Version 2 with new features added under construction. In 1986 the open source Concurrent Version Control system CVS \cite{CVS} was developed. This system could label groups of files and allow multiple branches (i.e. versions) simultaneously. There have been many other systems developed since them some open source and some proprietary. Fossil which was originally released in 2006 \cite{FOSSIL-HOME} is a easy to install version control system that also includes a trouble ticketing system ( Figure\vref{fig:viewticket}), a wiki ( Figure \vref{sub:Wiki-Use}) and self hosted web server ( Figure\vref{fig:Starting-Webserver}). It's home page is here \url{http://www.fossil-scm.org/}. \section{Why do it ?} Why do you want to use a source control system? To use one restricts your freedom, you won't be able to create files, delete files or, move files between directories at random. Making changes in your code becomes a check list of steps that must be followed carefully. With all those hassles why do it? The biggest answer is freedom (huh ?). By following the procedures of a source control system you gain the freedom to modify your code any way you want. How does that follow ? One of the most horrible feelings as a developer is the ``It worked yesterday'' syndrome. That is, you had code that worked just fine and now it doesn't. You have a very helpless feeling of how do you get back to working code. With a source control system and careful adherence to procedures you can just go back in time and get yesterday's code. Then, starting from known good code you can figure out what happened. Having a source control system also gives you the freedom to experiment, ``let's try that radical new technique'', and if it doesn't work it's easy to just go back to the previous state. The rest of this book is a user manual for the Fossil version control system that does code management and much much more. It runs on multiple OS's and is FREE. It is simple to install as it has only one executable and the repositories it creates are a single file that is easy to back up and are usually only 50\% the size of the original source. \subsection{How to get it} If this has interested you then you can get a copy of the Fossil executable here \url{http://www.fossil-scm.org/download.html}. There are Linux, Mac, and Windows executable links on this page. Also there is a source Tarball from which you can compile from source. This web site is self-hosted by Fossil itself (see Section\vref{sec:Multiple-Users}). \section{Source control description} This next section is useful if you have not used source control systems before. I will define some of the vocabulary and explain the basic ideas of source control. \subsection{Check out systems} When describing the grandaddy of source control systems, like SCCS I said it managed the changes for a single file and also prevented multiple people from working on the same file at the same time. This is representative of a whole class of source control systems. In these you have the idea of ``checking-out'' a file so you can edit it. At the same time while other people using the system can see who is working on the file they are prevented from touching it. They can get a read-only copy so they can say build software but only the ``owner'' can edit it. When done editing the ``owner'' checks it back in then anyone else could work on on it. At the same time the system has recorded who had it and the changes made to it. This system works well in small groups with real time communication. A common problem is that a file is checked out by some one else and \textbf{you} have to make a change in it. In a small group setting, just a shout over the cube wall will solve the problem. \subsection{Merge systems} In systems represented by CVS or Subversion the barrier is not getting a file to work on but putting it back under version control. In these systems you pull the source code files to a working directory in your area. Then you edit these files making necessary changes. When done you commit or check them back into the repository. At this point they are back under version control and the system knows the changes from the last version to this version. This gets around the problem mentioned above when others are blocked from working on a file. You now have the opposite problem in that more than one person can edit the same file and make changes. This is handled by the check-in process. There only one person at a time may check in a file. That being the case the system checks the file and if there are changes in repository file that are NOT in the one to be checked in stops the check in process. The system will ask if the user wants to merge these changes into his copy. Once that is done the new version of the file can be checked in. This type of system is used on large projects like the Linux kernel or other systems where you have a large number of geographically distributed contributors. \subsection{Distributed systems} The representatives of two major systems we have described thus far are centralized. That is there is only one repository on a single server. When you get a copy of the files or check in files it all goes to just one place. These work and can support many, many users. A distributed system is an extension of this where it allows the repositories to be duplicated and has mechanisms to synchronize them. With a single server users of the repository must be able to connect to it to get updates and for check ins of new code. If you are not connected to the server you are stuck and cannot continue working. Distributed systems allow you to have your own copy of the repository then continue working and when back in communication synchronize with the server. This is very useful where people take their work home and cannot access the company network. Each person can have a copy of the repository and continue working and re-sync upon return to the office. \subsection{Common Terms} The following is a list of terms I will use when talking about version control or Fossil. \begin{description} \item [{Repository}] This is the store when the version controlled files are kept. It will be managed by a source control system \item [{SCS}] Source control system, this is software that manages a group of files keeping track of changes and allowing multiple users to modify them in a controlled fashion \item [{Commit}] In Fossil to store the current set of new and changed files into the repository. \item [{Trunk}] The main line of code descent in a Fossil repository. \item [{Branch}] A user defined split in the files served by an SCS. This allow multiple work points on the same repository. Older branches (versions) might have bug fixes applied and newer branches (versions) can have new features added. \item [{Fork}] In Fossil an involuntary split in the code path, occurs when a file in the repository has changes not in a file to be committed. \end{description} |
Changes to Chapters/multiple_user.tex.
|
| | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | \chapter{\label{sec:Multiple-Users}Multiple Users} \section{Introduction} In the previous chapter I went through using Fossil with just one user (me). In this chapter we will get into using it with multiple users. Thanks to Fossil's distributed design once the set up is done using it is not much different than the single user case with Fossil managing automatically the multiple user details. \section{Setup} In the previous chapter the Fossil repository was a file on our system and we did commits to it and pulled copies of the source from it. Fossil is a distributed source control system; what this means is that there is a master repository in a place that all users can access. Each user has their own ``cloned'' copy of the repository and Fossil will automatically synchronize the users repository with the master. From a each user's perspective you have your local repository and work with it using the same commands shown in Chapter \ref{sec:Single-User-Fossil}. It's just that now Fossil will keep your repository in sync with the master. \subsection{Server Setup\label{sub:Server-Setup}} I have the FossilBook.fossil repository and now have to put it in place so multiple users can access it. There are two ways, the first is using fossil's built in webserver to host the file and the second is using the operating systems supported web server (if present) and a cgi type access. \paragraph{Self hosted} This is quite simply the easiest way to do it. The downside is that you are responsible for keeping the machine available and the webserver up. That is, don't turn the machine off when you quit for the day or some other user is going to be upset. All I have to do is this: |
︙ | ︙ | |||
110 111 112 113 114 115 116 | \caption{Copying script into place} \end{figure} | | | | | | 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 | \caption{Copying script into place} \end{figure} \subsection{The test (either self hosted or server hosted)} If all is in place then I should be able to access the webserver and get to this: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Multiple_user/test_access} \caption{\label{fig:Web-access-to}Web access to Fossil CGI hosted site} \end{figure} \section{User Accounts} Serving a repository, either self hosting or the more complicated CGI method gets you to the same place as shown in Figure \vref{fig:Web-access-to}. Now I have to set up user accounts for the other contributors to this book. Remember Fossil has automatically created an Anonymous user (see Figure \vref{fig:User-Configuration}) thus others can access the site in a limited way, that is they can download the book but cannot commit changes. In this case I want to create a new account (Marilyn) that can make changes and commit changes as she is my editor. To accomplish all this first I have to login by going to the log in page and entering my ID (jim) and my password. Now since I'm super-user I then go back to the User-Configuration page, Figure \eqref{fig:User-Configuration} and add a new user: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Multiple_user/mul_new_user} \caption{New Editor user\label{fig:New-Editor-user}} \end{figure} Since she is going to be an editor, this will be similar to a developer if we were doing code, so I picked the Developer privilege level. This way she can get the repository, check-in, check-out, and write and update tickets. I also added the attachments since she might need that to put on an image or other comment on actions she is doing. I also gave her a password so her access can be secured. I could add other users at this point but don't need any others for this project, but you can see how easily this can be done. When you assign the user privileges just read carefully and don't give them any more than you think they need. If they have problems, you can easily modify their account in the future. \section{Multiple User Operation} With the server set up and the user established the next thing to do is clone the repository. That is make copy from the webserver repository to my local machine. Once that is done this local repository uses the same commands and is very much like single user use discussed in Section \vref{sec:Single-User-Fossil}. Fossil will synchronize your local repository with the one on the server. \subsection{Cloning} To clone a Fossil repository you have to know four things: \begin{enumerate} \item It's web address, for our repository it is \textbf{http://pandora.dyn-o-saur.com:8080/cgi-bin/Book.cgi} \item Your account name in my case it's \textbf{jim} \item Your password (which I'm keeping to myself thank you...) \item The local name of the repository, in this case I'm calling it Fossilbook.fossil |
︙ | ︙ | |||
253 254 255 256 257 258 259 | \end{figure} As you see the files were committed locally and then the local repository was automatically synchronized with the repository on the server. | | | 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | \end{figure} As you see the files were committed locally and then the local repository was automatically synchronized with the repository on the server. \subsection{Keeping in sync} After doing all the setup described above I now have a distributed source control system. My co-worker, Marilyn has also cloned the repository and begun work. She is editing the book correcting my clumsy phrasing and fixing spelling mistakes. She is working independently and on the same files I use. We must use Fossil to prevent us from both modifying FossilBook.lyx but in different ways. Remember Fossil has no file locking, there is nothing to prevent her from editing and changing the file while I work on it. This is where we both must follow procedures to prevent this sort of problem. Even though she edits files I cannot see the changes till they are committed. Two different versions of the same file won't be a problem till I try to commit with my version and her version is in the current leaf. \label{There-are-two}There are two problems: \begin{enumerate} |
︙ | ︙ | |||
310 311 312 313 314 315 316 | \end{figure} Now I know I have the current state of the world and I can proceed to add in new sections. | | | 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 | \end{figure} Now I know I have the current state of the world and I can proceed to add in new sections. \subsection{Complications\label{sub:Complications}} In\vref{There-are-two} the second case is much harder. In this case I have diligently done my fossil update and started working. In the mean time Marilyn has also done her update and also started working. Now she is done and checks in her changes. I obviously don't know this since I am happily working on my changes. What happens next.... \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%}\textbf{\scriptsize fossil~commit~-m~\textquotedbl{}Commit~that~might~fork\textquotedbl{}}{\scriptsize \par} |
︙ | ︙ | |||
433 434 435 436 437 438 439 | \end{figure} By using the pipe and grep I can eliminate all those extra UNCHANGED lines. | | | 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 | \end{figure} By using the pipe and grep I can eliminate all those extra UNCHANGED lines. \subsection{Fixing the Update file} First we fix the easy file, the fossilbook.pdf I can just update by itself so it matches the current repository. It doesn't need merged so just replace it. Before I do that I have to look at the repository time line \begin{figure}[H] \includegraphics[scale=0.6]{Images/Multiple_user/mul_timeline} \caption{Current Timeline} |
︙ | ︙ | |||
475 476 477 478 479 480 481 | \end{figure} and it's done. | | | 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 | \end{figure} and it's done. \subsection{Fixing the Merge file} We can use the tools built into Fossil. In this case noticing that commit will cause a fork Jim will use the -force option to cause the fork and will handle the merge later. \begin{figure}[H] \begin{lyxcode} {\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-m~\textquotedbl{}adding~some~changes~of~jim\textquotedbl{}}{\scriptsize \par} |
︙ | ︙ |
Changes to Chapters/single_user.tex.
|
| > | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | \chapter{Single Users} \section{Introduction} If you have read this far and are at least persuaded to try, you will want to put one of your projects under software control using Fossil. This chapter is set up to lead you through that task and show you how to adapt your development to using this tool. The assumption is made in this section that you will be the only person using the repository, you are the designer, developer, and maintainer of this project. After you are comfortable using the tool, the next section will show how you use it when you have multiple people working on a project. \section{Creating a repository } \subsection{Introduction} In the spirit of ``eating one's own dog food'' we will use this book as the project we are going to manage with Fossil. The book is a directory of text files (we are writing it using \LyX{} \cite{LyX}) and my working area looks like this: \begin{lyxcode} {\scriptsize FOSSIL/}{\scriptsize \par} \begin{lyxcode} {\scriptsize This~directory~holds~all~my~Fossil~repositories}{\scriptsize \par} \end{lyxcode} |
︙ | ︙ | |||
40 41 42 43 44 45 46 | \end{lyxcode} \end{lyxcode} \end{lyxcode} \end{lyxcode} This took just an hour or so to start preliminary research and build the framework. Since that's about all I'm going to do today I want to build a repository and put all this stuff under Fossil control. | | | 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | \end{lyxcode} \end{lyxcode} \end{lyxcode} \end{lyxcode} This took just an hour or so to start preliminary research and build the framework. Since that's about all I'm going to do today I want to build a repository and put all this stuff under Fossil control. \subsection{Create Repository} I have a directory called FOSSIL in which I keep all my repositories, Fossil doesn't care but it helps me to keep them all in one place so I can back them up. First I need to create a new repository for the book. This is done using the command line after I move into the Fossil book directory. \begin{lyxcode} {\scriptsize } \begin{figure}[H] \begin{lyxcode} |
︙ | ︙ | |||
66 67 68 69 70 71 72 | \end{figure} {\scriptsize \par} \end{lyxcode} I create my repositories with the extension .fossil, this will be useful later with the server command (See Figure \vref{fig:server-detail}). When the create happened it assigned an initial password with an admin user of ``jim'' (i.e., me). | | | 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | \end{figure} {\scriptsize \par} \end{lyxcode} I create my repositories with the extension .fossil, this will be useful later with the server command (See Figure \vref{fig:server-detail}). When the create happened it assigned an initial password with an admin user of ``jim'' (i.e., me). \subsection{Connect Repository} The repository is created but is empty and has no connection to the book directory. The next step is to open the repository to the book directory with the \textbf{open} command. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~open~../FOSSIL/FossilBook.fossil}{\scriptsize{}~}{\scriptsize \par} |
︙ | ︙ | |||
119 120 121 122 123 124 125 | The \textbf{open} command seemingly did nothing but checking with the \textbf{status} command shows the repository, the directory it's linked to and that we are hooked to the trunk of the store. The \textbf{extra} command shows all the files in the directory that are NOT under control of Fossil. In this case that's all of them since we have not checked in anything. | | | 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | The \textbf{open} command seemingly did nothing but checking with the \textbf{status} command shows the repository, the directory it's linked to and that we are hooked to the trunk of the store. The \textbf{extra} command shows all the files in the directory that are NOT under control of Fossil. In this case that's all of them since we have not checked in anything. \subsection{Add and Initial Commit} I must now add all the relevant files into the repository with the \textbf{add} command. The Fossil add is recursive so if I add the top level files it will automatically recurse into the subdirectories like Layout and Research and get those files too. Before you do an add it pays to tidy up your directory so you don't accidentally add a bunch of transient files (like object files from a compile). It's easy to remove them later but a little tidying before hand can save you some work. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~add~.}{\scriptsize \par} |
︙ | ︙ | |||
168 169 170 171 172 173 174 | \end{figure} I added a comment on the commit and it's a good idea to always do this. When later we see the timeline of the commits you will have notes to tell you what was done. | | | | 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 | \end{figure} I added a comment on the commit and it's a good idea to always do this. When later we see the timeline of the commits you will have notes to tell you what was done. \subsection{Fossil start up summary} \begin{itemize} \item \textbf{fossil new <name> }Creates a new fossil repository \item \textbf{fossil open <repository> }While in a source directory connects this directory to the fossil repository \item \textbf{fossil add .} Will add (recursively) all the files in the current directory and all subdirectories to the repository \item \textbf{fossil commit -m ``Initial Commit''} Will put all the currently added files into the repository. \end{itemize} \section{Set Up User interface} One of the surprising features of Fossil is the webserver. This allows it to have a GUI type user interface with no operating system specific code, the GUI is the web browser supplied by your OS. In the previous steps I checked my project in to a Fossil repository, next I have to prep the web interface for production use. \begin{description} \item [{NOTE}] The Fossil web server uses port 8080 instead of the standard port 80 for all HTTP access. When run it will automatically start your Web browser and open the repository home page. Unfortunately my book work is done on a machine that already has Apache running on port 8080 so I will be using port 8081. I will always have to add an extra parameter on the UI command line to do this. \end{description} \begin{figure}[H] \begin{lyxcode} |
︙ | ︙ | |||
247 248 249 250 251 252 253 | I have put in my contact information (e-mail address) and while you cannot see it I have typed in a password that I will remember. Then I applied the changes. Now the repository is ready for further work, it's rather bare bones at this point but the most important things are set up. | | | | 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 | I have put in my contact information (e-mail address) and while you cannot see it I have typed in a password that I will remember. Then I applied the changes. Now the repository is ready for further work, it's rather bare bones at this point but the most important things are set up. \subsection{User interface summary} \begin{itemize} \item \textbf{fossil ui} run in the source directory will start a browser based user interface to fossil. \item \textbf{fossil ui -port <IP port \#>} Can be used if port 8080 if already in use on your system. \item On the first run it is important to configure your project with a name and set the password for yourself. \end{itemize} \section{Update Repository} After writing the above section of the book I now have created a bunch of new files and changed some of the existing files in the repository. Before quitting for the day I should add these new files into the repository and commit the changes saving this milestone in the project. \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:jschimpf/Public/FossilBook{]}~jim\%~}\textbf{\scriptsize fossil~extra}{\scriptsize \par} |
︙ | ︙ | |||
351 352 353 354 355 356 357 | \caption{Timeline Detail\label{fig:Timeline-Detail}} \end{figure} I clicked on the very last check-in (the \textbf{LEAF) }and the display is shown above. There are many things you can do at this point. From the list of changed files you can pick the diff link and it will show in text form the changes made in that particular file. The ``Other Links'' section has a very useful ZIP Archive. Clicking this will download a ZIP of this version to your browser. You will find this useful if you want to get a particular version, in fact this is normally how you get a new version of Fossil from the \url{http://www.fossil-scm.org/}. The edit link will be used later to modify a leaf. | | | | 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 | \caption{Timeline Detail\label{fig:Timeline-Detail}} \end{figure} I clicked on the very last check-in (the \textbf{LEAF) }and the display is shown above. There are many things you can do at this point. From the list of changed files you can pick the diff link and it will show in text form the changes made in that particular file. The ``Other Links'' section has a very useful ZIP Archive. Clicking this will download a ZIP of this version to your browser. You will find this useful if you want to get a particular version, in fact this is normally how you get a new version of Fossil from the \url{http://www.fossil-scm.org/}. The edit link will be used later to modify a leaf. \subsection{Update Summary} \begin{itemize} \item \textbf{fossil status} and \textbf{fossil extra} will tell you the updated files and files not in the repository before you commit. \item \textbf{fossil commit - m ``Commit comment'' }Commits a change (or changes). It is very important to have a descriptive comment on your commit. \end{itemize} \section{Tickets} Besides managing your code Fossil has a trouble ticket system. This means you can create a ticket for a problem or feature you are going to add to your system then track your progress. Also you can tie the tickets to specific check-ins of your files. For software this is very useful for bug fixes and feature additions. For example you can look for a bug in the ticket list then have it take you to the change that fixed the problem. Then you know exactly what you did and not have to be confused by other changes you might have made. When you pick Tickets it will bring up this window. You can create a new ticket, look at the list, or generate a new report. Keeping things simple I will just use the All Tickets list for now. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/ticket_initial} |
︙ | ︙ | |||
461 462 463 464 465 466 467 | \end{figure} I mark it as ``Closed''. If you have code you can mark this as fixed, tested, or a number of other choices. Another very important step, I brought up the Timeline and copied the link for the commit I had just done in Figure \vref{fig:checkin}. By doing this my ticket is now cross linked with the commit and the commit has a link back to the ticket. | | | | 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 | \end{figure} I mark it as ``Closed''. If you have code you can mark this as fixed, tested, or a number of other choices. Another very important step, I brought up the Timeline and copied the link for the commit I had just done in Figure \vref{fig:checkin}. By doing this my ticket is now cross linked with the commit and the commit has a link back to the ticket. \subsection{Ticket Summary} \begin{itemize} \item Tickets are a useful way of reminding you what needs done or bugs fixed \item When you commit a change that affects a ticket put the 10 digit hash label of the ticket into the commit comment surrounded by brackets, e.g. {[}<10 digit hash>{]} so you can link to the ticket \item When you close the ticket put in the hash label of the commit that fixed it. \end{itemize} \section{\label{sub:Wiki-Use}Wiki Use} As we saw in Figure \vref{fig:Starting-Webserver} Fossil has a browser based user interface. In addition to the pages that are built in you can add pages to web site via a wiki. This allows you to add code descriptions, user manuals, or other documentation. Fossil keeps all that stuff in one place under version control. A wiki is a web site where you can add pages and links from within your browser. You are given an initial page then if you type {[}newpage{]} this text will turn into a link and if clicked will take you to a new blank page. Remember in Figure \vref{fig:Initial-Webserver-page} that is the initial page for your project and from there you can add new pages. These pages are automatically managed by the Fossil version control system; you don't have to add or commit. Since I did the setup on repository (see Figure \vref{fig:Initial-Configuration}) the home page has changed to this: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/wiki_blankhome} |
︙ | ︙ | |||
540 541 542 543 544 545 546 | {[}http:doc/tip/FossilBook.pdf~|~Book~(pdf)~{]} \end{lyxcode} This is a special link the Fossil wiki understands, \textbf{doc }says this is documentation. \textbf{tip }says use the most current version; you could put a version link here. And finally since I am going to put the book PDF at the top level I only need the file name. If it was in a subdirectory I would have to say \textbf{doc/tip/subdir/filename. } The second link is just to a regular page and I can just edit that one just like I did this the main page. | | | 541 542 543 544 545 546 547 548 549 550 551 552 553 554 | {[}http:doc/tip/FossilBook.pdf~|~Book~(pdf)~{]} \end{lyxcode} This is a special link the Fossil wiki understands, \textbf{doc }says this is documentation. \textbf{tip }says use the most current version; you could put a version link here. And finally since I am going to put the book PDF at the top level I only need the file name. If it was in a subdirectory I would have to say \textbf{doc/tip/subdir/filename. } The second link is just to a regular page and I can just edit that one just like I did this the main page. \subsection{Wiki Summary} \begin{itemize} \item Format your text using HTML commands like <h1>Title</h1> for page headings \item Create and link pages using {[} <page> | <Link text> {]} \item The page designation http:doc/tip/<document path relative to repository> will display any document in the repository that your browser can handle (i.e. pdf, http etc) \item Never click on a link till AFTER you have saved the page \end{itemize} |
Changes to Chapters/th1_scripting.tex.
> > > | 1 2 3 | \chapter{TH1 Scripting} |
Changes to Chapters/whats_next.tex.
|
| < < | | 1 2 3 4 5 6 7 8 | \chapter{What's next ?} This book so far has covered how to use the many features of Fossil and has, I hope, interested you in using it. The question \textquotedbl{}what's next\textquotedbl{} now comes up. First go to the Fossil website \url{http://www.fossil-scm.org/}. While there you can go to the Wiki link and then list all Wiki pages. There are all sorts of topics covered there in depth. If that still doesn't help, you can join the Fossil mailing list (see Wiki links) and look at the archives or directly ask a question. I have found the list to be very helpful and have had my questions asked very quickly. On the mailing lists you will see long discussions of changes to be made to Fossil, some of these are accepted very quickly and will appear within hours in the Fossil source code. Others engender long discussions (in particular discussion of changes to the Wiki) and it is interesting to read the pros and cons of suggested changes. Fossil is an evolving program but if you get a version that has all the features you need you can stick with that version as long as you like. Going to a new version though is simple and just requires a \textbf{rebuild} of your current repositories. The developers have been very careful to preserve the basic structure so it is easy and safe to switch versions. |
︙ | ︙ |
Changes to fossilbook.pdf.
cannot compute difference between binary files
Changes to fossilbook.tex.
|
| | | 1 2 3 4 5 6 7 8 | \documentclass[11pt,letterpaper,english]{scrbook} \usepackage{mathptmx} \usepackage{helvet} \usepackage{courier} \usepackage[T1]{fontenc} \usepackage[latin9]{inputenc} \usepackage{fancyhdr} \pagestyle{fancy} |
︙ | ︙ | |||
178 179 180 181 182 183 184 | Fax: 724.539.1276 Web: http://www.fossil-scm.org/schimpf-book/index Email: jim.schimpf@gmail.com | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | | < < < < < > > > > | 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 | Fax: 724.539.1276 Web: http://www.fossil-scm.org/schimpf-book/index Email: jim.schimpf@gmail.com \newpage{} \newpage{}\tableofcontents{} \listoffigures \newpage{} \include{Chapters/foreword} \mainmatter \include{Chapters/introduction} \include{Chapters/single_user} \include{Chapters/multiple_user} \include{Chapters/forks_branches} \include{Chapters/commands} \include{Chapters/th1_scripting} \include{Chapters/whats_next} \pagebreak{} \printindex{} \bibliographystyle{plain} \bibliography{Research/fossilbib} \appendix \include{Appendices/revision_history} \end{document} |