# FossilBook

Check-in [92799dfb69]

Overview
Comment: Initial version 2.0 finalized - some issues remaining with layout family | ancestors | files | file ages | folders 92799dfb69bbe0d804d2dc59ce58450fdfd9937c frans 2013-02-25 19:43:46
Context
 2013-02-25 19:43 Initial version 2.0 finalized - some issues remaining with layout Leaf check-in: 92799dfb69 user: frans tags: 2ndEdition 19:20 Complete version with TH1 chapter check-in: 194949b810 user: frans tags: 2ndEdition
Changes

Changes to Chapters/foreword.tex.

 5 6 7 8 9 10 11 12 13 14 15 16 17   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 Paul Ruizendaal - TH 1 Scrpting Language manual \item javalinBCD@gmail.com - found bugs \item arnel\_legaspi@msn.com - found bugs \end{itemize} \newpage{}   |  5 6 7 8 9 10 11 12 13 14 15 16 17   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 Paul Ruizendaal - TH 1 Scripting Language manual \item javalinBCD@gmail.com - found bugs \item arnel\_legaspi@msn.com - found bugs \end{itemize} \newpage{} 

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 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 .. 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 ... 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 ... 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 ... 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 ... 559 560 561 562 563 564 565 566 567 568 569 570 571  \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: \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:/Users/jschimpf/Public{]}~jim\%~cd~FOSSIL/}{\scriptsize \par} {\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}\textbf{\scriptsize fossil~ui~-port~8081~FossilBook.fossil~\&}{\scriptsize{}~}{\scriptsize \par} {\scriptsize {[}1{]}~310}{\scriptsize \par} {\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}{\scriptsize \par} \end{lyxcode} \caption{Self-hosted Fossil repository} \end{figure} This is on UNIX system, the \&'' at then end of the second line runs the fossil webserver in the background. If I know this machine has an IP address of 192.168.1.200 then from any other machine in the network I can say: \textbf{http://192.168.1.200:8081} to the browser and I can access the Fossil web server. As you can see this is simple and works on any system that runs Fossil. As long as you carefully make sure it's always running and available for others this can be a very easy way to make the master repository available. ................................................................................ \paragraph{CGI Script for hosted server} If we assume an Apache server and, in my case, the cgi directory path is /Library/Webserver/CGI-Executables, then we have to write a script of the form: \begin{figure}[H] \begin{lyxcode} \#! repository:~ \end{lyxcode} \caption{Fossil CGI script} \end{figure} and put it into the cgi script directory. I have put my Fossil executable into /usr/local/bin and I am putting my Fossil shared repository into /Users/Shared/FOSSIL. My script then becomes: \begin{figure}[H] \begin{lyxcode} \#!/usr/local/bin/fossil \#~Put~the~book~repository~on~the~web repository:~/Users/Shared/FOSSIL/Fossilbook.fossil \end{lyxcode} \caption{My Fossil CGI script} \end{figure} After making the script I then copy it to the CGI directory and allow anyone to execute it. \begin{lyxcode} \end{lyxcode} \begin{figure}[H] \begin{lyxcode} \textbf{\scriptsize sudo~cp~Book.cgi~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par} \textbf{\scriptsize sudo~chmod~a+x~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par} \end{lyxcode} \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} ................................................................................ \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} \end{figure} ................................................................................ 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} {\scriptsize fossil:~would~fork.\A0~\textquotedbl{}update\textquotedbl{}~first~or~use~-f~or~-{}-force.}{\scriptsize \par} {\scriptsize \A0}{\scriptsize \par} {\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-f~-m~\textquotedbl{}adding~some~other~changes~of~jim\textquotedbl{}}{\scriptsize \par} {\scriptsize New\_Version:~df9f2ff6b14ef65a9dd2162f8bd20c78e1628165}{\scriptsize \par} \end{lyxcode} \caption{Forcing a commit under Windows} \end{figure} Now the timeline looks like: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Multiple_user/Windows/forked_timeline} \caption{Windows Forked timeline} \end{figure} To remove this fork (i.e. get the changes Marilyn did into the trunk) we use the Fossil merge command. We can use the merge because fossilbook.lyx is a text file and the merge markers are designed to work with text files. If it was a binary file we might have to use an external file or copy and paste between the two file versions using the handler program for the file. ................................................................................ Looking at the file (fossilbook.lyx) in a text editor (not \LyX{}) we find: \begin{figure}[H] \begin{lyxcode} {\scriptsize >\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>~BEGIN~MERGE~CONFLICT}{\scriptsize \par} {\scriptsize \A0Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~it}{\scriptsize \par} {\scriptsize \A0with~multiple~users~is~not~much~different~than~the~single~user~case.}{\scriptsize \par} {\scriptsize \A0Fossil~will~automatically~manage~the~most~multiple~user~details.}{\scriptsize \par} {\scriptsize ============================}{\scriptsize \par} {\scriptsize \A0}{\scriptsize \par} {\scriptsize \A0Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~is}{\scriptsize \par} {\scriptsize \A0not~much~different~than~the~single~user~case~with~Fossil~managing~automatically}{\scriptsize \par} {\scriptsize \A0the~multiple~user~details.}{\scriptsize \par} {\scriptsize <\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<~END~MERGE~CONFLICT}{\scriptsize \par} \textbf{} ................................................................................ \caption{Text differences} \end{figure} After the commit the timeline shows how the merge brought the fork back into the main trunk. Marilyn will then have to update to this new trunk. (See Section \vref{sub:Updating-by-others}) \begin{figure}[H] \includegraphics[scale=0.6]{Images/Multiple_user/Windows/merged_timeline} \caption{Merged timeline} \end{figure}   < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < < < | < < < < | | | | | | | | | | | |  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 .. 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 ... 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 ... 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 ... 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 ... 520 521 522 523 524 525 526 527 528 529 530 531 532  \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: \begin{figure}[H] \begin{lyxcode} {\scriptsize {[}Pandora-2:/Users/jschimpf/Public{]}~jim\%~cd~FOSSIL/}{\scriptsize \par} {\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}\textbf{\scriptsize fossil~ui~-port~8081~FossilBook.fossil~\&}{\scriptsize{}~}{\scriptsize \par} {\scriptsize {[}1{]}~310}{\scriptsize \par} {\scriptsize {[}Pandora-2:jschimpf/Public/FOSSIL{]}~jim\%~}{\scriptsize \par} \end{lyxcode} \caption{Self-hosted Fossil repository} \end{figure} This is on UNIX system, the \&'' at then end of the second line runs the fossil webserver in the background. If I know this machine has an IP address of 192.168.1.200 then from any other machine in the network I can say: \textbf{http://192.168.1.200:8081} to the browser and I can access the Fossil web server. As you can see this is simple and works on any system that runs Fossil. As long as you carefully make sure it's always running and available for others this can be a very easy way to make the master repository available. ................................................................................ \paragraph{CGI Script for hosted server} If we assume an Apache server and, in my case, the cgi directory path is /Library/Webserver/CGI-Executables, then we have to write a script of the form: \begin{figure}[H] \begin{lyxcode} \#! repository:~ \end{lyxcode} \caption{Fossil CGI script} \end{figure} and put it into the cgi script directory. I have put my Fossil executable into /usr/local/bin and I am putting my Fossil shared repository into /Users/Shared/FOSSIL. My script then becomes: \begin{figure}[H] \begin{lyxcode} \#!/usr/local/bin/fossil \#~Put~the~book~repository~on~the~web repository:~/Users/Shared/FOSSIL/Fossilbook.fossil \end{lyxcode} \caption{My Fossil CGI script} \end{figure} After making the script I then copy it to the CGI directory and allow anyone to execute it. \begin{figure}[H] \begin{lyxcode} \textbf{\scriptsize sudo~cp~Book.cgi~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par} \textbf{\scriptsize sudo~chmod~a+x~/Library/Webserver/CGI-Executables/Book.cgi}{\scriptsize \par} \end{lyxcode} \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.5]{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.5]{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} ................................................................................ \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.5]{Images/Multiple_user/mul_timeline} \caption{Current Timeline} \end{figure} ................................................................................ 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} {\scriptsize fossil:~would~fork.0~\textquotedbl{}update\textquotedbl{}~first~or~use~-f~or~-{}-force.}{\scriptsize \par} {\scriptsize }{\scriptsize \par} {\scriptsize E:\textbackslash{}Profile\textbackslash{}Ratte\textbackslash{}data\textbackslash{}organize\textbackslash{}fossil-w32\textbackslash{}fossil-book>fossil~commit~-f~-m~\textquotedbl{}adding~some~other~changes~of~jim\textquotedbl{}}{\scriptsize \par} {\scriptsize New\_Version:~df9f2ff6b14ef65a9dd2162f8bd20c78e1628165}{\scriptsize \par} \end{lyxcode} \caption{Forcing a commit under Windows} \end{figure} Now the timeline looks like: \begin{figure}[H] \includegraphics[scale=0.5]{Images/Multiple_user/Windows/forked_timeline} \caption{Windows Forked timeline} \end{figure} To remove this fork (i.e. get the changes Marilyn did into the trunk) we use the Fossil merge command. We can use the merge because fossilbook.lyx is a text file and the merge markers are designed to work with text files. If it was a binary file we might have to use an external file or copy and paste between the two file versions using the handler program for the file. ................................................................................ Looking at the file (fossilbook.lyx) in a text editor (not \LyX{}) we find: \begin{figure}[H] \begin{lyxcode} {\scriptsize >\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>\textcompwordmark{}>~BEGIN~MERGE~CONFLICT}{\scriptsize \par} {\scriptsize Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~it}{\scriptsize \par} {\scriptsize with~multiple~users~is~not~much~different~than~the~single~user~case.}{\scriptsize \par} {\scriptsize Fossil~will~automatically~manage~the~most~multiple~user~details.}{\scriptsize \par} {\scriptsize ============================}{\scriptsize \par} {\scriptsize }{\scriptsize \par} {\scriptsize Thanks~to~Fossil's~distributed~design~once~the~set~up~is~done~using~is}{\scriptsize \par} {\scriptsize not~much~different~than~the~single~user~case~with~Fossil~managing~automatically}{\scriptsize \par} {\scriptsize the~multiple~user~details.}{\scriptsize \par} {\scriptsize <\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<\textcompwordmark{}<~END~MERGE~CONFLICT}{\scriptsize \par} \textbf{} ................................................................................ \caption{Text differences} \end{figure} After the commit the timeline shows how the merge brought the fork back into the main trunk. Marilyn will then have to update to this new trunk. (See Section \vref{sub:Updating-by-others}) \begin{figure}[H] \includegraphics[scale=0.5]{Images/Multiple_user/Windows/merged_timeline} \caption{Merged timeline} \end{figure} 

Changes to Chapters/single_user.tex.

 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 ... 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 ... 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 ... 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 ... 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  \begin{description} \item [{NOTE:}] Newer versions of Fossil automatically find an open port and will give a message on the command line telling you what port number is used. You can still use the -port option if you want to control the port \#. \end{description} This shows how it's started, as you can see I have picked port 8081 since I am locked out of port 8080. When I do this my browser starts and I am presented with the following home page. \begin{figure}[H] \noindent \begin{raggedright} \includegraphics[scale=0.4]{Images/Single_user/initial_page} \par\end{raggedright} \caption{\label{fig:Initial-Webserver-page}Initial webserver page} \end{figure} Following the advice on the page I go to \textbf{setup/config}. I am going to do the minimum setup that you should do on all projects. As you get familiar with Fossil you will probably have many more things that you will customize for your taste but what follows are the only things you HAVE to do. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/config_initial} \caption{\label{fig:Initial-Configuration}Initial Configuration} \end{figure} I have entered in a project name and put in a description, the project name will be the name of the initial Wiki page (see \vref{sub:Wiki-Use}) and the description is useful for others to see what you are doing here. Then I go to the bottom of the page and pick the \textbf{Apply Changes }button. Next I pick the Admin tab (you can see it in the header bar) and the pick Users from that page. I am presented with the users and will use this to set the password of the project. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/user_config} \caption{\label{fig:User-Configuration}User Configuration} \end{figure} As you can see Fossil automatically configures a number of users beyond just the creator. The anonymous user you have already seen if you went to the Fossil web site to download the code. This user can view and get code but cannot commit code. On the right side of the page are the many options you can give to a user, it's worth reading it all when you set up your repository. The important one is me (jim) which has s'' or Super User Capabilities. This means I can do anything with the repository. I will now edit the user Jim to make sure it has the settings I want. In this case you MUST set the password. Remember way back where Fossil set it during the create (Figure\vref{fig:Create-Repository}), it's a very good idea to change this to something you can remember rather than the original random one. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/jim_setup} \caption{Super User Setup} \end{figure} ................................................................................ \end{figure} After doing this commit I can bring up the Fossil ui (see Figure \vref{fig:Starting-Webserver}) and view the project Timeline by picking that tab on the Fossil header. We get this: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/timeline} \caption{Timeline} \end{figure} You can see all my check-ins thus far and you can see after the check-in from Figure \vref{fig:Update-for-new} I did another check-in because I missed some changes in the outline. The check-ins are labeled with the first 10 digits of their hash value and these are active links which you can click to view in detail what was changed in that version. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/timeline_detail} \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. ................................................................................ \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} \caption{Initial Ticket Window} \end{figure} Picking New Ticket'' I get a form that I fill out like so: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/ticket_form} \caption{Ticket Form} \end{figure} Pretty simple actually. You can put as much or as little detail in here as you wish, but remember this stuff might be really vital 6 weeks or 6 months from now so think of what you would want to know then. When I press Submit I get this showing what I entered. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/ticket_submit} \caption{Viewing a Ticket} \end{figure} Finally picking Tickets then All Tickets'' I can see my new ticket in the list marked as Open and in a distinctive color. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/ticket_list} \caption{\label{fig:viewticket}Ticket List with open ticket} \end{figure} I try, in handling tickets, to have links from ticket to the commit that addressed the problem and a link from the commit back to the offending ticket. This way looking at the ticket I can get to the changes made and from the timeline I can get the the ticket and its resolution. To do this I will make sure and put the 10 digit hash label from the ticket into the check-in comment and put a link in the resolved ticket to the check-in. Since I have now written the chapter and put in all these images of what to do I can now add in all the new images to the repository and check this in as another completed operation. And I do that like this: \begin{figure}[H] \begin{lyxcode} ................................................................................ First I added in all the new image files. I am lazy and just told it to add in all the files in the Single\_user directory. I have previously added some of those like \textbf{config\_initial.epsf} but Fossil is smart and knows this and won't add that one twice. Even though it shows it ADDED, it really didn't. The commit line is very important, as you can see I put 10 digit hash code for the ticket in brackets in the comment. As we will see in the Wiki section this is a link to the Ticket, so when viewing the comment in the Timeline or elsewhere you can click the bracketed item and you would go to the ticket. Now that I have the items checked in I have to close the ticket. I do that by clicking on its link in the ticket list, that will go the the View Ticket window as shown in Figure \vref{fig:viewticket}. From there I pick edit and fill it in as shown: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/ticket_done} \caption{Ticket Finish} \end{figure} ................................................................................ \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} \caption{Blank Home Page} \end{figure} Not very helpful so the in rest of this chapter I will use the Wiki functions of Fossil to make this more useful. If I pick the Wiki item from the menu bar I get: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/wiki_page} \caption{\label{fig:Wiki-controls}Wiki controls} \end{figure} These are the controls that let you control and modify the wiki. Most important for now is the Formatting rules link. This link takes you to a page that describes what you can do to format a wiki page. If you just type text on a page it will appear but be formatted by your browser. You can type HTML commands to control this formating. It's worth your time to carefully read this page and note what you can and cannot do. The page just lists the valid HTML commands, and if you don't know what they mean I would suggest you find a page like this \url{http://www.webmonkey.com/2010/02/html_cheatsheet/} and keep it handy. Besides the HTML markup the most powerful command for the Wiki is {[}page{]} where it links to a new page. This is how you add pages and how you build your web site of documentation for the repository. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/wiki_formating}\caption{Wiki Formating} \end{figure} I now begin work. What I want to do is change the home page to be non-empty and also put a link on the home page to the PDF of this book. In Figure \vref{fig:Wiki-controls} I click on the first item, the FossilBook home page. This takes me to the home page again but now I have an Edit option. We also have a History option so I could look at older versions of the page. \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/wiki_homeedit} \caption{Home page with edit} \end{figure} This shows my initial edit and a preview: \begin{figure}[H] \includegraphics[scale=0.6]{Images/Single_user/wiki_home} \caption{Initial Home page} \end{figure}   | | | | | < | | < < < < | < < < | < < < < | < < < | | | | | | |  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 ... 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 ... 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 ... 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 ... 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  \begin{description} \item [{NOTE:}] Newer versions of Fossil automatically find an open port and will give a message on the command line telling you what port number is used. You can still use the -port option if you want to control the port \#. \end{description} This shows how it's started, as you can see I have picked port 8081 since I am locked out of port 8080. When I do this my browser starts and I am presented with the following home page. \begin{figure}[H] \noindent \begin{raggedright} \includegraphics[scale=0.5]{Images/Single_user/initial_page} \par\end{raggedright} \caption{\label{fig:Initial-Webserver-page}Initial webserver page} \end{figure} Following the advice on the page I go to \textbf{setup/config}. I am going to do the minimum setup that you should do on all projects. As you get familiar with Fossil you will probably have many more things that you will customize for your taste but what follows are the only things you HAVE to do. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/config_initial} \caption{\label{fig:Initial-Configuration}Initial Configuration} \end{figure} I have entered in a project name and put in a description, the project name will be the name of the initial Wiki page (see \vref{sub:Wiki-Use}) and the description is useful for others to see what you are doing here. Then I go to the bottom of the page and pick the \textbf{Apply Changes }button. Next I pick the Admin tab (you can see it in the header bar) and the pick Users from that page. I am presented with the users and will use this to set the password of the project. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/user_config} \caption{\label{fig:User-Configuration}User Configuration} \end{figure} As you can see Fossil automatically configures a number of users beyond just the creator. The anonymous user you have already seen if you went to the Fossil web site to download the code. This user can view and get code but cannot commit code. On the right side of the page are the many options you can give to a user, it's worth reading it all when you set up your repository. The important one is me (jim) which has s'' or Super User Capabilities. This means I can do anything with the repository. I will now edit the user Jim to make sure it has the settings I want. In this case you MUST set the password. Remember way back where Fossil set it during the create (Figure\vref{fig:Create-Repository}), it's a very good idea to change this to something you can remember rather than the original random one. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/jim_setup} \caption{Super User Setup} \end{figure} ................................................................................ \end{figure} After doing this commit I can bring up the Fossil ui (see Figure \vref{fig:Starting-Webserver}) and view the project Timeline by picking that tab on the Fossil header. We get this: \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/timeline} \caption{Timeline} \end{figure} You can see all my check-ins thus far and you can see after the check-in from Figure \vref{fig:Update-for-new} I did another check-in because I missed some changes in the outline. The check-ins are labeled with the first 10 digits of their hash value and these are active links which you can click to view in detail what was changed in that version. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/timeline_detail} \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. ................................................................................ \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.5]{Images/Single_user/ticket_initial} \caption{Initial Ticket Window} \end{figure} Picking New Ticket'' I get a form that I fill out like so: \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/ticket_form} \caption{Ticket Form} \end{figure} Pretty simple actually. You can put as much or as little detail in here as you wish, but remember this stuff might be really vital 6 weeks or 6 months from now so think of what you would want to know then. When I press Submit I get this showing what I entered. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/ticket_submit} \caption{Viewing a Ticket} \end{figure} Finally picking Tickets then All Tickets'' I can see my new ticket in the list marked as Open and in a distinctive color. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/ticket_list} \caption{\label{fig:viewticket}Ticket List with open ticket} \end{figure} I try, in handling tickets, to have links from ticket to the commit that addressed the problem and a link from the commit back to the offending ticket. This way looking at the ticket I can get to the changes made and from the timeline I can get the the ticket and its resolution. To do this I will make sure and put the 10 digit hash label from the ticket into the check-in comment and put a link in the resolved ticket to the check-in. Since I have now written the chapter and put in all these images of what to do I can now add in all the new images to the repository and check this in as another completed operation. And I do that like this: \begin{figure}[H] \begin{lyxcode} ................................................................................ First I added in all the new image files. I am lazy and just told it to add in all the files in the Single\_user directory. I have previously added some of those like \textbf{config\_initial.epsf} but Fossil is smart and knows this and won't add that one twice. Even though it shows it ADDED, it really didn't. The commit line is very important, as you can see I put 10 digit hash code for the ticket in brackets in the comment. As we will see in the Wiki section this is a link to the Ticket, so when viewing the comment in the Timeline or elsewhere you can click the bracketed item and you would go to the ticket. Now that I have the items checked in I have to close the ticket. I do that by clicking on its link in the ticket list, that will go the the View Ticket window as shown in Figure \vref{fig:viewticket}. From there I pick edit and fill it in as shown: \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/ticket_done} \caption{Ticket Finish} \end{figure} ................................................................................ \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.5]{Images/Single_user/wiki_blankhome} \caption{Blank Home Page} \end{figure} Not very helpful so the in rest of this chapter I will use the Wiki functions of Fossil to make this more useful. If I pick the Wiki item from the menu bar I get: \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/wiki_page} \caption{\label{fig:Wiki-controls}Wiki controls} \end{figure} These are the controls that let you control and modify the wiki. Most important for now is the Formatting rules link. This link takes you to a page that describes what you can do to format a wiki page. If you just type text on a page it will appear but be formatted by your browser. You can type HTML commands to control this formating. It's worth your time to carefully read this page and note what you can and cannot do. The page just lists the valid HTML commands, and if you don't know what they mean I would suggest you find a page like this \url{http://www.webmonkey.com/2010/02/html\_cheatsheet/} and keep it handy. Besides the HTML markup the most powerful command for the Wiki is {[}page{]} where it links to a new page. This is how you add pages and how you build your web site of documentation for the repository. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/wiki_formating}\caption{Wiki Formating} \end{figure} I now begin work. What I want to do is change the home page to be non-empty and also put a link on the home page to the PDF of this book. In Figure \vref{fig:Wiki-controls} I click on the first item, the FossilBook home page. This takes me to the home page again but now I have an Edit option. We also have a History option so I could look at older versions of the page. \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/wiki_homeedit} \caption{Home page with edit} \end{figure} This shows my initial edit and a preview: \begin{figure}[H] \includegraphics[scale=0.5]{Images/Single_user/wiki_home} \caption{Initial Home page} \end{figure} 

Changes to fossilbook.pdf.

cannot compute difference between binary files