Home

Fossil Version Control A Users Guide

1. ee 36 318 Fossi Merge cia ra a A en 36 3 19 Text differences a i i bh ea eR rra a E 37 3 20 Merged timeline ee 37 4 1 Marilyn s work i e h eee a am ea a a d ee 40 4 2 Jim s commit attempt 40 4 3 Forcing the commit 41 4 4 Repository Fork aoaaa ee 41 4 5 Merge Operation oy a sre a pars a peas Be Oe ee 42 4 6 Commitaftermerge s e e a o aa a a a a al aa a TA a i a a 42 4 7 After merge timeline e 43 4 8 Marilyn s Update o soo sea e osa ea a a a e e e a a E E a 43 4 9 Jim s check in attempt e 44 4 10 Update dry tun 62a e 23 a eee E a e Ee eR da ee ad 45 4 11 Merged repository aca reg ee a daa aa 45 4 12 Checking code status ee ee 46 4 13 Branch commands aoaaa 47 4 14 Branch Timeline a 47 4 15 Setting Timeline color oaoa ee ee 48 4 16 Check out VER_1 0 aoaaa 2 eee eee eee 49 4 17 VER_2 0 checkout a a a ee ee 50 4 18 Fixing both branches aoaaa e 51 4 19 Correcting both branches 0 0 e 52 3 1 Help run 4 a a ca ARA we ee de 53 3 2 Help detail a 4 4 o e won aan a ed eR we ee we eh 54 5 3 add detail 342 5484 6404 aka a a debe ee bea a is 54 S4 Gm detalles ota e Sao ee Ben a ee SMe a ee ee ew eh 55 3d rename detail o s 42 0 acteurs a led Bee a ee Re Be Rr ae 55 5 7 Changes details yc essa ad ke ua aa ede ae a a Me en 56 0 Status TUM sou a ee a a Be a 56 5 8 ex
2. Pandora 2 jschimpf Public FossilBook jim fossil help revert Usage fossil revert r REVISION FILE Revert to the current repository version of FILE or to the version associated with baseline REVISION if the r flag appears If a file is reverted accidently it can be restored using the fossil undo command Figure 5 9 revert details With no parameters it will revert the file to the current revision see Figure 5 6 on the facing page The r option allows you to pick any revision from the time line 5 2 9 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 Updated for fossil version 1 25 Page 57 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help update Usage fossil update VERSION FILES Change the version of the current checkout to VERSION Any uncommitted hanges are retained and applied to the new checkout he VERSION argument can be a specific version or tag or branch name f the VERSION argument is omitted then the leaf of the the subtree hat begins at the current version is used if there is only a single eaf VERSION can also be current to select the leaf of the current ersion or latest to select the most recent check in f one or more FILES are listed after the VERSION then only th
3. 17 21 4a9c960e42 part of check in d9e10e2602 undo wrong indentation from html copy amp paste user Ratte branch trunk diff annotate TAT a0a6f39141 part of check in 80b861536d simulating merge base user Ratte branch trunk annotate Figure 3 17 Windows Forked timeline 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 E Profile Ratte data organize fossil w32 fossil book gt fossil merge a91582b699 MERGE fossilbook lyx x x 2 merge conflicts in fossilbook lyx Figure 3 18 Fossil Merge Looking at the file fossilbook lyx in a text editor not LyX we find Updated for fossil version 1 25 Page 36 of 107 TA Fossil Version Control Fossil SCM gt gt gt gt gt gt gt BEGIN MERGE CONFLICT Thanks to Fossil s distributed design once the set up is done using it with multiple users is not much different than the single user case Fossil will automatically manage the most multiple user details Thanks to Fossil s distributed design once the set up is done using is not much different than the single user case with Fossil managing automatically the multiple user details lt lt lt
4. Trunk The main line of code descent in a Fossil repository 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 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 Updated for fossil version 1 25 Page 4 of 107 2 Single Users 2 1 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 2 2 Creating a repository 2 2 1 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 2 and my working area looks like this FOSSIL This directory holds all my Fossil repositories FossilBook outline txt Book design fossilbook lyx T
5. 2 e 39 4 2 1 Marilyn s Actions 2 Como onen 39 4 2 2 ms Actions a 0 ee a ar 40 4 2 3 Fixing the fork i ae ghee aa sa aha his 42 4 2 4 Commands us d u u 64 0 00 a ee ee a e 43 4 3 Merge without fork 2 2 none 44 4 3 1 Checkin attempt crac 2 2 Meee BER SRS aa 44 A3 2 Update 22 4 ara da amp he doe SS a Se wa a eS ee 44 4 3 3 Commands used 20 0000 ee 45 44 Branching s eh 264 e085 Sr de YA PER eR ee Pee EE a 46 4 4 1 Introduction 46 4 4 2 Branchtherepository 0 00020 0002 eee 46 4 4 3 Color Setup u du u ee nn ee baba ea a 48 4 4 4 Check out the branches 49 4 4 5 Correcting errors in both o o e ee eee 50 4 4 6 Commands used 0 0 0000 ee 52 5 Fossil Commands 53 5 1 Introduction aosi aea ea a eaea a a a a a a e ae a a a A 53 5 2 Basico Commands s suss eo m none 53 3 2 1 help a O E ae Boar ws E ere ee 53 3 22 Add zes es es arr ie ph Ale ome Hs ed ee Ge es see By lee ee ete 54 A del 6 ak a a wh aan aa 54 3 24 rename OF MV ee wR we Ke 55 9 2395 Status cok earch woke wae ahaa nr a se He eh ae 55 5 2 6 Changes eee ua ER a ee ee ew aoe a 56 Medi JOR goa Sade ohana Bw Be A e Ges an 56 9 278 A EEES ee ee ie 57 3 2 9 Updater tons ee Pe ee ee ee ewe ee Pe eae aE e le 57 5 2 10 checkoutorco CH Homer 58 JAUNO u 08 01400 Gide SO we Go HE ee ee Hw WH es 59 S202 ith 358 4 a 8 h
6. 51be6423a3 Update outline user jim artifact 7cd39dfa06 2010 04 27 3960728527 1665c78d94 Ticket Use user jim artifact 1f82aaf41c 2010 04 26 497b93858f Update to catch changes in outline user Jim artifact b870231e48 2010 04 25 8fa0708186 Initial Commit user jim artifact 34a460a468 Pandora 2 jschimpf Public FossilBook jim 5 4 4 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 Updated for fossil version 1 25 Page 72 of 107 Fossil Version Control Fossi TA SCM Pandora 2 jschimpf Public FossilBook jim fossil help timeline Usage fossil timeline WHEN BASELINE DATETIME n N t TYPE Print a summary of activity going backwards in date and time specified or from the current date and time if no arguments are given Show as many as N default 20 check ins The WHEN argument can be any unique abbreviation of one of these keywords before after descendants children ancestors parents The BASELINE can be any unique prefix of 4 characters or more The DATETIME should be in the ISO8601 format For examples 2007 08 18 07 21 21 You can also say current for the current version or now for the
7. Hello world n The command to output a string in TH is the puts command A single unit of text after the puts command will be printed to the output stream If the string has more than one word you must enclose the string in double quotes or curly brackets A set of words enclosed in quotes or curly brackets is treated as a single unit while words separated by white space are treated as multiple arguments to the command 6 3 TH structure and syntax 6 3 1 Datatypes TH has at its core only a single data type which is string All values in TH are strings variables hold strings and the procedures return strings Strings in TH consist of single byte characters and 79 Viv 27 Fossil Version Control Fossil SCM are zero terminated Characters outside of the ASCII range i e characters in the 0x80 Oxff range have no TH meaning at all they are not considered digits or letters nor are they considered white space Depending on context TH can interpret a string in four different ways First of all strings can be just that text consisting of arbitrary sequences of characters Second a string can be considered a list an ordered sequence of words separated by white space Third a string can be a command A command is a list where the first word is interpreted as the name of a command optionally followed by further argument words Fourth and last a string can be interpreted as an expression The latter three interpretations of s
8. VER_1 0 user jim tags VER_1 0 14 18 Tested ticket fed383fa1a Add help to MAIN plus 4 other changes user jim 14 16 462156b283 Branch Point Leaf fed383fa1a Add help to cmd line user jim tags trunk Figure 4 19 Correcting both branches 4 4 6 Commands used e fossil branch Used to generate a branch of the repository The command can optionally color the branch in the display Updated for fossil version 1 25 Page 52 of 107 5 Fossil Commands 5 1 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 help You can always type fossil help at the command line and it will list out all the commands it has Then typing fossil help lt command gt 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 NOTE Fossil is a moving target commands might be added and others removed future versions Type fossil help on
9. g h will return ab c de g h The lindex command treats argument list as a TH list and returns the element with index number index from it The argument index must be an integer number and zero refers to the first element of the list In extracting the element the lindex command observes the same rules concerning braces and quotes and backslashes as the TH command interpreter however variable substitution and command substitution do not occur If index is negative or greater than or equal to the number of elements in value an empty string is returned The length command treats argument list as a list and returns a decimal string giving the number of elements in it Updated for fossil version 1 25 Page 97 of 107 7 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 what s next now comes up First go to the Fossil website 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 h
10. lt lt lt lt END MERGE CONFLICT lt Here edit in the changes gt E Profile Ratte data organize fossil w32 fossil book gt fossil commit m merging marilyn s fork back New_Version acdd676d3ab157769496 6845ccc7652985c1d03 Figure 3 19 Text differences 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 on page 7 most recent events R N 18 03 acdd676d3a Merge Leaf merging marilyn s fork back user Ratte tags trunk 17 37 dfgf2ff6b1 adding some other changes of jim user Ratte tags trunk 17 35 f10f68d717 adding some changes of jim user Ratte tags trunk 17 23 a91582b699 simulating marilyn s commit user Ratte tags trunk 17 21 d9e10e2602 Fork undo wrong indentation from html copy amp paste user Ratte tags trunk 47 47 ALA A is nn bs eee Sa TS Figure 3 20 Merged timeline Updated for fossil version 1 25 Page 37 of 107 4 Forks amp Branches 4 1 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 3 4 3 on page 32 If instead of fixing merging the file then doing the commit we forced the commit Fos
11. the TH Scripting language 79 6 1 Introductionto TH a a a e a e a a 79 6 1 1 TH is a Tcl like language o e 79 6 2 The Hello world program ee 79 6 3 TH structure and syntax 2 CC mon onen 79 6 3 1 Datatypes v e en be ee eee e Aaa ee 79 6 3 2 LASS ose ne Be ee Re yw ee Be er ne 80 6 3 3 Commands ss cesser talea aeaa aa p a a e a ea ea 81 6 3 4 Grouping amp substitution 2 oaoa e 81 6 3 4 1 Argument grouping e 81 6 3 4 2 Value substitutions oaa ee ee 82 6 3 4 3 Backslash escape substitution 00 82 6 3 4 4 Variable substitution 222 2 Comm 82 6 3 4 5 Command Substitution o o 83 Updated for fossil version 1 25 V Fossil Version Control 6 3 4 6 Argument grouping revisited 6 3 5 Summary 2 e aoco ee do we 639 1 CaveatS ocu cb baa ba wee a nen 6 4 TH expressions 00000002 ee ee 6 5 TH variables aoaaa 00 00 0000 000 6 5 1 Working with variables 6 5 1 1 Scalar variables and array variables 6 5 1 2 Variable scope 6 6 TH commands scripts and programfloW 6 6 1 Commands revisited o 0 02 SCIPS an ean da A 6 6 3 Command result codes 6 6 4 Flow control commands 6 6 5 Creating user defined commands 6 6 6 Execution of user defined comm
12. 10 42 b72e96832e Update documentation user Marilyn tags trunk 10 12 New ticket d23bf4bbbb Fix warnings in main amp qdj_util user jim 10 53 Changes to wiki page JASONP user jim 10 52 Changes to wiki page JASONP user jim 10 52 Changes to wiki page JASONP user jim 10 45 6edbaf5fa8 Fork Initial Checkin user jim tags trunk 10 44 b4bca2a0c5 initial empty check in user jim tags trunk Figure 4 7 After merge timeline The only other thing remaining is that Marilyn does an Update before proceeding so her checked out code matches the repository WhiteBook jsonp marilyn fossil update Autosync http Marilyn pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 130 1 0 0 Received 1150 25 0 0 Send 412 7 0 0 Received 3274 31 1 5 Total network traffic 843 bytes sent 2709 bytes received UPDATE json src qdj_token c UPDATE json src qdj_util c UPDATE main c Figure 4 8 Marilyn s Update 4 2 4 Commands used e fossil merge lt fork gt Used to merge a fork specified by hash value to current check out Updated for fossil version 1 25 Page 43 of 107 Vv 27 Fossil Version Control Fossil SCM e fossil update lt version gt Used to update current check out to specified version if version not present use default tag for check out see fossil status 4 3 Merge without fork In this case I will show how to merge in code changes from multiple users with
13. 2 Jim s commit attempt At this point Fossil recognizes that Marilyn has changed the repository she updated the documen tation but Jim does not have these changes because he checked out an earlier version of the code Jim says he must get his changes in so he does a FORCE to force fossil to accept the commit Updated for fossil version 1 25 Page 40 of 107 v gt Fossil Version Control Fossil SCM 552 jsonp gt fossil commit m d23bf4bbbb Remove warnings f Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 130 1 0 0 Received 874 19 0 0 Total network traffic 338 bytes sent 771 bytes received New_Version lbeab955418a942ab9953c4865109ff46cbbd691 Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 2646 25 0 4 Received 1058 23 0 0 Total network traffic 1498 bytes sent 864 bytes received x warning a fork has occurred x x Figure 4 3 Forcing the commit Looking at the timeline Jim sees this KA 2 j e jasonp Timeline Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout 200 Events Checkins Only Tickets Only Wiki Only 8 most recent events 10 44 1beab95541 Leaf d23bf4bbbb Remove warnings user jim tags trunk 10 42 b72e96832e Leaf Update documentation user Marilyn tags trunk 10 12 New ticket d23bf4bbbb Fix warnings in main amp qaj_util user ji
14. COMMAND settings COMMAND unset fossil setting PROPERTY VALUE global fossil unset PROPERTY global The setting command with no arguments lists all properties and their values With just a property name it shows the value of that property With a value argument it changes the property for the current repository The unset command clears a property setting auto captcha If enabled the Login page will provide a button which uses JavaScript to fill out the captcha for he anonymous user Most bots cannot use JavaScript f enabled automatically pull prior to commit r update and automatically push after commit or ag or branch creation If the the value is pullonly hen only pull operations occur automatically he VALUE is a comma separated list of GLOB patterns hat should be treated as binary files for merging urposes Example xml hen enabled fossil will attempt to sign all commits with gpg When disabled the default commits will be unsigned diff command External command to run when performing a diff f undefined the internal text diff will be used dont push Prevent this repository from pushing from client to server Useful when setting up a private branch editor Text editor command used for check in comments gdiff command External command to run when performing a graphical diff If undefined text diff will be used http port The TCP IP port number to use by the server and ui commands Default 8080 The VALUE is
15. Figure 2 5 on page 8 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 2 6 on page 8 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 2 7 on page 9 the home page has changed to this Ww u FossilBook FossilBook Logged in as jim Empty Page Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 20 Blank Home Page 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 Updated for fossil version 1 25 Page 19 of 107 M oj Fossil Version Control Fossil SCM A Va A FossilBook Wi ki Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout FossilBook wiki home page Recent changes to wiki pages Formatting rules for wiki Use the Sandbox to
16. TH_RETURN 3 Indicates that the return command has been invoked The string gives the return value for the procedure or command TH_BREAK 2 Indicates the innermost loop should abort immediately The string contains break or the argument of break if any TH_CONTINUE 4 Indicates that the innermost loop should go on to the next iteration The string contains break or the argument of break if any TH programmers do not normally need to think about return codes since TH_OK is almost always returned If anything else is returned by a command then the TH interpreter immediately stops processing commands and returns to its caller If there are several nested invocations of the TH interpreter in progress then each nested command will usually return the error to its caller until eventually the error is reported to the top level application code The application will then display the error message for the user In a few cases some commands will handle certain error conditions themselves and not return them upwards For example the for command checks for the TH_BREAK code if it occurs for stops executing the body of the loop and returns TH_OK to its caller The for command also handles TH_CONTINUE codes and the procedure interpreter handles TH_RETURN codes The catch command allows TH programs to catch errors and handle them without aborting command interpretation any further Updated for fossil version 1 25 Page 91 of 10
17. This code has to be specified with its numeric value 6 6 7 Special commands TH includes three core commands that assist with working with commands They are breakpoint args rename oldcmd newcmd uplevel level script The breakpoint command does nothing It is used as placeholder to place breakpoints during debugging Updated for fossil version 1 25 Page 94 of 107 Viv A Fossil Version Control Fossil SCM The rename command renames a user defined or a built in command The old name is removed and the new name is inserted in the interpreter s command table The uplevel command executes a command in the variable scope of a command higher up in the call chain The script argument is evaluated in the variable scope indicated by level The uplevel command returns the result of that evaluation If level is an integer then it gives a distance up the procedure calling stack to move before executing the command If level is omitted then it defaults to 1 For example suppose that procedure a was invoked from top level and that it called b and that b called c Suppose that c invokes the uplevel command If level is 1 or omitted then the command will be executed in the variable context of b If level is 2 then the command will be executed in the variable context of a If level is 3 then the command will be executed at top level i e only global variables will be visible The uplevel command causes t
18. a Ble Ge Be oe ke 71 5 35 finfo detal 72 5 36 timeline detail 2 2 22 2 Co oo nenn 73 3 37 w ki det ll ooo ahd eat Bea bh er nn th ed 74 5 38 scr b detail 24 sa c seas a Rw RR ma a ASR aa wea ee es 75 3 39 searchidetall s s s s u 8 au wart a ar a asado 75 5 40 shalsum detal 75 5 41 stats detail 22 22 oo onen 76 5 42 configuration detail ee 77 5 43 descendants detail 22 22 Co oo oo nenn 77 Updated for fossil version 1 25 Page 103 of 107 Bibliography 1 D Crockford The application json media type for javascript object notation Request for Comments 4627 Network Working Group July 2006 2 a Mattias Ettrich Lyx the document processor 3 Dick Grune Concurrent versions system a method for independent cooperation unpublished 1986 4 5 6 Marc J Rochkind The source control system IEEE Transactions on Software Engineering SE 1 4 364 December 1975 ey D Richard Hipp Fossil home page a University of Texas How we use sccs 105 A Document Revision History Use the following table to track a history of this documents revisions An entry should be made into this table for each version of the document Version Author Description Date 0 1 js Initial Version 24 Apr 2010 0 2 js Finishing up Single User Chapter 27 Apr 2010 0 3 js Working on introduction chapter 30 Apr 2010 0 4 j
19. a comma separated list of GLOB patterns specifying files that the extra command will ignore Example 0 obj exe localauth f enabled require that HTTP connections from 27 0 0 1 be authenticated by password If false all HTTP requests from localhost have unrestricted access to the repository autosync binary glob SOtHt tone clearsign ignore glob mtime changes Use file modification times mtimes to detect when files have been modified Default on pgp command Command used to clear sign manifests at check in The default is gpg clearsign o proxy URL of the HTTP proxy If undefined or off then the http_proxy environment variable is consulted If the http_proxy environment variable is undefined then a direct HTTP connection is used web browser A shell command used to launch your preferred web browser when given a URL as an argument Defaults to start on windows open on Mac and firefox on Unix Figure 5 32 settings details 5 4 Miscellaneous These are commands that don t seem to fit in any category but are useful Updated for fossil version 1 25 Page 70 of 107 TA Fossil Version Control Fossil SCM 5 4 1 zip You can do what this command does from the web based user interface In Figure 2 13 on page 13 you can download a ZIP archive of the particular version of the files This command lets you do it from the command line Pandora 2 jschimpf Public FossilBook jim
20. both command line and browser UI control of the Fossil repository The example used for the entire book is the repository used to manage this book e Link to book PDF e Design amp Tools Notes lt hl gt lt center gt Fossil User Manual lt center gt lt h1 gt This repository holds the text and images of a Fossil user manual This will show a new user how to use the many features of this innovative and simple source control tool The manual will be illustrated with screen captures showing both command line and browser UI control of the Fossil repository The example used for the entire book is the repository used to manage this book http doc tip fossilbook pdf Link to book PDF tools Design amp Tools Notes Preview Your Changes Apply These Changes Cancel Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 24 Initial Home page The bottom section is an edit window where I type things I want displayed and the top is a preview of what the page will be As you can see I typed some simple HTML to make a large and centered title The body of the text I just typed and as you see the browser fits the text to the screen You can have multiple paragraphs by just putting blank lines between your text Next I wanted a bulleted list and this is done by typing two spaces a then two more spaces On each of these lines I have a link to a new not yet created page If you look I put these in the
21. command Updated for fossil version 1 25 Page 83 of 107 Vv A Fossil Version Control Fossil SCM 6 3 4 6 Argument grouping revisited During the substitution phase of command evaluation the two grouping operators the curly bracket and the double quote are treated differently by the TH interpreter Grouping words with double quotes allows substitutions to occur within the double quotes A double quote is only used for grouping when it comes after white space The string a b is a normal 4 character string and not the two character string ab puts a b gt a b Grouping words within curly brackets disables substitution within the brackets Again A opening curly bracket is only used for grouping when it comes after white space Characters within curly brackets are passed to a command exactly as written and not even backslash escapes are processed Note that curly brackets have this effect only when they are used for grouping i e at the beginning and end of a sequence of words If a string is already grouped either with double quotes or curly brackets and the curly brackets occur in the middle of the grouped string e g foo bar then the curly brackets are treated as regular characters with no special meaning If the string is grouped with double quotes substitutions will occur within the quoted string even between the brackets The square bracket syntax used for command substitution does not provide grou
22. empty each of whose elements specifies one argument Each argument specifier is also a list with either one or two fields If there is only a single field in the specifier then it is the name of the argument if there are two fields then the first is the argument name and the second is its default value Curly brackets and backslashes may be used in the usual way to specify complex default values The proc command returns the null string Updated for fossil version 1 25 Page 93 of 107 Fossil Version Control Fossil SCM 6 6 6 Execution of user defined commands If a command is a user defined command i e a command created with the proc command then the TH interpreter creates a new local variable context binds the formal arguments to their actual values i e TH uses call by value exclusively and loads the body script Execution then proceeds with the first command in that script Execution ends when the last command has been executed or when one of the returning commands is executed When the script ends the local variable context is deleted and processing continues with the next command after the user defined command More in detail when a user defined command is invoked a local variable is created for each of the formal arguments to the procedure its value is the value of corresponding argument in the invoking command or the argument s default value Arguments with default values need not be specified in a procedure invocatio
23. experiment Create a new wiki page List of All Wiki Pages available on this server Search wiki titles Figure 2 21 Wiki controls 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 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 v ahs FossilBook Wiki Formattin y Rules Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Formatting Rule Summary Blank lines are paragraph breaks Bullets are surrounded by two spaces at the beginning of the line Enumeration items are surrounded by two spaces at the beginning of a line Indented pargraphs begin with a tab or two spaces Hyperlinks are contained with square brackets target or targetiname Most ordinary HTML
24. files I use We must use Fossil to prevent us from both modifying FossilBook lyx but in differ ent 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 There are two problems 1 Before I do any work I must be sure I have the current versions of all the files 2 When I commit I must make sure what I am committing has only my changes and is not stepping on changes she has done The first is pretty obvious make sure you have the latest before you do anything We do that with the update command In Figure 3 8 I had done my latest check in Before starting any more work I should ensure that Marilyn hasn t checked in something else I could check the timeline but instead PI do an update to my repository and source files When I do the update I specify it should be updated from the trunk This ensures I get it from the latest and greatest not some branch Ah ha Marilyn has been at work and updated the book source and pdf If I check the timeline from the webserver I see she has even documented it Updated for fossil version 1 25 Page 31 of 107 M 27 Fossil Version Contro
25. first so doing fossil sync then fossil update n will do that for you Pandora 2 jschimpf Public FossilBook jim fossil help sync Usage fossil sync URL options Synchronize the local repository with a remote repository This is the equivalent of running both push and pull at the same time Use the R REPO or repository REPO command line options to specify an alternative repository file If a user id and password are required specify them as follows http userid password www domain com 1234 path If the URL is not specified then the URL from the most recent successful clone push pull remote url or sync command is used The URL specified normally becomes the new remote url used for subsequent push pull and sync operations However the once command line option makes the URL a one time use URL that is not saved See also clone push pull remote url Figure 5 27 sync details 5 3 11 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 Updated for fossil version 1 25 Page 66 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help clean Usage fossil clean force dotfiles Delete all extra files in the source tree Extra files are files that are not officially part of the checkout See also the extra command This operation
26. fossil version 1 25 Page 62 of 107 Viv e Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help clone Usage fossil clone OPTIONS URL FILENAME Make a clone of a repository specified by URL in the local file named FILENAME By default your current login name is used to create the default admin user This can be overridden using the A admin user parameter Options admin user A USERNAME Figure 5 19 clone details Just like create you can specify the admin user for this clone with an option The URL for the master repository is of the form http lt user gt lt password gt domain Where user and password are for a valid user of the selected repository It is best to check the path with a browser before doing the clone Make sure you can reach it for example the repository for this book is http pandora dyn o saur com 8080 cgi bin Book cgi Putting that into a browser should get you the home page for this book See Figure 3 5 on page 27 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 5 3 3 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 Pandor
27. 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 3 2 1 0 1 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 Pandora 2 Users jschimpf Public jim cd FOSSIL Pandora 2 jschimpf Public FOSSIL jim fossil ui port 8081 FossilBook fossil amp 1 310 Pandora 2 jschimpf Public FOSSIL jim Figure 3 1 Self hosted Fossil repository 25 Vv A Fossil Version Control Fossil SCM This is on UNIX system the amp 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 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 The problems with this method are 1 If you have multiple repositories you have to use the ser
28. is empty and has no connection to the book directory The next step is to open the repository to the book directory with the open command Pandora 2 jschimpf Public FossilBook jim fossil open FOSSIL FossilBook fossil Pandora 2 jschimpf Public FossilBook jim fossil status repository Users jschimpf Public FOSSIL FossilBook fossil local root Users jschimpf Public FossilBook server code 0149388e5a3109a867332dd8439ac7b454f3f9 9dd checkout 279dfecd3f0322f236a92a9a8F3c9b6acf327d8cl 2010 04 25 12 40 39 UTC tags trunk Pandora 2 jschimpf Public FossilBook jim fossil extra Layout fossil png Research History CVS grune pdf Research History RCS A System for Version Control webloc Research History SCCS Slideshow pdf Research History VCSHistory pysync webloc Research fossilbib bib fossilbook lyx outline txt Figure 2 2 Open Repository amp Check The open command seemingly did nothing but checking with the status command shows the repos itory the directory it s linked to and that we are hooked to the trunk of the store The 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 Updated for fossil version 1 25 Page 6 of 107 Fossil Version Control Fossil SCM 2 2 4 Add and Initial Commit I must now add all the relevant files into the repository with the add command The Fossil add is recursive
29. like lt h1 gt Title lt h1 gt for page headings e Create and link pages using lt page gt lt Link text gt e The page designation http doc tip lt document path relative to repository gt will display any document in the repository that your browser can handle i e pdf http etc e Never click on a link till AFTER you have saved the page Updated for fossil version 1 25 Page 23 of 107 3 Multiple Users 3 1 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 3 2 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 It s just that now Fossil will keep your repository in sync with the master 3 2 1 Server Setup I have the FossilBook fossil repository and now
30. move The argument frame may be omitted if othervar is not an integer frame then defaults to 1 For each othervar argument the upvar command makes the variable by that name in the local scope identified by the frame offset accessible in the current procedure by the name given in the corresponding myvar argument The variable named by othervar need not exist at the time of the call it will be created the first time myvar is referenced just like an ordinary variable The upvar command is only meaningful from within user defined command bodies Neither othervar nor myvar may refer to an element of an array The upvar command returns an empty string The upvar command simplifies the implementation of call by name procedure calling and also makes it easier to build new control constructs as TH commands For example consider the following procedure Updated for fossil version 1 25 Page 89 of 107 Fossil Version Control Fossil SCM proc incr name upvar name x set x expr x 1 incr is invoked with an argument giving the name of a variable and it adds one to the value of that variable 6 6 TH commands scripts and program flow In TH there is actually no distinction between commands often known as statements and func tions in other languages and syntax There are no reserved words like if and while as exist in C Java Python Perl etc When the TH interpreter starts up there is a list of built in know
31. password and then open the Fossil Repository on a working directory Now that I ve moved everything to the new cloned repository I do a check in a the end of the day which looks like this Updated for fossil version 1 25 Page 30 of 107 Vv 27 Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil commit m Moved to clone repository Autosync http Jjim pandora dyn o saur com 8080 cgi bin Book cgi Bytes Cards Artifacts Deltas Send 130 1 0 0 Received 2990 65 0 0 Total network traffic 334 bytes sent 1876 bytes received New_Version 158492516c640d055bc0720684a05e797b88165a Autosync http jimtpandora dyn o saur com 8080 cgi bin Book cgi Bytes Cards Artifacts Deltas Send 618798 74 1 2 Received 3222 70 0 0 Send 268138 73 1 0 Received 3221 70 0 0 Send 3977 72 0 1 Received 3220 70 0 0 Total network traffic 457995 bytes sent 6011 bytes received Pandora 2 jschimpf Public FossilBook jim Figure 3 8 Cloned repository checkin As you see the files were committed locally and then the local repository was automatically syn chronized with the repository on the server 3 4 2 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
32. so conflicting edits would not be done 5 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 name for example Version 1 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 named Version 2 with new features added under construction In 1986 the open source Concurrent Version Control system CVS 3 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 4 is a easy to install version control system that also includes a trouble ticketing system Figure 2 17 on page 16 a wiki Figure 2 6 on page 19 and self hosted web server Figure 2 5 on page 8 Fossil Version Control Fossil SCM 1 2 Why version the files in your project Why do you want to use a source control system You won t be able to create files delete files or move files between direc
33. works lt verbatim gt and lt nowiki gt NOUPUmD We call the first five rules above wiki formatting rules The last two rules are the HTML formatting rule Formatting Rule Details Figure 2 22 Wiki Formating Updated for fossil version 1 25 Page 20 of 107 M ng Fossil Version Control Fossil SCM 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 2 21 on the facing page 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 v z FossilBook FossilBook Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Edit History Empty Page Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 23 Home page with edit This shows my initial edit and a preview Updated for fossil version 1 25 Page 21 of 107 M 27 Fossil Version Control Fossil SCM g MY rg FossilBook Edit FossilBook nn Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Preview Fossil User Manual This repository holds the text and images of a Fossil user manual This will show a new user how to use the many features of this innovative and simple source control tool The manual will be illustrated with screen captures showing
34. 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 5 2 Basic Commands 5 2 1 help This command is used to dump the current command set and version of Fossil It can also be used in the form fossil help lt command gt to get further information on any command Pandora 2 jschimpf Public FossilBook jim fossil help Usage fossil help COMMAND Common COMMANDs use fossil help all for a complete list add changes finfo merge revert tag addremove clean gdiff mv rm timeline all clone help open settings ui annotate commit import pull sqlite3 undo bisect diff info push stash update branch export init rebuild status version cat extras ls remote url sync This is fossil version 1 25 d2e07756d9 2013 02 16 00 04 35 UTC Figure 5 1 Help run 53 Vv 27 Fossil Version Control Fossil SCM Actually this will give you only a subset of the help commands limited to the commands that are used most often If you want to see all commands available then issue the fossil help all command Between versions you will see changes as to what is included in the help sub set An example of using the help function to get further information about a particular command Pandora 2 jschimpf Public FossilBook jim fossil help add Usage fossil add FILE Make arrangements to add one or more files to the current checkout at the next commit when adding files
35. 1c diff Modified outline txt from 34a460a468c3500c to b870231 4790 diff Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 13 Timeline Detail I clicked on the very last check in the 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 http www fossil scm org The edit link will be used later to modify a leaf 2 4 1 Update Summary e fossil status and fossil extra will tell you the updated files and files not in the repository before you commit e fossil commit m Commit comment Commits a change or changes Itis very important to have a descriptive comment on your commit Updated for fossil version 1 25 Page 13 of 107 M 27 Fossil Version Control Fossil SCM 2 5 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 fe
36. 2a621490276d739 Figure 2 4 Initial Commit 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 2 2 5 Fossil start up summary e fossil new lt name gt Creates a new fossil repository e fossil open lt repository gt While in a source directory connects this directory to the fossil repository e fossil add Will add recursively all the files in the current directory and all subdirectories to the repository Updated for fossil version 1 25 Page 7 of 107 g Fossil Version Control Fossil SCM e fossil addremove Will recursively add any files that have been added in the current working directory and delete any files that have been deleted in the current working directory e fossil commit m Initial Commit Will put all the currently added files into the repository 2 3 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 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
37. 30ccec65ff82fe2eb160d checkout 462156b283b694af0b99c9b446b64d3f77436fbb 2010 06 09 14 16 42 UTC parent fbb1649le2ff9f9ca3a98adffal67delb6903a44 2010 06 09 14 02 28 UTC tags trunk Figure 4 12 Checking code status Seeing that matches the latest leaf in the time line we can proceed to branch the code Updated for fossil version 1 25 Page 46 of 107 y e Fossil Version Control Fossil SCM Pandora 2 jschimpf Public jsonp jim fossil branch new VER_1 0 trunk bgcolor OxFFCOFF sh gpg command not found unable to sign manifest continue y N y New branch 65e1f48633d69la5ea738cd5lccbhf9a581dfb3c7 Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 2391 42 0 1 Received 1840 40 0 0 Total network traffic 1524 bytes sent 1272 bytes received Pandora 2 jschimpf Public jsonp jim fossil branch new VER_2 0 trunk bgcolor OxCOFOFF sh gpg command not found unable to sign manifest continue y N y New branch a173791l6ec2df696a0f3a7e3 6edf9ba4370e48a7 Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 2437 43 0 1 Received 1886 41 0 0 Total network traffic 1550 bytes sent 1271 bytes received Pandora 2 jschimpf Public jsonp jim Figure 4 13 Branch commands What was just done We used the Fossil branch command to create two branches VER_1 0 and VER_2 0 and assigned each of them a color We can see the timelin
38. 4 3 3 Commands used e fossil update n Does a dry run of an update to show what files will changed UPDATE Implies file will be replaced by repository file MERGE Implies file will be mixed text from repository and check out Updated for fossil version 1 25 Page 45 of 107 Fossil Version Control Fossil SCM 4 4 Branching 4 4 1 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 4 4 2 Branch the repository Before proceeding we will make sure we have the current trunk code in our check out Pandora 2 jschimpf Public jsonp jim fossil status repository Users jschimpf Public FOSSIL jsonp fossil local root Users jschimpf Public jsonp server code 90c80fla2da7360dae2
39. 7 Fossil Version Control Fossil SCM 6 6 4 Flow control commands The flow control commands in TH are if exprl bodyl elseif expr2 body2 else bodyN for init condition incr script break value continue value error value catch script varname Below each command is discussed in turn The if command has the following syntax if expri bodyl elseif expr2 body2 else bodyN The expr arguments are expressions the body arguments are scripts and the elsif and else arguments are keyword constant strings The if command optionally executes one of its body scripts The expr arguments must evaluate to an integer value If it evaluates to a non zero value the follow ing body script is executed and upon return from that script processing continues with the command following the if command If an expr argument evaluates to zero its body script is skipped and the next option is tried When there are no more options to try processing also continues with the next command The if command returns the value of the executed script or 0 when no script was executed The for command has the following syntax for init condition incr body The init incr and body arguments are all scripts The condition argument is an expression yielding an integer result The for command is a looping command similar in structure to the C for statement The for command first invokes the TH interpreter to execute init Then it repeate
40. 9b6acf327d8cl 2010 04 25 12 40 39 UTC tags trunk EDITED fossilbook lyx Figure 2 10 Project Status I run fossil extra to see these new files The image files those in Images Single_user I want to add the other two files fossilbook lyx and fossilbook lyx I don t want to add since they are temporary artifacts of LyX I also ran fossil status This shows changes to files that are already in the repository There the only file changed is the book text itself fossilbook lyx All I have to do now is add in the directory Images which will add in the image files I want in the repository Then I commit the changes to the repository and we can move on to other tasks of the day Pandora 2 jschimpf Public FossilBook jim fossil add Images ADDED Images Single_user config_initial epsf ADDED Images Single_user initial_page epsf ADDED Images Single_user jim_setup epsf ADDED Images Single_user user_config epsf Pandora 2 jschimpf Public FossilBook jim fossil commit m Initial setup with pictures New_Version a2d12bf532a08 ee53578e3e17c6e732c0442f49 Figure 2 11 Update for new files Updated for fossil version 1 25 Page 11 of 107 M j Fossil Version Control Fossil SCM After doing this commit I can bring up the Fossil ui see Figure 2 5 on page 8 and view the project Timeline by picking that tab on the Fossil header We get this v l A A FossilBook Timeline Logged in as jim Home Timeline Files Leaves Branc
41. P port TCPPORT REPOSITORY Or fossil ui P port TCPPORT REPOSITORY Open a socket and begin listening and responding to HTTP requests on TCP port 8080 or on any other TCP port defined by the P or port option The optional argument is the name of the repository The repository argument may be omitted if the working directory is within an open checkout The ui command automatically starts a web browser after initializing the web server In the server command the REPOSITORY can be a directory aka folder that contains one or more repositories with names ending in fossil In that case the first element of the URL is used to select among the various repositories Figure 5 16 server detail 5 2 16 commit or 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 Pandora 2 jschimpf Public FossilBook jim fossil help commit Usage fossil commit OPTIONS FILE Create a new version containing all of the changes in the current checkout You will be prompted to enter a check in comment unless one of the m or M options are used to specify a comment m takes a single string for the commit message and M requires a filename from which to read the commit message If neither m nor M are specified then the editor defined in the editor fossil option see fossil help set will be used or from the VISUAL or EDI
42. TOR environment variables in that order if no editor is set You will be prompted for your GPG pass phrase in order to sign the new manifest unless the nosign options is used All files that have changed will be committed unless some subset of files is specified on the command line The branch option followed by a branch name cases the new check in to be placed in the named branch The bgcolor option can be followed by a color name ex ff c0c0 to specify the background color of entries in the new branch when shown in the web timeline interface A check in is not permitted to fork unless the force or f option appears A check in is not allowed against a closed check in The private option creates a private check in that is never synced Children of private check ins are automatically private Options comment m COMMENT TEXT branch NEW BRANCH NAME bgcolor COLOR nosign force f private message file M COMMENT FILE Pandora 2 jschimpf Public FossilBook jim Figure 5 17 commit details Updated for fossil version 1 25 Page 61 of 107 Vv 27 Fossil Version Control Fossil SCM 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 5 3 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
43. Then I applied the changes Now the repository is ready for further work it s rather bare bones at this point but the most impor tant things are set up Updated for fossil version 1 25 Page 10 of 107 TA Fossil Version Control Fossil SCM 2 3 1 User interface summary e fossil ui run in the source directory will start a browser based user interface to fossil e fossil ui port lt IP port gt Can be used if port 8080 if already in use on your system e On the first run it is important to configure your project with a name and set the password for yourself 2 4 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 Pandora 2 jschimpf Public FossilBook jim fossil extra tfossilbook lyx Images Single_user config_initial epsf Images Single_user initial_page epsf Images Single_user jim_setup epsf Images Single_user user_config epsf fossilbook lyx Pandora 2 jschimpf Public FossilBook jim fossil status repository Users jschimpf Public FOSSIL FossilBook fossil local root Users jschimpf Public FossilBook server code 0149388e5a3109a867332dd8439ac7Tb454f3f9dd checkout 8 a070818679e1744374bc5302a621490276d739 2010 04 25 13 09 02 UTC parent 279dfecd3f0322f236a92a9a8F3c
44. a 2 jschimpf Public FossilBook jim fossil help open Usage fossil open FILENAME VERSION keep Open a connection to the local repository in FILENAME A checkout for the repository is created with its root at the working directory If VERSION is specified then that version is checked out Otherwise the latest version is checked out No files other than manifest and manifest uuid are modified if the keep option is present See also the close command Figure 5 20 open details 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 Updated for fossil version 1 25 Page 63 of 107 TA Fossil Version Control Fossil SCM 5 3 4 close This is the opposite of open in that it breaks the connection between this working directory and the Fossil repository Pandora 2 jschimpf Public FossilBook jim fossil help close Usage fossil close f force The opposite of open Close the current database connection Require a f or force flag if there are unsaved changed in the current check out Figure 5 21 close details 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 dire
45. age 8 of 107 v wy Fossil Version Control Fossil SCM Ww j sgl Unnamed Fossil Project WWW Confi gt uration Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout FossilBaok Project Name Give your project a name so visitors know what this site is about The project name will also be used as the RSS feed title This is a user guide for Fossil It will show a new user how to setup and use this wonderfully simple source control system 4 Project Description Describe your project This will be used in page headers for search engines as well as a short RSS description Figure 2 7 Initial Configuration 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 2 6 on page 19 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 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 Mw A d FossilBook User List Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Add Users Notes UserID Capabilities Contact Info 1 The permission flags are as follows anonymous ghmncz Anon developer dei Dev a Admin Create and delete users er S Tee b Attach Add attachments to
46. alar variable with a particular name then it is not possible to make array references to the variable To convert a scalar variable to an array or vice versa remove the existing variable with the unset command 6 5 1 2 Variable scope Variables exist in a scope The TH interpreter maintains a global scope that is available to and shared by all commands executed by it Each invocation of a user defined command creates a new local scope This local scope holds the arguments and local variables of that user command invocation and only exists as long a the user command is executing If not in the body of user command then references to varname refer to a global variable i e a variable in the global scope In contrast in the body of a user defined command references to varname refer to a parameter or local variable of the command However in the body of a user defined command a global variable can be explicitly referred to by preceding its name by TH offers a special command to access variables not in the local scope of the current command but in the local scope of the call chain of commands that leas to the current command This is the upvar command upvar frame othervar myvar othervar myvar The upvar command arranges for one or more local variables in the current procedure to refer to variables in an enclosing procedure call or to global variables If frame is an integer then it gives a distance up the command calling stack to
47. and Initial Commit o o 7 2 2 5 Fossil start up summary 0 000000 eee 7 2 3 Set Up User interface e 8 2 3 1 User interface summary cesa Como 0 00000 ee eee 11 2 4 Update Repository a 11 2 4 1 Update Summary ooa 13 2 32 EKES 2 aaie e Sodas ea Ros PP A eS ee A ey A R a 14 25 1 Ticket Summary a a BATS A ay at ache eed 18 202 WIKLLUSCH svc eaten N Dane A Beh ee Ree 19 2 6 1 Wiki Summarys 2 22a A da beg eae ba eh ew a har BA 23 3 Multiple Users 25 Side Introduction a a ee oo na ee ee 25 3 2 SOUP tence dh ae Gh Meat tik ted eras di te allot Sec this Wee Bk eel rancid card 25 3 2 1 Server Setup sae ada ak SAA eee ae te 25 321 011 Selt hosted a 44 ow ea se dl a ra 25 3 2 1 0 2 Server hosted mirena ds do 26 3 2 1 0 3 CGI Script for hosted Server 26 3 2 2 The test either self hosted or server hosted 27 3 3 JUSer Accounts Ci ee arlene bok 28 111 Fossil Version Control Fossil SCM 3 4 Multiple User Operation ooo 30 3 4 1 CIONS 5 cr kd ee OE wa a a a 30 3 4 2 Keeping insyne os oca cau aa eee a 31 3 4 3 Complications oaoa 0 0000 2 ee 32 3 4 4 Fixing the Update file o e 34 3 4 5 Fixing the Merge file o e e 36 4 Forks amp Branches 39 4 1 Introduction sc 6 44 ee a a a a 39 4 2 Forks Branch amp Merge
48. ands 6 6 7 Special commands nn 6 7 working with strings o 6 8 working with lists o o ee 7 What s next A Document Revision History 107 Updated for fossil version 1 25 vi Disclaimer Pandora Products has carefully checked the information in this document and believes it to be accu rate 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 e Marilyn Noz Editor e Wolfgang Stumvoll Fossil Merge use and Windows use e Paul Ruizendaal TH 1 Scripting Language manual e javalinBCD gmail com found bugs e arnel_legaspi msn com found bugs 1 Source Control amp Why you need it 1 1 What is Source Control 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 These files in turn are managed by organizing them in directories and sub director
49. ature 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 g nv y Fossilbook Ticket Main Menu ie Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Enter a new ticket e New ticket Choose a report format from the following list 1 All Tickets copy edit sal Create a new ticket display format e New report format Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 14 Initial Ticket Window Picking New Ticket I get a form that I fill out like so Updated for fossil version 1 25 Page 14 of 107 M 2 Fossil Version Control Fossil SCM de New Ticket Logged in as jim Enter A New Ticket Enter a one line summary of the ticket Add in the Ticket operations to the Single User chapter Type What type of ticket is this Version In what version or build number do you observe the problem ihre How debilitating is the problem How badly does the problem affect the Severity operation of the product EMail jim schimpf gmail com Not publicly visible Used by developers to contact you with questions E
50. ay be end to refer to the last character of the string If first is less than zero then it is treated as if it was zero and if last is greater than or equal to the length of the string then it is treated as if it were end If first is greater than last then an empty string is returned The string repeat subcommand returns a string that is formed by repeating the argument string for count times The argument count must be an integer If count is zero or less the empty string is returned The string is alnum subcommand tests whether the argument string is an alphanumeric string i e a string with only alphanumeric characters It returns a decimal string with value 1 if the string is alphanumeric and with value 0 it is not 6 8 working with lists The list is the basic TH data structure A list is simply an ordered collection of items numbers words strings or other lists For instance the following string is a list with four items The third item is a sub list with two items first second a b fourth TH has three core commands to work with lists list argl arg2 lindex list index llength list The list command returns a list comprising all the args Braces and backslashes get added as necessary so that the lindex command may be used on the result to re extract the original arguments For example the command Updated for fossil version 1 25 Page 96 of 107 Fossil Version Control Fossil SCM list ab c d e f
51. bee at Pe ea 2 16 Viewing a Ticket soe aeu kon ar at a a eo ek kh dd 2 17 Ticket List with open ticket a 2 18 Ticket resolving check in 2 a 2192 Ticket Finish ze ana wach A es sla ala e Sa eo AE Shae ne 2 20 Blank Home Page ee 2 21 Wiki controls 2 2 2 4 ob echt is ee en 2 22 Wiki Formatting u 2 2 2 by A ea A Se SE ty 2 23 Home page with edit 2 22 u a A hy aw a aad 2 24 Initial Home page ne 2 22 2 2 Boke a aan Aka ie 3 1 Self hosted Fossil repository 2 2 o e e 3 25 Fos EOI script ivi a vr ia a he Mow hs eae BA 3 3 My Fossil EOLSCTPE 25 4 5 2 2a OR a Sn Shades 3 4 Copying script into place ee 3 5 Web access to Fossil CGI hosted site 2 2 0 nen 3 6 New Editor User vivo ti bce eae au ne ed be do dd 3 7 Clone command oaaae 3 8 Cloned repository checkin ooa ee 3 9 Update action s s sasine e ies seh ar eine e ala a Sha se ach 3 10 Updated Timeline 2 ee S A Forking Commit 2 2 es Soy ee ee en 3 12 Update diy t n it ES ne ein vo ooN NAD 11 11 12 13 14 15 16 16 17 18 19 20 20 21 22 25 26 27 27 27 29 30 31 32 32 33 33 101 Fossil Version Control Fossil SCM 3 13 Update dry run shorter ee 34 3 14 Current Timeline ee 35 3 15 Update fossilbook pdf o o ee ee 35 3 16 Forcing a commit under Windows e 36 3 17 Windows Forked timeline
52. cannot be undone You will be prompted before removing each file If you are sure you wish to remove all extra files you can specify the optional force flag and no prompts will be issued Files and subdirectories whose names begin with are normally ignored They are included if the dotfiles option is used Figure 5 28 clean details 5 3 12 branch This command is used if you want to create or list branches in arepository Previously we discussed forks See Section 3 4 3 on page 32 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 Pandora 2 jschimpf Public FossilBook jim fossil help branch Usage fossil branch SUBCOMMAND R repository FILE Run various subcommands on the branches of the open repository or of the repository identified by the R or repository option fossil branch new BRANCH NAME BASIS bgcolor COLOR Create a new branch BRANCH NAME off of check in BASIS You can optionally give the branch a default color fossil branch list List all branches Figure 5 29 branch details 5 3 13 merge This command does the opposite of branch it brings two branches together Updated for fossil version 1 25 Page 67 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help merge Usage fossil mer
53. ch entry name delimited by the s char fossil wiki diff ARTIFACT f infile stdin EntryName Diffs the local copy of a page with a given version defaulting to the head version Figure 5 37 wiki detail 5 5 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 5 5 1 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 Updated for fossil version 1 25 Page 74 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help scrub COMMAND scrub fossil scrub verily force REPOSITORY The command removes sensitive information such as passwords from a repository so that the repository can be sent to an untrusted reader By default only passwords are removed However if the verily option is added then private branches concealed email addresses IP addresses of correspondents and similar privacy sensitive fields are also purged This command permanently deletes the scrubbed information The effects of this command are irreversible Use with caution The user is prompted to confirm the scrub unless the force option is used Figure 5 38 scrub detail 5 5 2 search This i
54. configuration of Fossil Updated for fossil version 1 25 Page 76 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help configuration Usage fossil configure METHOD Where METHOD is one of export import merge pull push reset All methods accept the R or repository option to specific a repository fossil configuration export AREA FILENAME Write to FILENAME exported configuration information for AREA AREA can be one of all ticket skin project fossil configuration import FILENAME Read a configuration from FILENAME overwriting the current configuration fossil configuration merge FILENAME Read a configuration from FILENAME and merge its values into the current configuration Existing values take priority over values read from FILENAME fossil configuration pull AREA URL Pull and install the configuration from a different server identified by URL If no URL is specified then the default server is used fossil configuration push AREA URL Push the local configuration into the remote server identified by URL Admin privilege is required on the remote server for this to work fossil configuration reset AREA Restore the configuration to the default AREA as above WARNING Do not import merge or pull configurations from an untrusted source The inbound configuration is not checked for safety and can introduce security vulnerabilities Figure 5 42 configura
55. ctory and the repository With the force flag you can explicitly cut the connection even if there are changes 5 3 5 version This command is used to show the current version of fossil Pandora 2 jschimpf Public FossilBook jim fossil help version Usage fossil version Print the source code version number for the fossil executable Pandora 2 jschimpf Public FossilBook jim fossil version This is fossil version c56af6le5e 2010 04 22 15 48 25 UTC Pandora 2 jschimpf Public FossilBook jim Figure 5 22 version details 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 5 3 6 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 Pandora 2 jschimpf Public FossilBook jim fossil help rebuild Usage fossil rebuild REPOSITORY Reconstruct the named repository database from the core records Run this command after updating the fossil executable in a way that changes the database schema Figure 5 23 rebuild details Updated for fossil version 1 25 Page 64 of 107 TA Fossil Version Control Fossil SCM 5 3 7 all This co
56. current time The optional TYPE argument may any types supported by the timeline page For example w wiki commits only ci file commits only t tickets only Figure 5 36 timeline detail 5 4 5 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 Updated for fossil version 1 25 Page 73 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help wiki Usage fossil wiki export create commit list WikiName Run various subcommands to work with wiki entries fossil wiki export PAGENAME FILE Sends the latest version of the PAGENAME wiki entry to the given file or standard output fossil wiki commit PAGENAME FILE Commit changes to a wiki page from FILE or from standard input fossil wiki create PAGENAME FILE Create a new wiki page with initial content taken from FILE or from standard input fossil wiki list Lists all wiki entries one per line ordered case insentively by name TODOs fossil wiki export u ARTIFACT WikiName FILE Outputs the selected version of WikiName fossil wiki delete m MESSAGE WikiName The same as deleting a file entry but i don t know if fossil supports a commit message for Wiki entries fossil wiki u d s list Lists the artifact ID and or Date of last change along with ea
57. cutable here http www fossil scm org download html There are Linux Mac and Windows executable links on this page The source code is also available if you want or need to compile yourself This web site containing this PDF and the code behind the PDF is self hosted by Fossil see Section 3 on page 25 1 3 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 1 3 1 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 Updated for fossil version 1 25 Page 2 of 107 Vv A Fossil Version Control Fossil SCM 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
58. d69la5ea738cd5lccbf9a581ldfb3c7 2010 06 13 10 13 55 UTC parent 462156b283b694af0b99C9b446b64d3f77436fbb 2010 06 09 14 16 42 UTC tags VER_1 0 Figure 4 16 Check out VER_1 0 Checking out VER_2 0 in the same way Updated for fossil version 1 25 Page 49 of 107 Vv a Fossil Version Control Fossil SCM Pandora 2 jschimpf Public jsonp2 jim fossil open FOSSIL jsonp fossil VER_2 0 docs qdj lyx docs qdj pdf json src qdj c json src qdj h json src qdj_token c json src qdj_token h json src qdj_util c main c makefile obj test txt test txt project name JASONP repository Users jschimpf Public FOSSIL jsonp fossil local root Users jschimpf Public jsonp2 project code eb6084c8ab115cf2b28a129c7183731002c6143a server code 90c80fla2da7360dae230ccec65ff82fe2eb160d checkout a1737916ec2df696a0f3a7e36edf9ba4370e48a7 2010 06 13 10 14 26 UTC parent 462156b283b694af0b99c9b446b64d3f77436fkbb 2010 06 09 14 16 42 UTC tags VER_2 0 Figure 4 17 VER_2 0 checkout Notice on both of these the tags show which branch we are attached to 4 4 5 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 b
59. ded 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 Updated for fossil version 1 25 Page 55 of 107 g Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help changes Usage fossil changes Report on the edit status of all files in the current checkout See also the status and extra commands Figure 5 7 changes details Pandora 2 jschimpf Public FossilBook jim fossil status repository Users jschimpf Public FOSSIL FossilBook fossil local root Users jschimpf Public FossilBook server code 3e67da6d6212494456c69b1c5406a277d7e50430 checkout eda5b5fa4277604f365ec09238422c0aa7a28faf 2010 05 08 14 44 21 UTC parent 3f019cbc730db0eb35f20941533a22635856b2b3 2010 05 08 11 15 19 UTC tags trunk EDITED fossilbook lyx EDITED outline txt Figure 5 6 status run 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 5 2 6 changes This lists the changed files like status but does not show the other information that status does 5 2 7 extra The extra command is used to find files you have added to your working directory but are not yet under Fossil c
60. didn t touch these files and Marilyn didn t touch the code files Next Jim does a commit to make this new merged set of files the new trunk Rememeber doing the merge shown in Figure 4 5 just updates your checked out code and does not change the repository till you check it in 558 jsonp gt fossil commit m After merging in changes Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 1 30 1 0 0 Received 1058 23 0 0 Total network traffic 340 bytes sent 864 bytes received New_Version 3d73c03edee33cdc2elbd8a47de57b7a6b6d880a Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 1737 26 0 1 Received 1104 24 0 0 Total network traffic 1101 bytes sent 888 bytes received 559 jsonp gt Figure 4 6 Commit after merge When we look at the timeline we have a single leaf for future code commits Updated for fossil version 1 25 Page 42 of 107 v yA Fossil Version Control Fossil SCM A N ri jasonp Timeline Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logou 200 Events Checkins Only Tickets Only Wiki Only 10 most recent events 10 50 Tested ticket d23bf4bbbb Fix warnings in main amp qdj_util plus 4 other changes user jim 10 48 3d73c03ede Merge Leaf After merging in changes user jim tags trunk 10 44 1beab95541 d23bf4bbbb Remove warnings user jim tags trunk
61. dly evaluates con dition as an expression if the result is non zero it invokes the TH interpreter on body then invokes the TH interpreter on incr then repeats the loop The command terminates when test evaluates to Zero If a continue command is invoked within execution of the body script then any remaining commands in the current execution of body are skipped processing continues by invoking the TH interpreter on incr then evaluating condition and so on If a break command is invoked within body or next then the for command will return immediately The operation of break and continue are similar to the corresponding statements in C The for command returns an empty string The break command has the following syntax break value Updated for fossil version 1 25 Page 92 of 107 Viv A Fossil Version Control Fossil SCM The break command returns immediately from the current procedure or top level command with value as the return value and TH_BREAK as the result code If value is not specified the string break will be returned as result The continue command has the following syntax continue value The continue command returns immediately from the current procedure or top level command with value as the return value and TH_CONTINUE as the result code If value is not specified the string continue will be returned as result The error command has the following syntax error value The error comma
62. e amed files are candidates to be updated If FILES is omitted all iles in the current checkout are subject to be updated he n or nochange option causes this command to do a dry run It rints out what would have happened but does not actually make any hanges to the current checkout or the repository he v or verbose option prints status information about unchanged files in addition to those file that actually do change HQAVCHMDH IS HEtHHA Figure 5 10 update details Update has a number of options first you can tie the update to a particular version if not picked then it just uses the latest Second it can work on a single files or many files at once That is you could say fossil update c 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 5 2 10 checkout or co This command is similar to update Pandora 2 jschimpf Public FossilBook jim fossil help checkout Usage fossil checkout VERSION f force keep Check out a version specified on the command line This command will abort if there are edited files in the current checkout unless the force option appears on the comma
63. e This rule is important if you have a variable value or a command result that contains special characters such as spaces dollar signs square brackets or curly brackets Because only a single round of substitution is done you do not have to worry about special characters in values causing extra substitutions 6 3 5 1 Caveats e A common error is to forget a space between arguments when grouping with curly brackets or quotes This is because white space is used as the separator while the curly brackets or quotes only provide grouping If you forget the space you will get syntax errors about the wrong number of arguments being applied The following is an error because of the missing space between and if x gt 1 puts x x e When double quotes are used for grouping the special effect of curly brackets is turned off Substitutions occur everywhere inside a group formed with double quotes In the next command the variables are still substituted set x xvalue set y foo x bar gt foo xvalue bar e Spaces are not required around the square brackets used for command substitution For the purposes of grouping the interpreter considers everything between the square brackets as part of the current group Updated for fossil version 1 25 Page 85 of 107 Fossil Version Control Fossil SCM 6 4 TH expressions The TH interpreter itself does not evaluate math expressions TH just does grouping substitutions and co
64. e is now g s amp _ 4 a yasonp Timeline Home Timeline Files Leaves Branches Tags Tickets Wiki Admin 200 Events Checkins Only Tickets Only Wiki Only 19 most recent events a1737916ec Leaf Create new branch named VER_2 0 user jim tags VER_2 0 65e1f48633 Leaf Create new branch named VER_1 0 user jim tags VER_1 0 Tested ticket fed383fa1a Add help to MAIN plus 4 other changes user jim 462156b283 Branch Point Leaf fed383fa1a Add help to cmd line user jim tags trunk New ticket fed383fata Add help to MAIN user jim Closed ticket ZB424402e4 Add BSD license to code plus 2 other changes user Marilyn 1 similar event omitted 14 02 fbb16491e2 7642446264 Add BSD license to code user Marilyn tags trunk 13 57 New ticket 75429264 Add BSD license to code user Marilyn Figure 4 14 Branch Timeline Updated for fossil version 1 25 Page 47 of 107 Lo v oy Fossil Version Control Fossil SCM 4 4 3 Color Setup As you see above the two branches have different colors in the timeline This was due to the bgcolor option added when we created each branch See Figure 4 13 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 t a Edit Check in 65e1f48633 Home Timeline Files Leaves Branches Tags Tickets Wiki Ad Make change
65. e 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 Pandora 2 jschimpf Public FossilBook jim fossil help diff Usage fossil diff gdiff options FILE Show the difference between the current version of FILE as it xists on disk and that same file as it was checked out Or f the FILE argument is omitted show the unsaved changed currently n the working check out f the from VERSION or r VERSION option is used it specifies he source check in for the diff operation If not specified the ource check in is the base check in for the current check out f the to VERSION option appears it specifies the check in from hich the second version of the file or files is taken If there is to option then the possibly edited files in the current check out re used he i command line option forces the use of the internal diff logic ather than any external diff program that might be configured using he setting command If no external diff program is configured then he i option is a no op The i option converts gdiff into diff o COR HMB EHO HHHO Figure 5 13 diff details 5 2 13 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 Updated for fossil versio
66. ed for fossil version 1 25 Page 34 of 107 M a Fossil Version Control Fossil SCM FossilBook Timeline Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout 200 Events Checkins Only Older Tickets Only Wiki Only 20 most recent events 11 36 Closed ticket ebf40b842a Editorial corrections spelling etc plus 4 other changes user Marilyn 11 34 yy d44769cc23 Leaf ebf4068422 Editorial corrections on text thus far user marilyn tags trunk 10 48 New ticket ebf40b842a Editorial corrections spelling etc user Marilyn 11 35 7 aad7dd10f3 Commit last change and updated PDF user jim tags trunk 11 24 7 158492516c Moved to clone repository user jim tags trunk 10 03 7 1a403c87fc Update before moving to server user jim tags trunk 11 03 fe5578c96f Correct site URL user jim tags trunk 10 52 7 fa5b9247bd Working on chapter 1 user jim tags trunk 11 16 Changes to wiki page tools user jim 11 15 51be6423a3 Update outline user jim tags trunk 11 08 7 2234149037027a Clean up Single user chapter and working initial chapter user jim tags trunk 11 08 7 7c37c13190 End of day commit user jim tags trunk san A o o pee Figure 3 14 Current Timeline I see that the current Leaf is d44769cc23 and it is tagged as trunk I want to update the fossil book pdf from there So I say Pandora 2 jschimpf Public FossilBook jim f
67. every historical version of every baseline and file The Zip privilege allows a user to see the download as ZIP hyperlink and permits access to the zip page This allows users to download ZIP archives without granting other rights like Read or History This privilege is recommended for user nobody so that automatic package downloaders can obtain the sources without going through the login procedure Figure 3 6 New Editor user 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 Updated for fossil version 1 25 Page 29 of 107 Fossil Version Control Fossil SCM 3 4 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 repo
68. form lt new page gt lt title gt This way I can have a long string that describes the link but have a nice short no embedded spaces page name One mistake I usually make at this point is to click one of those new links which takes me to a new blank page OOPS if I have not saved this page yet then I find I ve lost my changes so far OK I will save my changes and then go to the new pages I am doing some complicated things here The first link is to the book PDF This will be a file I create in the repository The LyX program I m Updated for fossil version 1 25 Page 22 of 107 Viv A Fossil Version Control Fossil SCM using creates the PDF I will do that save it and add it to the repository But I don t want to link to a static file that is I want the most current version of the PDF the one I save each time I quit for the day To do this we have to put in a link that looks like this http doc tip FossilBook pdf Book pdf This is a special link the Fossil wiki understands doc says this is documentation 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 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 2 6 1 Wiki Summary e Format your text using HTML commands
69. fossil help zip Usage fossil zip VERSION OUTPUTFILE name DIRECTORYNAME Generate a ZIP archive for a specified version If the name option is used it argument becomes the name of the top level directory in the resulting ZIP archive If name is omitted the top level directory named is derived from the project name the check in date and time and the artifact ID of the check in Figure 5 33 zip detail 5 4 2 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 3 6 on page 29 Pandora 2 jschimpf Public FossilBook jim fossil help user Usage fossil user SUBCOMMAND R repository FILE Run various subcommands on users of the open repository or of the repository identified by the R or repository option fossil user capabilities USERNAME STRING Query or set the capabilities for user USERNAME fossil user default USERNAME Query or set the default user The default user is the user for command line interaction fossil user list List all users known to the repository fossil user new USERNAME CONTACT INFO PASSWORD Create a new user in the repository Users can never be deleted They can be denied all access but they must continue to exist in the database fossil user password USERNAME PASSWORD Change the web access password for a user Figure 5 34 user detail 5 4 3 finfo This command will pr
70. ge cherrypick backout VERSION The argument is a version that should be merged into the current checkout All changes from VERSION back to the nearest common ancestor are merged Except if either of the cherrypick or backout options are used only the changes associated with the single check in VERSION are merged The backout option causes the changes associated with VERSION to be removed from the current checkout rather than added Only file content is merged The result continues to use the file and directory names from the current checkout even if those names might have been changed in the branch being merged in Other options detail Show additional details of the merge binary GLOBPATTERN Treat files that match GLOBPATTERN as binary and do not try to merge parallel changes This option overrides the binary glob setting Figure 5 30 merge details 5 3 14 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 on page Updated for fossil version 1 25 Page 68 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help tag Usage fossil tag SUBCOMMAND Run various subcommands to control tags and properties fossil tag add raw propagate TAGNAME CHECK IN VALUE Add a new
71. gi directory path is Library Webserver CGI Executables then we have to write a script of the form lt Fossil executable location gt repository lt Fossil repository location gt Figure 3 2 Fossil CGI script Updated for fossil version 1 25 Page 26 of 107 M oj Fossil Version Control Fossil SCM 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 usr local bin fossil Put the book repository on the web repository Users Shared FOSSIL Fossilbook fossil Figure 3 3 My Fossil CGI script After making the script I then copy it to the CGI directory and allow anyone to execute it sudo cp Book cgi Library Webserver CGI Executables Book cgi sudo chmod a x Library Webserver CGI Executables Book cgi Figure 3 4 Copying script into place 3 2 2 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 4 v gt FossilBook FossilBook Not logged in Home Timeline Leaves Branches Tags Tickets Wiki Login Fossil User Manual This repository holds the text and images of a Fossil user manual This will show a new user how to use the many features of this innovative and simple source control tool The manual will be illustrated with screen captures showing both command line and bro
72. guration Contact Info changes An Admin user can add other users and change user privileges and reset user passwords Capabilities ur Both automatically get all other privileges listed below Use these two settings with discretion O Delete O Email e The mark indicates the privileges of nobody O Password that are available to all users regardless of O Check In whether or not they are logged in O Check Out O History e The mark indicates the privileges of O Reader anonymous that are inherited by all logged in M Developer users O Clone O Read Wiki e The mark indicates the privileges of ONew Wiki developer that are inherited by all users with the O Append Wiki Developer privilege O Write Wiki m Attachments e The mark indicates the privileges of reader O Read Ticket that are inherited by all users with the Reader O New Ticket privilege O Append Ticket O Write Ticket The Delete privilege give the user the ability to O Ticket Report erase wiki tickets and attachments that have 3 been added by anonymous users This capability i idle is intended for deletion of spam The delete Password son capability is only in effect for 24 hours after the item is first posted The Setup user can delete anything at any time e The History privilege allows a user to see most hyperlinks This is recommended ON for most logged in users but OFF for user nobody to avoid problems with spiders trying to walk
73. h special characters to fetch variables and to perform nested command calls Hence the behavior of the TH command processor can be summarized in three basic steps 1 Argument grouping 2 Value substitution of backslash escapes variables and nested commands 3 Command invocation Note that there is no step to evaluate the arguments to a command After substitution arguments are passed verbatim to the command and it is up to the command to evaluate its arguments as needed 6 3 4 1 Argument grouping TH has two mechanisms for grouping multiple words into a single item 66909 e Double quotes e Curly brackets Whilst both have the effect of grouping a set of words they have different impact on the next phase of substitution In brief double quotes only group their content and curly brackets group and prevent all substitution on their content Grouping proceeds from left to right in the string and is not affected by the subsequent substitution If a substitution leads to a string which would be grouped differently 1t has no effect as the grouping has already been decided in the preceding grouping phase Updated for fossil version 1 25 Page 81 of 107 Fossil Version Control Fossil SCM 6 3 4 2 Value substitutions TH performs three different substitutions see the th c thSubstWord code for details e Backslash escape substitution e Variable substitution e Nested command substitution Like grouping substitution pr
74. he book Layout fossil png The Fossil logo image on title page Research fossilbib bib Working bibliography History CVC grune pdf Historical paper about CVS RCS A System for Version Control webloc RCS bookmark SCCS Slideshow pdf Historical paper about SCCS VCSHistory pysync webloc History of version control This took just an hour or so to start preliminary research and build the framework Since that s about all Pm going to do today I want to build a repository and put all this stuff under Fossil control g Fossil Version Control Fossil SCM 2 2 2 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 Pandora 2 jschimpf Public FossilBook jim fossil new FOSSIL FossilBook fossil project id 2b0d35831c1a5b315d74c4fd8d532b100b822ad7 server id 0149388e5a3109a867332dd8439ac7b454f3f9dd admin user jim initial password is ec3773 Figure 2 1 Create Repository I create my repositories with the extension fossil this will be useful later with the server command See Figure 5 16 on page 61 When the create happened it assigned an initial password with an admin user of jim i e me 2 2 3 Connect Repository The repository is created but
75. he invoking procedure to disappear from the procedure calling stack while the command is being executed In the above example suppose c invokes the command uplevel 1 set x 43 d where d is another TH procedure The set command will modify the variable x in the context of b and d will execute at level 3 as if called from b If it in turn executes the command uplevel set x 42 then the set command will modify the same variable x in the context of b context the procedure c does not appear to be on the call stack when d is executing 6 7 working with strings TH provides the string command to facilitate working with strings The string command is a single command with seven subcommands identified by the first argument The first argument serves no purpose other than to identify the subcommand If the first argument does not match a subcommand an error is thrown The seven string subcommands are string length string string compare stringl string2 string first needle haystack startindex string last needle haystack startindex string range string first last string repeat string count string is alnum string The string length subcommand takes one parameter which is a string It returns the decimal string with the length of the string As TH uses a single byte character encoding the string size is both the size in characters and in bytes Updated for fossil version 1 25 Page 95 of 107 Vv A Fossil Ver
76. here or to 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 5 3 1 new This command is used to create a new repository Pandora 2 jschimpf Public FossilBook jim fossil help new Usage fossil new OPTIONS FILENAME Create a repository for a new project in the file named FILENAME This command is distinct from clone The clone command makes a copy of an existing project This command starts a new project By default your current login name is used to create the default admin user This can be overridden using the A admin user parameter Options admin user A USERNAME date override DATETIME Figure 5 18 new details 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 5 3 2 clone The clone command is used to create your own local version of the master repository If you are sup porting multiple users via a network accessible version of the original repository see Section 3 2 1 on page 25 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 Updated for
77. hes Tags Tickets Wiki Admin Logout 200 Events Checkins Only Tickets Only Wiki Only 4 most recent events 497b93858f Leaf Update to catch changes in outline user jim tags trunk a2d12bf532 Initial setup with pictures user jim tags trunk 13 09 8fa0708186 Initial Commit user jim tags trunk 12 40 E 279dfecd3f initial empty check in user jim tags trunk Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 12 Timeline You can see all my check ins thus far and you can see after the check in from Figure 2 11 on the preceding page 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 Updated for fossil version 1 25 Page 12 of 107 M p Fossil Version Control Fossil SCM da n Fossittoon Check in 497b93858f TE S SHA1 Hash 497b93858f48b8885936906ce470aeb38fd7fbc2 Record ID 19 Date 2010 04 26 11 32 57 User jim Comment Update to catch changes in outline Received From jim on 2010 04 26 11 32 57 Timelines ancestors descendants both trunk Other Links files ZIP archive manifest edit LET tale HIT IE e branch trunk inherited from 279dfecd3f branch timeline e sym trunk inherited from 279dfecd3f show diffs Modified fossilbook lyx from 62adda90bf0cf9d2 to cec3960e6877e7
78. ib bib ssilbook lyx ossilbook pdf GED outline txt Pandora 2 jschimpf Public FossilBook jim Zz Z Zz Z Zz Z z Z zZ z 4000000000000 0 000 0 000 000 ica Q BHM PED PREP EEE RPE EP RPE ERE RE BS o FU A ie OS SUS Ss o O Cc C C C C Cc Cc Cc C Cc C C C CH C C C C C Cc C Cc Cc Ri D Cc a Figure 3 12 Update dry run Updated for fossil version 1 25 Page 33 of 107 Vv A Fossil Version Control Fossil SCM That s a little more than I wanted as you can see almost everything is UNCHANGED but it shows that fossilbook lyx needs a MERGE and fossilbook pdf needs an UPDATE This is what I should expect Marilyn has done edits to the fossilbook lyx file and so have I so we have to merge the changes But she has also updated the fossilbook pdf which I have not Before we go on if you are running on Linux or UNIX you can simplify this dry run by doing Pandora 2 jschimpf Public FossilBook jim fossil update n v grep v UNCHANGED MERGE fossilbook lyx UPDATE fossilbook pdf Figure 3 13 Update dry run shorter By using the pipe and grep I can eliminate all those extra UNCHANGED lines 3 4 4 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 Updat
79. ies At any particular time this set of files in their present edited state make up a working copy of the project at the latest version If other people are working the same project you would give them your current working copy to start with As they find and fix problems their working copy will become different from the one that you have it will be in a different version For you to be able to continue where they left off you will need some mechanism to update your working copy of the files to the latest version available in the team As soon as you have updated your files this new version of the project goes through the same cycle again Most likely the current version will be identified with a code 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 and 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 work of all team members to fix bugs and write enhancements were included A tool called Source Code Control System 6 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
80. ill occur The characters after the up to the first character that isn t a number letter or underscore are taken as a variable name and the string value of that variable is substituted for the name For example if variable foo has the value test then the command puts foo c is equivalent to the command puts test c There are two special forms for variable substitution If the next character after the name of the variable is an open parenthesis then the variable is assumed to be an array name and all of the characters between the open parenthesis and the next close parenthesis are taken as an index into the array Command substitutions and variable substitutions are performed on the information between the parentheses before it is used as an index For example if the variable x is an array with one element named first and value 87 and another element named 14 and value more then the command puts xyz x first zyx Updated for fossil version 1 25 Page 82 of 107 Fossil Version Control Fossil SCM is equivalent to the command puts xyz87zyx If the variable index has the value 14 then the command puts xyzSx Sindex zyx is equivalent to the command puts xyzmorezyx See the section Variables and arrays below for more information on arrays The second special form for variables occurs when the dollar sign is followed by an open curly bracket In this case the variable name consists of all the characters up to
81. int 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 Updated for fossil version 1 25 Page 71 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help finfo Usage fossil finfo FILENAME Print the change history for a single file The limit N and offset P options limits the output to the first N changes after skipping P changes Figure 5 35 finfo detail An example would be to run it on the outline txt file in our book directory Pandora 2 jschimpf Public FossilBook jim fossil finfo outline txt History of outline txt 2010 05 17 0272dc0169 Finished maintenance commands user jim artifact 25b6e38e97 2010 05 12 5e5c0f7d55 End of day commit user jim artifact dlald31fbd 2010 05 10 e924ca3525 End of day update user jim artifact 7cd19079al 2010 05 09 Oabb95b046 Intermediate commit not done with basic commands user Jim artifact 6f7bcd48b9 2010 05 07 6921e453cd Update outline amp book corrections user jim artifact 4eff85c793 2010 05 03 158492516c Moved to clone repository user jim artifact 23b729cb66 2010 05 03 1a403c87fc Update before moving to server user Jim artifact 706a9d3 94d 2010 04 30 fa5b9247bd Working on chapter 1 user jim artifact 7b6bb188 f0c6 2010 04 29
82. integer values If an operand is not in integer format then it is treated as a floating point number if that is possible Floating point numbers may be specified in any of the ways accepted by an ANSI compliant C compiler For example all of the following are valid floating point numbers 2 1 3 6e4 7 91e 16 If no numeric interpretation is possible then an operand is left as a string and only a limited set of operators may be applied to it Operands may be specified in any of the following ways e As a numeric value either integer or floating point e As astring enclosed in curly brackets The characters between the opening bracket and match ing closing bracket are used as the operand without any substitutions e As a string enclosed in double quotes The expression parser performs variable and com mand substitutions on the information between the quotes and uses the resulting value as the operand e Asa TH variable using standard notation The variable s value is used as the operand e As a TH command enclosed in square brackets The command will be executed and its result will be used as the operand Where substitutions occur above e g inside quoted strings they are performed by the expression processor However an additional layer of substitution may already have been performed by the Updated for fossil version 1 25 Page 86 of 107 Vv A Fossil Version Control Fossil SCM command parser before the expressio
83. is checked out by some one else and you have to make a change in it In a small group setting just a shout over the cube wall will solve the problem 1 3 2 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 1 3 3 Distributed systems The representatives of two major systems we have described thus far a
84. ities Both automatically get all other privileges listed below Bremen Use these two settings with discretion O Delete 8 a The mark indicates the privileges of nobody that Passwor are available to all users regardless of whether or not OCheck In they are logged in O Check Out O History The mark indicates the privileges of anonymous O Reader that are inherited by all logged in users o Developer O Clone The mark indicates the privileges of developer O Read Wiki that are inherited by all users with the Developer ONew Wiki privilege Append Wiki O Write Wiki The mark indicates the privileges of reader that O Attachments are inherited by all users with the Reader privilege Read Ticket O New Ticket The Delete privilege give the user the ability to erase Append Ticket wiki tickets and attachments that have been added by O Write Ticket anonymous users This capability is intended for 2 Ticket Report deletion of spam The delete capability is only in effect A for 24 hours after the item is first posted The Setup Download Zip h user can delete anything at any time Password o mo o o The History privilege allows a user to see most hyperlinks This is recommended ON for most logged in users but OFF for user nobody to avoid problems Figure 2 9 Super User Setup 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
85. k 11 08 7c37c13190 End of day commit user jim tags trunk Lan AN Figure 3 10 Updated Timeline Now I know I have the current state of the world and I can proceed to add in new sections 3 4 3 Complications In 3 4 2 on the previous page 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 Updated for fossil version 1 25 Page 32 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil commit m Commit that might fork Autosync http jim pandora dyn o saur com 8080 cgi bin Book cgi Bytes Cards Artifacts Deltas Send 130 1 0 0 Received 4002 87 0 0 Send 365 6 0 0 Received 110470 92 2 3 Total network traffic 797 bytes sent 104567 bytes received fossil would fork update first or use f or force Pandora 2 jschimpf Public FossilBook jim Figure 3 11 Forking commit Ah ha that very thing has happened and fossil warned me that my copy of the file differs from the master copy If I did a force then the repository would generate a fork and Marilyn s future commits would be to her fork and my commits would be to mine That would not be what we want since I want her to edit my copy of the boo
86. k The next step would be to do as Fossil says and do an update At this point you have to be careful since blindly updating the changed files could overwrite the stuff I ve just done So we do a trial update by using the n and v options to say do a dry run and show me the results Pandora 2 jschimpf Public FossilBook jim fossil update n v UNCHANGED Images Multiple_user mul_new_user epsf UNCH D Images Multiple_user mul_timeline epsf D Images Multiple_user test_access epsf D Images Single_user config_initial epsf D Images Single_user initial_page epsf D Images Single_user jim_setup epsf D Images Single_user ticket_done epsf D Images Single_user ticket_form epsf D Images Single_user ticket_initial epsf D Images Single_user ticket_list epsf D Images Single_user ticket_submit epsf D Images Single_user timeline epsf D Images Single_user timeline_detail epsf D D D D D D D D D D D z gt Z Z Q Zz Z Zz Z 2 zZ Z zZ Zz Z Images Single_user user_config epsf Images Single_user wiki_blankhome epsf Images Single_user wiki_formating epsf Images Single_user wiki_home epsf Images Single_user wiki_homeedit epsf Images Single_user wiki_page epsf Layout fossil png Research History CVS grune pdf Research History RCS A System for Version Control webloc Research History SCCS Slideshow pdf Research History VCSHistory pysync A Brief History of Version Control Systems Project H D Research fossilb
87. ks through the documentation and finds a number of problems and fixes them the documen tation uses LyX and PDF s When she is satisfied with what she has done she checks the current version of the documentation in 39 M nj Fossil Version Control Fossil SCM T N JASONP Timeline Home Timeline Files Leaves Branches Tags Tickets 200 Events Checkins Only Tickets Only Wiki q 7 most recent events b72e96832e Leaf Update documentation user Marilyn tags trunk New ticket d23bf4bbbb Fix warnings in main qdj_util user jim Changes to wiki page JASONP user jim Changes to wiki page JASONP user jim Changes to wiki page JASONP user jim 10 45 Sedbaf5fa8 Initial Checkin user jim tags trunk 10 44 b4bca2a0c5 initial empty check in user jim tags trunk Figure 4 1 Marilyn s work 4 2 2 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 4 1 After fixing the warnings Jim is done and goes to commit He does this AFTER Marilyn has done her commit 551 jsonp gt fossil commit m d23bf4bbbb Remove warnings Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 130 1 0 0 Received 874 19 0 0 Total network traffic 339 bytes sent 771 bytes received fossil would fork update first or us f or force 552 jsonp gt Figure 4
88. l Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil update trunk Autosync http Jjim pandora dyn o saur com 8080 cgi bin Book cgi Bytes Cards Artifacts Deltas Send 130 100 Received 3588 78 0 0 Send 365 6 0 0 Received 136461 83 2 3 Total network traffic 796 bytes sent 131582 bytes received UPDATE fossilbook lyx UPDATE fossilbook pdf Pandora 2 jschimpf Public FossilBook jim Figure 3 9 Update action VW FossilBook Timeline Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout 200 Events Checkins Only Older Tickets Only Wiki Only 20 most recent events Closed ticket ebf406842a Editorial corrections spelling etc plus 4 other changes user Marilyn d44769cc23 Leaf ebf40b842a Editorial corrections on text thus far user marilyn tags trunk New ticket ebf40b842a Editorial corrections spelling etc user Marilyn aad7dd10f3 Commit last change and updated PDF user jim tags trunk 158492516c Moved to clone repository user jim tags trunk 1a403c87fc Update before moving to server user jim tags trunk 11 03 fe5578c96f Correct site URL user jim tags trunk 10 52 fa5b9247bd Working on chapter 1 user jim tags trunk 11 16 Changes to wiki page tools user jim 11 15 51be6423a3 Update outline user jim tags trunk 11 08 2234149037027a Clean up Single user chapter and working initial chapter user jim tags trun
89. m 10 53 Changes to wiki page JASONP user jim 10 52 Changes to wiki page JASONP user jim 10 52 Changes to wiki page JASONP user jim 10 45 6edbaf5fa8 Fork Initial Checkin user jim tags trunk 10 44 b4bca2a0c5 initial empty check in user jim tags trunk Figure 4 4 Repository Fork Not good there are two 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 Updated for fossil version 1 25 Page 41 of 107 Fossil Version Control Fossil SCM 4 2 3 Fixing the fork So Jim who s checked out code is from Leaf 1beab85441 does a merge with Marilyn s leaf b72e96832e like so 556 jsonp gt fossil merge b72e96832e UPDATE docs qdj lyx UPDATE docs qdj pdf 557 jsonp gt fossil status repository Users jschimpf Public FOSSIL jsonp fossil local root Users jschimpf Public jsonp server code d3e7932b0b0f5e704264ba30adeael4978c08bc6 checkout lbeab955418a942ab9953c4865109ff46cbbd691 2010 06 08 10 44 56 UTC parent 6edbaf5faB8e1d061c2e04e7fd481e7663b090bd3 2010 06 07 10 45 57 UTC tags trunk UPDATED_BY_MERGE docs qdj lyx UPDATED_BY_MERGE docs qdj pdf MERGED_WITH b72e96832e024 f235696dcd6c5d0ddcc2cb38238 Figure 4 5 Merge Operation As shown the two documentation files are updated there are no merge conflicts as Jim
90. m fossil add Images Single_user ADDED mages Single_user config_initial epsf ADDED mages Single_user initial_page epsf ADDED mages Single_user jim_setup epsf ADDED mages Single_user ticket_form epsf ADDED mages Single_user ticket_initial epsf ADDED mages Single_user ticket_list epsf ADDED mages Single_user ticket_submit epsf ADDED mages Single_user timeline epsf ADDED mages Single_user timeline_detail epsf ADDED mages Single_user user_config epsf Pandora 2 jschimpf Public FossilBook jim fossil commit m 1665c78d94 Ticket Use Figure 2 18 Ticket resolving check in 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 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 2 17 on the preceding page From there I pick edit and fill it in as shown Upda
91. ments and run those scripts zero or more times depending on the other arguments For example the if command executes either the then script or the else script once depending on the if expression being true or false The command that takes a script will perform the normal grouping and substitution as part of executing the script Updated for fossil version 1 25 Page 90 of 107 Viv A Fossil Version Control Fossil SCM Note that the script always needs to be enclosed in curly brackets to prevent substitu tion taking place twice once as part of the execution of the top level command and once again when preparing the script Forgetting to enclose a script argument in curly brackets is common source of errors A few commands return error break and continue immediately stop execution of the current script instead of passing control to the next command in the list Control is instead returned to the command that initiated the execution of the current script 6 6 3 Command result codes Each command produces two results a result code and a string The code indicates whether the command completed successfully or not and the string gives additional information The valid codes are defined in th h and are Name Value Meaning TH_OK 0 This is the normal return code The string gives the command s return value TH_ERROR 1 Indicates that an error occurred the string gives a message describing the error
92. mmand invocations However several built in commands see one of more of their arguments as expressions and request the interpreter to calculate the value of such expressions The expr command is the simplest such command and is used to parse and evaluate expressions puts expr 7 4 2 gt 3 7 Note that an expression can contain white space but if it does it must be grouped in order to be recognized as a single argument Within the context of expression evaluation TH works with three datatypes two types of number integer and floating point and string Integer values are promoted to floating point values as needed The Boolean values True and False are represented by the integer values 1 and O respectively The implementation of expr is careful to preserve accurate numeric values and avoid unnecessary con versions between numbers and strings Before expression evaluation takes place both variable and command substitution is performed on the expression string Hence you can include variable references and nested commands in math expressions even if the expression string was originally quoted with curly brackets Note that backslash escape substitution is not performed by the expression evaluator A TH expression consists of a combination of operands operators and parentheses White space may be used between the operands and operators and parentheses it is ignored by the expression processor Where possible operands are interpreted as
93. mmand is actually a modifier and when used before certain commands will run them on all the repositories Pandora 2 jschimpf Public FossilBook jim fossil help all Usage fossil all list ls pull push rebuild sync The fossil file records the location of all repositories for a user This command performs certain operations on all repositories that can be useful before or after a period of disconnection operation Available operations are list Display the location of all repositories ls An alias for list pull Run a pull operation on all repositories push Run a push on all repositories rebuild Rebuild on all repositories sync Run a sync on all repositories Repositories are automatically added to the set of known repositories when one of the following commands against the repository clone info pull push or sync Figure 5 24 all details 5 3 8 push This command will push changes in the local repository to the master or remote repository Pandora 2 jschimpf Public FossilBook jim fossil help push Usage fossil push URL options Push changes in the local repository over into a remote repository Use the R REPO or repository REPO command line options to specify an alternative repository file If the URL is not specified then the URL from the most recent clone push pull remote url or sync command is used The URL specified normally becomes the new remote url used for subsequent push pull a
94. mmand returns 1 if the variable named varname exists in the current scope either the global scope or the current local scope and returns 0 otherwise 6 5 1 1 Scalar variables and array variables TH supports two types of variables scalars and arrays A scalar variable has a single value whereas an array variable can have any number of elements each with a name called its index and a value TH arrays are one dimensional associative arrays i e the index can be any single string Updated for fossil version 1 25 Page 88 of 107 Viv A Fossil Version Control Fossil SCM If varname contains an open parenthesis and ends with a close parenthesis then it refers to an array element the characters before the open parenthesis are the name of the array and the characters be tween the parentheses are the index within the array Otherwise varname refers to a scalar variable For example the command set x first 44 will modify the element of x whose index is first so that its new value is 44 Two dimensional arrays can be simulated in TH by using indices that contain multiple concatenated values For example the commands set a 2 3 1 set a 3 6 2 set the elements of a whose indices are 2 3 and 3 6 In general array elements may be used anywhere in TH that scalar variables may be used If an array is defined with a particular name then there may not be a scalar variable with the same name Similarly if there is a sc
95. 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 Pandora 2 jschimpf Public FossilBook jim fossil ui port 8081 Figure 2 5 Starting Webserver 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 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 W eae Home Unnamed Fossil Project Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout This is a stub home page for the project To fill in this page first go to setup confia and establish a Project Name Then create a wiki page with that name The content of that wiki page will be displayed in place of this message Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 6 Initial webserver page Following the advice on the page I go to 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 Updated for fossil version 1 25 P
96. n However there must be enough actual arguments for all the formal arguments that don t have defaults and there must not be any extra actual arguments There is one special case to permit procedures with variable numbers of arguments If the last formal argument has the name args then a call to the procedure may contain more actual arguments than the procedure has formals In this case all of the actual arguments starting at the one that would be assigned to args are combined into a list as if the list command had been used this combined value is assigned to the local variable args When body is being executed variable names normally refer to local variables which are created automatically when referenced and deleted when the procedure returns One local variable is auto matically created for each of the procedure s arguments Global variables can be accessed by using the syntax When a procedure is invoked the procedure s return value is the value specified in a return com mand If the procedure doesn t execute an explicit return then its return value is the value of the last command executed in the procedure s body If an error occurs while executing the procedure body then the procedure as a whole will return that same error The syntax for the return command is return code code value The optional argument pair code code allows to change the return status code from the default of TH_OK to another status code
97. n commands that the interpreter uses to parse a line These commands include for set puts and so on They are however still just regular TH commands that obey the same syntax rules as all TH commands both built in and those that you create yourself with the proc command 6 6 1 Commands revisited Like Tcl TH is build up around commands A command does something for you like outputting a string computing a math expression or generating HTML to display a widget on the screen Commands are a special form of list The basic syntax for a TH command is command argl arg2 arg3 The command is either the name of a built in command or a TH procedure White space is used to separate the command name and its arguments and a newline character or semicolon is used to terminate a command TH comments are lines with a character at the beginning of the line or with a character after the semicolon terminating a command 6 6 2 Scripts Normally control in TH flows from one command to the next The next command is either in the same list if the current command is terminated with a semicolon or in the next input line A TH program is thus a TH list of commands Such a list of commands is referred to as a script A script is hence a self contained code fragment containing one or more commands The commands in a script are analogous to statements in other programming languages Some commands take one or more scripts as argu
98. n 1 25 Page 59 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help gdiff Usage fossil diff gdiff options FILE Show the difference between the current version of FILE as it xists on disk and that same file as it was checked out Or f the FILE argument is omitted show the unsaved changed currently the working check out f the from VERSION or r VERSION option is used it specifies he source check in for the diff operation If not specified the ource check in is the base check in for the current check out f the to VERSION option appears it specifies the check in from hich the second version of the file or files is taken If there is o to option then the possibly edited files in the current check out re used he i command line option forces the use of the internal diff logic ather than any external diff program that might be configured using he setting command If no external diff program is configured then he i option is a no op The i option converts gdiff into diff 5 ttk He DBD EHD tHE HO Figure 5 14 gdiff details 5 2 14 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
99. n processor was called As discussed below it is usually best to enclose expressions in curly brackets to prevent the command parser from performing substitutions on the contents The valid operators are listed below grouped in decreasing order of precedence Operators Action Unary plus unary minus bit wise NOT logical NOT None of these operands may be applied to string operands and bit wise NOT may be applied only to integers 1 Multiply divide remainder None of these operands may be applied to string operands and remainder may be applied only to integers Add and subtract Valid for numeric operands only lt lt gt gt Left and right shift Valid for integer operands only lt gt lt gt Boolean less greater less than or equal and greater than or equal Each operator produces 1 if the condition is true O otherwise These operators may be applied to strings as well as numeric operands in which case string comparison is used Boolean equal and not equal Each operator produces a zero one result as per above Valid for all operand types eq ne Compare two strings for equality eq or inequality ne These operators return 1 true or 0 false Using these operators ensures that the operands are regarded exclusively as strings not as possible numbers amp Bit wise AND Valid for integer operands only Bit wise XOR Valid for integer operands only l Bit wise OR Valid for integer operands o
100. nd images Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 16 Viewing a Ticket Finally picking Tickets then All Tickets I can see my new ticket in the list marked as Open and in a distinctive color KA FossiBock All Tickets Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Edit New Ticket Raw SQL Key Active Review Fixed Tested Deferred Closed 4 mime ype status subsystem He 7 1665c78d94 2010 04 27 Feature_Request Open Add in the Ticket operations to the edit 10 59 56 Single User chapter Fossil version c56af61e5e 2010 04 22 15 48 25 Logged in as jim Figure 2 17 Ticket List with open ticket 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 Updated for fossil version 1 25 Page 16 of 107 Viv e Fossil Version Control Fossil SCM 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 Pandora 2 jschimpf Public FossilBook ji
101. nd line The keep option leaves files on disk unchanged except the manifest and manifest uuid files The latest flag can be used in place of VERSION to checkout the latest version in the repository See also the update command Figure 5 11 checkout or co details Updated for fossil version 1 25 Page 58 of 107 TA Fossil Version Control Fossil SCM 5 2 11 undo This is used to undo the last update merge or revert operation Pandora 2 jschimpf Public FossilBook jim fossil help undo Usage fossil undo FILENAME Undo the most recent update or merge or revert operation If FILENAME is specified then restore the content of the named file s but otherwise leave the update or merge or revert in effect A single level of undo redo is supported The undo redo stack is cleared by the commit and checkout commands Figure 5 12 undo details It acts on a single file or files if specified otherwise if no file given it undoes all of the last changes 5 2 12 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 th
102. nd returns immediately from the current procedure or top level command with value as the return value and TH_ERROR as the result code If value is not specified the string error will be returned as result The catch command has the following syntax catch script varname The catch command may be used to prevent errors from aborting command interpretation The catch command calls the TH interpreter recursively to execute script and always returns a TH_OK code regardless of any errors that might occur while executing script The return value from catch is a decimal string giving the code returned by the TH interpreter after executing script This will be 0 TH_OK if there were no errors in command otherwise it will have a non zero value corresponding to one of the exceptional result codes If the varname argument is given then it gives the name of a variable catch sets the value of the variable to the string returned from running script either a result or an error message 6 6 5 Creating user defined commands The proc command creates a new command The syntax for the proc command is proc name args body The proc command creates a new TH command procedure name replacing any existing command there may have been by that name Whenever the new command is invoked the contents of body will be executed by the TH interpreter The parameter args specifies the formal arguments to the procedure It consists of a list possibly
103. nd sync operations However the once command line option makes the URL a one time use URL that is not saved See also clone pull sync remote url Figure 5 25 push details 5 3 9 pull This command will copy changes from the remote repository to the local repository You could then use update to apply these changes to checked out files Updated for fossil version 1 25 Page 65 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help pull Usage fossil pull URL options Pull changes from a remote repository into the local repository Use the R REPO or repository REPO command line options to specify an alternative repository file If the URL is not specified then the URL from the most recent clone push pull remote url or sync command is used The URL specified normally becomes the new remote url used for subsequent push pull and sync operations However the once command line option makes the URL a one time use URL that is not saved See also clone push sync remote url Figure 5 26 pull details 5 3 10 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
104. nly amp amp Logical AND Produces a 1 result if both operands are non zero 0 otherwise Valid for integer operands only Note there is no shortcut evaluation the right hand is evaluated even if the left hand evaluated to false I Logical OR Produces a 1 result if either operand is non zero 0 otherwise Valid for integer operands only Note there is no shortcut evaluation the right hand is evaluated even if the left hand evaluated to true gt All of the binary operators group left to right within the same precedence level For example the expression 4 2 lt 7 evaluates to 0 All internal computations involving integers are done with the C type int and all internal com putations involving floating point are done with the C type double Conversion among internal representations for integer floating point and string operands is done automatically as needed For Updated for fossil version 1 25 Page 87 of 107 Viv A Fossil Version Control Fossil SCM arithmetic computations integers are used until some floating point number is introduced after which floating point is used String values may be used as operands of the comparison operators although the expression eval uator tries to do comparisons as integer or floating point when it can If one of the operands of a comparison is a string and the other has a numeric value the numeric operand is converted back t
105. nter a detailed description of the problem For code defects be sure to provide details on exactly how the problem can be reproduced Provide as much detail as possible This part of the chapter will explain how to use the ticket system Close the ticket when we have added the text and images After filling in the information above press this button to create the new ticket Abandon and forget this ticket Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 15 Ticket Form 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 Updated for fossil version 1 25 Page 15 of 107 v Bg Fossil Version Control Fossil SCM Ww ce FocsilBook View Ticket ss Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Attach Check ins Edit History New Ticket Timeline Ticket UUID 1665 78d9434439e84cb76b8b41 1 48dac199e06f Title Add in the Ticket operations to the Single User chapter Status Open Type Feature_Request Severity Important Priority Subsystem Resolution Last Modified 2010 04 27 10 59 56 Contact jim schimpf gmail com Version Found In Description amp Comments This part of the chapter will explain how to use the ticket system Close the ticket when we have added the text a
106. o a string 6 5 TH variables Like almost all programming languages TH has the concept of variables TH variables bind a name to a string value A variable name must be unique in its scope either the global scope or a local scope TH supports two types of variables scalars and arrays TH allows the definition of variables and the use of their values either through style variable substitution the set command or a few other mechanisms Variables need not be declared a new variable will automatically be created each time a new variable name is used 6 5 1 Working with variables TH has two key commands for working with variables set and unset set varname value unset varname info exists varname The set command returns the value of variable varname If the variable does not exist then an error is thrown If the optional argument value is specified then the set command sets the value of varname to value creating a new variable in the current scope if one does not already exist and returns its value The unset command removes a variable from its scope The argument varname is a variable name If varname refers to an element of an array then that element is removed without affecting the rest of the array If varname consists of an array name with no parenthesized index then the entire array is deleted The unset command returns an empty string as result An error occurs if the variable doesn t exist The info exists co
107. o bt ti Ge hae So ee ee 59 5 2 SAME 3 5 2 2204 ande ind 59 LIA Misa e da as Bala ea 60 52 15 SEIVER aua mir aaa a a a 60 5 2 16 commitorci 2 e a a R a a a 61 Updated for fossil version 1 25 iv Fossil Version Control Fossil SCM 5 3 Maintenance commands nn nn 62 II 62 5 932 CONS a e ee ee ae er 62 53 3 E ee a eA ar doe 63 DIA Cloe aa uud ha as a ana Canes Backs 64 3 3395 VELSION u a 0 0 a a A ee ee OS 64 5 3 0 M DULA 4 4 00 ads na ee diia edb 64 DI Ten Alle nee II E a ie ae ee 65 53 8 PUSH ar ek eB a e a erde a 65 339 pull vaa ir BS aa Er Dina Dem 65 93 10 SMC ca Ga be ee MEE eae Le Rae wk ewe eS 66 Selen 2 4 ao dob aoe a we BE a hh oS 66 9 3 12 0 a cece u deca cea 00 0 a a a ea ee 67 3 3 13 MErge cr a ea ee ee ee A ra 67 Do 1A 1a a Ward Se an Bard a Pad Man ua 68 5 3 15 SEINES cs Kaas ken ie Re ae ee ae ee ek ee 69 9 4 Miscellaneous 20 2 2 4 4 44 bade ha bbe eke eh be ba ba bao dS 70 TAL Zi a ea aa dad edie ds 71 A A 71 DAS MPO Werd a aka ed ea ava ae ae de ae doe Paes ae es 71 9 44 Timeline 4 aed a ake A a Ro ok a ae A 72 SAS Wikis 25 6458 dood bao eh ae ee Ewe a a ee ae i 73 55 Advanced 2 au auch wa Be a we a a ad ak es a 74 A A ee ee A A ee ee ed 74 939 2 SEAICH ANA 75 5 3 3 A ia Bee ee ie BA ate ek ee a eo ee Bc ee 75 DA ISTAIS Saar a ae ee a aoe ae ee ee 76 5 3 5 configuration 2 sa nn 76 59 2 6 descendants 2 00 a a Le 77 6 Fossil Customization
108. oceeds from left to right and is performed only once if a substitution leads to a string which could again be substituted such this not happen 6 3 4 3 Backslash escape substitution In general the backslash disables substitution for the single character immediately following the backslash Any character immediately following the backslash will stand as literal This is useful to escape the special meaning of the characters and There are two specific strings which are replaced by specific values during the substitution phase A backslash followed by the letter n gets replaced by the newline character as in C A backslash followed by the letter x and two hexadecimal digits gets replaced by the character with that value Le writing x20 is the same as writing a space Note that the x substitution does not keep going as long as it has hex digits as in Tcl but insists on two digits The word x2121 is not a single exclamation mark but the 3 letter word 21 6 3 4 4 Variable substitution Like any programming language TH has a concept of variables TH variables are named containers that hold string values Variables are discussed in more detail later in this document for now we limit ourselves to variable substitution The dollar sign may be used as a special shorthand form for substituting variable values If appears in an argument that isn t enclosed in curly brackets then variable substitution w
109. ontrol This is important because if you move your working directory or others attempt to use the repository they won t have these files Pandora 2 jschimpf Public FossilBook jim fossil help extra Usage fossil extras dotfiles ignore GLOBPATTERN Print a list of all files in the source tree that are not part of the current checkout See also the clean command Files and subdirectories whose names begin with are normally ignored but can be included by adding the dotfiles option Figure 5 8 extra details The dotfiles option shows you any files starting with that are not under Fossil control This would be important if you need those files in your repository The last option ignore allows you to ignore certain files you know don t belong in the repository In my case there is a file called fossilbook lyx that is a LyX backup file that I do not want as it is temporary So I can say Updated for fossil version 1 25 Page 56 of 107 Fossil Version Control Fossil SCM fossil extra ignore x lyx and only get Pandora 2 jschimpf Public FossilBook jim fossil extra ignore lyx Images Commands helpl epsf instead of Pandora 2 jschimpf Public FossilBook jim fossil extra Images Commands helpl epsf fossilbook lyx 5 2 8 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
110. ossil update trunk fossilbook pdf Autosync http jim pandora dyn o saur com 8080 cgi bin Book cgi Bytes Cards Artifacts Deltas Send 130 l 0 0 Received 4002 87 0 0 Total network traffic 334 bytes sent 2412 bytes received UPDATE fossilbook pdf Pandora 2 jschimpf Public FossilBook jim Figure 3 15 Update fossilbook pdf and it s done Updated for fossil version 1 25 Page 35 of 107 g Fossil Version Control Fossil SCM 3 4 5 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 E Profile Ratte data organize fossil w32 fossil book gt fossil commit m adding some changes of jim fossil would fork 0 update first or use f or force E Profile Ratte data organize fossil w32 fossil book gt fossil commit f m adding some other changes of New_Version df9f2ff6b14ef65a9dd2162f8bd20c78e1628165 Figure 3 16 Forcing a commit under Windows Now the timeline looks like History of fossilbook lyx 2010 06 01 T3 197c95ee3d part of check in df9f2ff6b1 adding some other changes of jim user Ratte branch trunk diff annotate 17 35 f8fc742ce8 part of check in f10f68d7 17 adding some changes of jim user Ratte branch trunk diff annotate 17 23 cf12774943 part of check in a91582b699 simulating marilyn s commit user Ratte branch trunk diff annotate
111. oth branches and then check both in Now the timeline looks like this Updated for fossil version 1 25 Page 50 of 107 Fossil Version Control Fossil SCM Pandora 2 jschimpf Public jsonpl jim fossil commit m 2795e6c74d Fix unused variable Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 130 al 0 0 Received 2116 46 0 0 Send 365 6 0 0 Received 3601 51 5 0 Total network traffic 805 bytes sent 3464 bytes received New_Version 3b902585d0e8849399286139d27676c5a349de7b Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 3034 50 0 2 Received 2208 48 0 0 Total network traffic 1848 bytes sent 1444 bytes received Pandora 2 jschimpf Public jsonpl jim cd Pandora 2 Users jschimpf Public jim cd jsonp2 Pandora 2 jschimpf Public jsonp2 jim cp jsonpl main c Pandora 2 jschimpf Public jsonp2 jim fossil status repository Users jschimpf Public FOSSIL jsonp fossil local root Users jschimpf Public jsonp2 server code 90c80fla2da7360dae230ccec65ff82fe2eb160d checkout al737916ec2df696a0 f3a7e36edf9ba4370e48a7 2010 06 13 10 14 26 UTC parent 462156b283b694af0b99c9b446b64d3f77436fbb 2010 06 09 14 16 42 UTC tags VER_2 0 EDITED main c Pandora 2 jschimpf Public jsonp2 jim fossil commit m 2795e6c74d Fix unused variable Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi B
112. ours 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 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 Finally if you wish to contribute to the project there are many things to do See the To Do List in the Wiki 99 List of Figures 2 1 Create Repository cox 6 eX Ah a ew ad Ga a ae E sa al a 2 2 Open Repository amp Check o onen 2 3 Initial file add 2 4 eo Pes a thea cd eo Ge God aha how Ga os A ii 2 4 Initial Comites ee ed 2 5 Starting Webserver wi su Rede 2 6 Initial webserver page ua en era ae a a a a eed 2 7 Initial Configuration 8 040 22a aueh A Ek a Bk DA 2 8 User Configuration o sos 2 Comm none 2 9 Super User Setup 2 ac ner ne Be OP a eB gel 2 10 Pr jeet Status 3 2m o RA amp el Ge od daw bo eae Aa ar BA 2 11 pdate fornew esti s ar ae eee ee aoe AER ars 2 12 Timeline y r aa a aes en en eee a es 213 Timeline Detail e 2 cy 2 52 des amas ae Ba we le ede e 2 14 Initial Ticket Window 2 oo oo 2 15 Ticket Formi se i o ea Pk ie Sees Gece Pe
113. out 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 4 3 1 Check in attempt Marilyn finished first and checks in her changes Jim builds tests and tries to check in his code and gets 502 jsonp gt make usr bin gcc main c c I Ijson src o obj main o usr bin gcec obj main o obj qdj oN obj qdj_util o obj qdj_token o 0o jsonp 503 jsonp gt jsonp v JSON Test Program Ver Jun 9 2010 10 15 00 SYNTAX jsonp i lt json text file gt v i lt json text file gt Show parse of JSON y Show help 506 jsonp gt fossil commit m fed383fala Add help to cmd line Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 130 1 0 0 Received 1656 36 0 0 Send 647 12 0 0 Received 14039 47 4 7 Total network traffic 942 bytes sent 4537 bytes received fossil would fork update first or us f or force Figure 4 9 Jim s check in attempt 4 3 2 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 Updated for fossil version 1 25 Page 44 of 107 M 27 Fossil Version Control Fossil SCM 507 jsonp gt fossil update n PDATE json src
114. ping Instead a nested command is considered part of the current group In the command below the double quotes group the last argument and the nested command is just part of that group puts The length of s is string length s If an argument is made up of only a nested command you do not need to group it with double quotes because the TH parser treats the whole nested command as part of the group A nested command is treated as an unbroken sequence of characters regardless of its internal structure It is included with the surrounding group of characters when collecting arguments for the main command 6 3 5 Summary The following rules summarize the fundamental mechanisms of grouping and substitution that are performed by the TH interpreter before it invokes a command e Command arguments are separated by white space unless arguments are grouped with curly brackets or double quotes as described below Grouping with curly brackets prevents substitutions Curly brackets nest The interpreter includes all characters between the matching left and right brace in the group including new lines semicolons and nested curly brackets The enclosing i e outermost curly brackets are not included in the group s value nn Grouping with double quotes allows substitutions The interpreter groups everything until another double quote is found including newlines and semicolons The enclosing quotes are not included in the gro
115. qdj c PDATE json src qdj h PDATE json src qdj_token c P P GG G JPDATE json src qdj_token h U DATE json src qdj_util c MERGE main c U Figure 4 10 Update dry run This shows some files will be updated i e be replaced by new text from the repository The main c file will be merged with the version from the repository That is text from the repository will be mixed with the text from Jim s modified file Note that it says MERGE meaning the two sets of text are a disjoint set This means the merge can all be done by Fossil with no human intervention Jim can just do the update for real then commit the merged files to make a new leaf So now we have Marilyn s and Jim changes combined in the lastest version de sonp Timeline Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Lo 200 Events Checkins Only Tickets Only Wiki Only 17 most recent events 2010 06 09 A 14 18 Tested ticket fed383fa1a Add help to MAIN plus 4 other changes user jim 14 16 462156b283 Leaf fed383fa1a Add help to cmd line user jim tags trunk 14 08 New ticket fed383fa1a Add help to MAIN user jim 14 05 Closed ticket 7642140264 Add BSD license to code plus 2 other changes user Marilyn 1 similar event omitted 14 02 fob16491e2 7642440264 Add BSD license to code user Marilyn tags trunk 13 57 New ticket 7542140264 Add BSD license to code user Marilyn Figure 4 11 Merged repository
116. r fossil del FILE Remove one or more files from the tree This command does not remove the files from disk It just marks the files as no longer being part of the project In other words future changes to the named files will not be versioned Figure 5 4 rm detail 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 fossil rm com_ c By running a fossil status you can see what files will be deleted on the next commit 5 2 4 rename or 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 Pandora 2 jschimpf Public FossilBook jim fossil help rename Usage fossil mv rename OLDNAME NEWNAME or fossil mv rename OLDNAME DIR Move or rename one or more files within the tree This command does not rename the files on disk All this command does is record the fact that filenames have changed so that appropriate notations can be made at the next commit checkin Figure 5 5 rename detail 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 5 2 5 status The status command is used to show you the current state of your files relative to the repository It will show you files ad
117. re 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 1 3 4 Common Terms The following is a list of terms I will use when talking about version control or Fossil Repository This is the store when the version controlled files are kept It will be managed by a source control system Updated for fossil version 1 25 Page 3 of 107 viv A Fossil Version Control Fossil SCM 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 Commit In Fossil to store the current set of new and changed files into the repository
118. recursively filenames that begin with are excluded by default To include such files add the dotfiles option to the command line Figure 5 2 Help detail 5 2 2 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 Pandora 2 jschimpf Public FossilBook jim fossil help add Usage fossil add FILE Make arrangements to add one or more files to the current checkout at the next commit When adding files recursively filenames that begin with are excluded by default To include such files add the dotfiles option to the command line Figure 5 3 add detail Typing fossil add 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 5 2 3 rm or 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 Updated for fossil version 1 25 Page 54 of 107 g amp Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help rm Usage fossil rm FILE o
119. s Adding multiuser chapter 1 May 2010 0 5 mn Adding editorial corrections ebf40b842a 4 May 2010 0 6 js Adding Command sections e11399d575 8 May 2010 0 7 js English amp spelling corrections 19 May 2010 0 8 js Spelling fixes 30 May 2010 0 9 ws Using Fossil merge db6c734300 2 Jun 2010 1 0 js ws Put Fossil merge first in handling fork 3 Jun 2010 1 1 mn Fixes in multiple user chapter e8770d3172 4 Jun 2010 1 2 js Start advanced use chapter 2abc23dae5 4 Jun 2010 1 3 mn English corrections Chapter 1 8b324dc900 5 Jun 2010 1 4 mn Sections 2 1 amp 2 2 corrections 0b34cb6f04 7 Jun 2010 1 5 js Move close leaf to adv use 2abc23dae5 7 Jun 2010 1 6 js Convert Advanced chapter to forks and branching 13 Jun 2010 1 7 js tr Add note about IP port usage a62efa8eba 8 Jul 2010 1 71 javelin Check on mispelling section 1 1 637d974f62 15 Sep 2011 1 72 anon Fix absolute path in image regs d54868853b 15 Sep 2011 1 73 anon Fix fossil create section 2 2 5 36772d90a5 15 Sep 2011 1 74 anon Push Pull described incorrectly 1b930fced6 15 Sep 2011 1 75 arnel Commands might be changed 4aaf1f78bb 15 Sep 2011 2 0 FvD Updated and matched to fossil 1 25 March 2013 107
120. s to attributes of check in 6581148633 User im Comment create new branch named VER_1 0 Check in Time 2010 06 13 10 13 5 Background Color M Propagate color to descendants O none O f2dcdc O OffcO O bde5d6 O cOffcd O cOfffO O c0foff O dOcOff ffcOff O ffcOdd O fffOcO O cOc0cd Tags O Add the following new tag name to this check in Cancel tag VER_1 0 O Cancel special tag bgcolor O Cancel special tag branch O Cancel special tag date Figure 4 15 Setting Timeline color Under the Background Color section I have checked Propagate color to descendants so future checkins will have the same color Updated for fossil version 1 25 Page 48 of 107 Fossil Version Control Fossil SCM 4 4 4 Check out the branches Now the the repository is branched we can check out the two sets of code into different directories We create jsonpl and jsonp2 and proceed to open the different branches into them Pandora 2 jschimpf Public jsonpl jim fossil open FOSSIL jsonp fossil VER_1 0 docs qdj lyx docs qdj pdf json sre qdj c json src qdj h json sre qdj_token c json sre qdj_token h json sre qdj_util c main c makefile obj test txt test txt project name JASONP repository Users jschimpf Public FOSSIL jsonp fossil local root Users jschimpf Public jsonpl project code eb6084c8ab115cf2b28a129c7183731002c6143a server code 90c80fla2da7360dae230ccec65ff82fe2eb160d checkout 65e1f48633
121. s used to search the timeline entries for a pattern This can also be done in your browser on the timeline page Pandora 2 jschimpf Public FossilBook jim fossil help search COMMAND search fossil search pattern Search for timeline entries matching the pattern Figure 5 39 search detail 5 5 3 shalsum This can compute the shal value for a particular file These sums are the labels that Fossil uses on all objects and should be unique for any file Pandora 2 jschimpf Public FossilBook jim fossil help shalsum COMMAND shalsum fossil shalsum FILE Compute an SHAl checksum of all files named on the command line If an file is named then take its content from standard input Figure 5 40 shalsum detail Updated for fossil version 1 25 Page 75 of 107 Fossil Version Control Fossil SCM 5 5 4 rstats Pandora 2 jschimpf Public FossilBook jim fossil help rstats Usage fossil rstats Deliver a report of the repository statistics for the current checkout Figure 5 41 rstats detail For example running it on the Fossil Book checkout Pandora 2 3jschimpf Public FossilBook jim fossil rstats Number of Artifacts 137 59 full text 78 delta blobs 218961 bytes average 38217738 bytes total Number Of Checkins 26 Number Of Files 37 Number Of Wiki Pages 2 Number Of Tickets 6 Duration Of Project 23 days 5 5 5 configuration This command allows you to save or load a custom
122. sil 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 1 1 on page 1 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 1 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 http www fossil scm org index html doc tip www branching wiki 4 2 Forks Branch amp 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 3 on page 25 The JSON code has been placed in a distributed location each of them clones the repository and opens a working copy of the code 4 2 1 Marilyn s Actions She loo
123. sion Control Fossil SCM The string compare subcommand performs a character by character comparison of argument strings string and string2 in the same way as the C stremp procedure It returns a decimal string with value 1 0 or 1 depending on whether string is lexicographically less than equal to or greater than string2 The string first subcommand searches argument haystack for a sequence of characters that exactly match the characters in argument needle If found it returns a decimal string with the index of the first character in the first such match within haystack If not found it returns return 1 The optional integer argument startindex specifies the position where the search begins the default value is 0 i e the first character in haystack The string last subcommand searches argument haystack for a sequence of characters that exactly match the characters in argument needle If found it returns a decimal string with the index of the first character in the last such match within haystack If not found it returns return 1 The optional integer argument startindex specifies the position where the search begins the default value is 0 i e the first character in haystack The string range subcommand returns a range of consecutive characters from argument string starting with the character whose index is first and ending with the character whose index is last An index of zero refers to the first character of the string last m
124. sitory uses the same commands and is very much like single user use discussed in Section on page Fossil will synchronize your local repository with the one on the server 3 4 1 Cloning To clone a Fossil repository you have to know four things 1 It s web address for our repository it is http pandora dyn o saur com 8080 cgi bin Book cgi 2 Your account name in my case it s jim 3 Your password which I m keeping to myself thank you 4 The local name of the repository in this case I m calling it Fossilbook fossil You then go to where you want to keep the Repository in my case the FOSSIL directory and use the clone command Pandora 2 jschimpf Public FOSSIL fossil clone http jim lt passwd gt pandora dyn o saur com 8080 cgi bin Book cgi FossilBook fossil NOTE lt passwd gt Stands in for real password Bytes Cards Artifacts Deltas Send 49 1 0 0 Received 120 2 0 0 Send 625 25 0 0 Received 4704 72 0 0 Send 3104 72 0 0 Received 5129052 131 10 5 Send 2399 51 0 0 Received 4381170 116 22 28 Total network traffic 4117 bytes sent 6913068 bytes received Rebuilding repository meta data 65 100 project id 2b0d35831c1a5b315d474c4fd8d532b100b822ad7 server id 3e67da6d6212494456c69b1c5406a277d7e50430 admin user jim password is d07222 Pandora 2 jschimpf Public FOSSIL jim Figure 3 7 Clone command At this point I can go through the steps outlined in Section on page to set my user
125. 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 Pandora 2 jschimpf Public FossilBook jim fossil add ADDED Layout fossil png ADDED Research History CVS grune pdf ADDED Research History RCS A System for Version Control webloc ADDED Research History SCCS Slideshow pdf ADDED Research History VCSHistory pysync webloc ADDED Research fossilbib bib fossil cannot add _FOSSIL_ ADDED fossilbook lyx ADDED outline txt Figure 2 3 Initial file add I simply told fossil to do an add of the current directory so it got all those files and all the files in the subdirectory Note the _FOSSIL_ that it didn t add This is the tag file that fossil keeps in a directory so it knows what repository it belongs to Fossil won t add this file since it manages it but everything else is fair game One final thing before I can quit for the day these files have been added or rather they will be added to the repository when I commit it That must be done and then we can relax and let Fossil manage things Pandora 2 jschimpf Public FossilBook jim fossil commit m Initial Commit New_Version 8fa070818679e1744374bc530
126. sr lt a Fossil SCM Fossil Version Control A Users Guide Jim Schimpf 2010 Pandora Products Document number PAN 20100424 This work is licensed under the Creative Commons Attribution Share Alike 3 0 United States Li cense To view a copy of this license visit http creativecommons org licenses by sa 3 0 us or send a letter to Creative Commons 171 Second Street Suite 300 San Fran cisco California 94105 USA Pandora Products 215 Uschak Road Derry PA 15627 United States of America Phone 724 539 1276 Fax 724 539 1276 Web http www fossil scm org schimpf book index Email jim schimpf gmail com This version Revision Number 2 0 Date November 29 2012 Contents 1 Source Control amp Why you need it 1 1 1 Whatis Source Control 2 oo on 1 1 2 Why version the files in your project oo o 0000 2 12 1 How t setit m esme 2 28 w ale ee BR Soe ak ee a DS 2 1 3 Source control description ooa 2 1 3 1 Check utsystems 2 0 2 a2 era an atk aria aed 2 1 3 2 Merge Systems s iani nr gar a Bea are armani ale aE eels 3 1 3 3 Distributed systems 2 Coon 3 1 34 Common Terms 2 0 0 deh tude ash ut war are 3 2 Single Users 5 2 1 gt 1htroducti6n 4 3 A AE Bra an an 5 2 2 Creating a repository 5 2 2 14 Introduction dir BAS ee rar 5 22 2 Create REPOSitOry se tof xfs A a ee rs Pe Panne ane 6 2 2 3 Connect Repository 22 2 Cm ne 6 2 2 4 Add
127. t a single quote is not a special character in TH To use one of these characters to start a word it must be escaped which is discussed further later on Updated for fossil version 1 25 Page 80 of 107 Vv A Fossil Version Control Fossil SCM TH offers several built in commands for working with lists such as counting the number of words in a list retrieving individual words from the list by index and appending new items to a list These commands are discussed in the section Working with lists 6 3 3 Commands TH casts everything into the mold of a command even programming constructs like variable as signment and procedure definition TH adds a tiny amount of syntax needed to properly invoke commands and then it leaves all the hard work up to the command implementation Commands are a special form of list The basic syntax for a TH command is command argl arg2 arg3 The command is either the name of a built in command or a TH procedure White space is used to separate the command name and its arguments and a newline character or semicolon is used to terminate a command TH comments are lines with a character at the beginning of the line or with a character after the semicolon terminating a command 6 3 4 Grouping amp substitution TH does not interpret the arguments to the commands except to perform grouping which allows multiple words in one argument and substitution which is used to deal wit
128. tag or property to CHECK IN The tag will be usable instead of a CHECK IN in commands such as update and merge If the propagate flag is present the tag value propagates to all descendants of CHECK IN fossil tag cancel raw TAGNAME CHECK IN Remove the tag TAGNAME from CHECK IN and also remove the propagation of the tag to any descendants fossil tag find raw TAGNAME List all check ins that use TAGNAME fossil tag list raw CHECK IN List all tags or if CHECK IN is supplied list all tags and their values for CHECK IN The option raw allows the manipulation of all types of tags used for various internal purposes in fossil It also shows cancel tags for the find and list subcommands You should not use this option to make changes unless you are sure what you are doing If you need to use a tagname that might be confused with a hexadecimal baseline or artifact ID you can explicitly disambiguate it by prefixing it with tag For instance fossil update decaf will be taken as an artifact or baseline ID and fossil will probably complain that no such revision was found However fossil update tag decaf will assume that decaf is a tag branch name Figure 5 31 tag details 5 3 15 settings This command is used to set or unset a number of properties for fossil Updated for fossil version 1 25 Page 69 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help settings
129. ted for fossil version 1 25 Page 17 of 107 M A Fossil Version Control Fossil SCM gt Edit Ticket FossilBook Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Title Add in the Ticket Operations to the Single User chapter Status Type Severity Priority Resolution tll Subsystem Contact jim schimpf gmail com Version Found In 39bc728527 Append Remark from jim Added the new images and finished the section See 39bc728527 Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 2 19 Ticket Finish 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 2 18 on the preceding page By doing this my ticket is now cross linked with the commit and the commit has a link back to the ticket 2 5 1 Ticket Summary e Tickets are a useful way of reminding you what needs done or bugs fixed e 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 lt 10 digit hash gt so you can link to the ticket Updated for fossil version 1 25 Page 18 of 107 Wo wy Fossil Version Control Fossil SCM e When you close the ticket put in the hash label of the commit that fixed it 2 6 Wiki Use As we saw in
130. the next curly bracket Array references are not possible in this form the name between curly brackets is assumed to refer to a scalar variable For example if variable foo has the value test then the command set a abcS foo bar is equivalent to the command set a abctestbar A dollar sign followed by something other than a letter digit underscore or left parenthesis is treated as a literal dollar sign The following prints a single character puts x 6 3 4 5 Command Substitution The last form of substitution is command substitution A nested command is delimited by square brackets The TH interpreter takes everything between the brackets and evaluates it as a com mand It rewrites the outer command by replacing the square brackets and everything between them with the result of the nested command Example puts string length foobar gt 6 In the example the nested command is string length foobar This command returns the length of the string foobar The nested command runs first Then command substitution causes the outer command to be rewritten as if it were puts 6 If there are several cases of command substitution within a single command the interpreter pro cesses them from left to right As each right bracket is encountered the command it delimits is evaluated This results in a sensible ordering in which nested commands are evaluated first so that their result can be used in arguments to the outer
131. tion detail 5 5 6 descendants This is used to find where the checked out files are in the time line Pandora 2 jschimpf Public FossilBook jim fossil help descendants Usage fossil descendants BASELINE ID Find all leaf descendants of the baseline specified or if the argument is omitted of the baseline currently checked out Figure 5 43 descendants detail Updated for fossil version 1 25 Page 77 of 107 6 Fossil Customization the TH Scripting language 6 1 Introduction to TH 6 1 1 TH is a Tcl like language TH is a string based command language closely based on the Tcl language The language has only a few fundamental constructs and relatively little syntax which is meant to be simple TH is designed to be the scripting language of the Fossil source code management system TH is an interpreted language and it is parsed compiled and executed when the script runs In Fossil TH scripts are typically run to build web pages often in response to web form submissions The basic mechanisms of TH are all related to strings and string substitutions The TH Tcl way of doing things is a little different from some other programming languages with which you may already be familiar so it is worth making sure you understand the basic concepts 6 2 The Hello world program The traditional starting place for a language introduction is the classic Hello World program In TH this program has only a single line puts
132. tories 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 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 If you work on only one document it is conceivable that you saved a copy under a different name perhaps with a date that you could go back to But if you did not you doubtlessly feel helpless at your inability to 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 or the code from one hour ago or from last month After you have don this 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 manage ment and much much more It runs on multiple OS s and is free and open source software FOSS 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 1 2 1 How to get it If this has interested you then you can get a copy of the Fossil exe
133. tra details u eR na ea er 56 3 9 revert details ionn gad 24 ee BR ER Pe ea es ea 57 3 10 update details ca goog bo pa ka a Sa da a ea 58 5 11 checkout or co details as etsea ee 58 S12 undo details se a e ae rca ee A ee a ee ee 59 3 13 diff detalls shirt is ed bai Sean ea ee hh a ed bd 59 5 14 gditf details o ia ah ED aa wee a ne a da 60 3 15 ULOStalS us ua as a8 82 0 8 eat ea Ba a ee a 60 3 16 server detail u eas wet ep ara a re as are 61 Updated for fossil version 1 25 Page 102 of 107 Fossil Version Control Fossil SCM 5 17 commit details 22 ee 61 5 183 mew d tails Gor sost a una una Eee ea a eae 62 5 19 clone det lls si ai id Gok Rb we Bede ee So PA ce 63 3 20 open details u zu 20 wu aa 0a ara a a a a 63 5 21 close details lt s uoa a Co oo onen 64 5 22 version details 2 22 CC Con nenn 64 5 23 rebuild details 2 222 Co oo oo nenn 64 5 24 all details a 22 0 I ee nn 65 9 25 push details u a ae 2 han ee a a a a E 65 326 pull details uni ea a0 eee OE a Ee 66 9 27 8yne detalls s 2 ee a a ee a ae 66 5 28 clean details 2 22 Co oo non 67 5 29 branch details 2 2 2 Co oo on nn 67 3 30 Merge detallS 2 06244 salia ras de au ara wee ee eS aes 68 3 31 tag details s lt pos 2 Kondome wer an ee a nn ea ne A 69 5 32s Settings details so eee ee Dr ame HR ieh ee Ee a 70 5 33 21p detall 24 52 2 4 eo a en wies anne let 71 9 34 user detail uva Kun a san nad we we A we
134. trings are discussed in more detail below 6 3 2 Lists A list in TH is an ordered sequence of items or words separated by white space In TH the following characters constitute white space logo FossilBook Artifact Content Logged in as frans Home Timeline Files Branches Tags Tickets Wiki Admin Logout Download Hex Shun Artifact 7 03c1c83fcd092b090ada102ed76356e9496f 2d File fossilbook lyx 2010 06 26 12 28 12 part of checkin 9ad19c40d6 on branch trunk Added section on TH scripting b832f46d31 user jim annotate logo FossilBook Artifact Content Logged in as frans Home Timeline Files Branches Tags Tickets Wiki Admin Logout Download Hex Shun Artifact 7b03c1c83 fcd092b0 90adal02ed76356e9496f2dA File fossilbook lyx 2010 06 26 12 28 12 part of checkin 9ad19c40d6 on branch trunk Added section on TH scripting b832f46d31 user jim annotate a 0x20 Pt 0x09 ran 0x0A EN 0x0B INE 0x0C Nr 0x0D Ls A word can be any sequence of characters delimited by white space It is not necessary that a word is alphanumeric at all is a valid word in TH If a word needs to contain embedded white space characters it needs to be quoted with either a double quotes or with opening closing curly brackets Quoting has the effect of grouping the quoted content into a single list element Words cannot start with one of the TH special characters 1 and Note tha
135. up of characters A double quote character can be included in the group by quoting it with a backslash i e Updated for fossil version 1 25 Page 84 of 107 Viv A Fossil Version Control Fossil SCM e Grouping decisions are made before substitutions are performed which means that the values of variables or command results do not affect grouping e A dollar sign causes variable substitution Variable names can be any length and case is significant If variable references are embedded into other strings or if they include characters other than letters digits and the underscore they can be distinguished with the varname syntax e Square brackets cause command substitution Everything between the brackets is treated as a command and everything including the brackets is replaced with the result of the com mand Nesting is allowed e The backslash character is used to quote special characters You can think of this as another form of substitution in which the backslash and the next character or group of characters is replaced with a new character e Substitutions can occur anywhere unless prevented by curly bracket grouping Part of a group can be a constant string and other parts of it can be the result of substitutions Even the command name can be affected by substitutions e A single round of substitutions is performed before command invocation The result of a substitution is not interpreted a second tim
136. ver not the ui command have all your repositories in the same directory and have them all use the extension fossil 2 If the machine goes off line i e for OS update or other reason it might not automatically restart the Fossil servers 3 Backup of the repositories might be not be done This method does work and if you only have one repository and a diligent owner of the master machine it will work and work well 3 2 1 0 2 Server hosted If you have a server type machine available i e a Linux or UNIX box that is running Apache or a Windows machine running HS you can let it be the webserver for your repository This has a number of advantages this machine will be up all the time it will probably be automatically backed up and it can easily support multiple Fossil repositories I am not going into how to set up the webserver or how to enable Common Gateway Interface CGI See the following sites e For IIS see here http www boutell com newfaq creating iiscgihowto html and just ensure that your fossil exe is in the path to be run by the cgi script e For Apache see here http httpd apache org docs 2 0 howto cgi html and ensure you know the directory where the CGI scripts are stored If you are not in control of the webserver you will need the help of the server admin to enable CGI and to copy your CGI scripts to correct location 3 2 1 0 3 CGI Script for hosted server If we assume an Apache server and in my case the c
137. web page for that repository If run outside the working directory you can specify the repository on the command line Pandora 2 jschimpf Public FossilBook jim fossil help ui Usage fossil server P port TCPPORT REPOSITORY Or fossil ui P port TCPPORT REPOSITORY Open a socket and begin listening and responding to HTTP requests on TCP port 8080 or on any other TCP port defined by the P or port option The optional argument is the name of the repository The repository argument may be omitted if the working directory is within an open checkout The ui command automatically starts a web browser after initializing the web server In the server command the REPOSITORY can be a directory aka folder that contains one or more repositories with names ending in fossil In that case the first element of the URL is used to select among the various repositories Figure 5 15 ui details 5 2 15 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 Updated for fossil version 1 25 Page 60 of 107 TA Fossil Version Control Fossil SCM Pandora 2 jschimpf Public FossilBook jim fossil help server Usage fossil server
138. wiki or tickets gr er Kon Re c Append Tkt Append to tickets d Delete Delete wiki and tickets e Email View sensitive data such as EMail addresses Figure 2 8 User Configuration As you can see Fossil automatically configures a number of users beyond just the creator The anonymous user you have already seen 1f 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 Updated for fossil version 1 25 Page 9 of 107 M 27 Fossil Version Control Fossil SCM 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 2 1 on page 6 it s a very good idea to change this to something you can remember rather than the original random one y N ao FossilBook Edit User jim Home Timeline Files Logged in as jim Tags Tickets Wiki Admin Logout Privileges And Capabilities User ID 1 Login jim The Setup user can make arbitrary configuration Contact Info jim schimpf gmail com changes An Admin user can add other users and change user privileges and reset user passwords Capabil
139. wser UI control of the Fossil repository The example used for the entire book is the repository used to manage this book e Link to book PDF e Design amp Tools Notes Fossil version c56af61e5e 2010 04 22 15 48 25 Figure 3 5 Web access to Fossil CGI hosted site Updated for fossil version 1 25 Page 27 of 107 Fossil Version Control Fossil SCM 3 3 User Accounts Serving a repository either self hosting or the more complicated CGI method gets you to the same place as shown in Figure 3 5 on the previous page 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 2 8 on page 9 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 2 8 and add a new user Updated for fossil version 1 25 Page 28 of 107 Fossil Version Control Fossil SCM s gt FossilBook Add A New User Logged in as jim Home Timeline Files Leaves Branches Tags Tickets Wiki Admin Logout Cancel USD paisa Privileges And Capabilities Login Marilyn The Setup user can make arbitrary confi
140. ytes Cards Artifacts Deltas Send 130 1 0 0 Received 2392 52 0 0 Send 318 5 0 0 Received 3320 56 4 0 Total network traffic 781 bytes sent 3508 bytes received New_Version 762a31854d708080678598c8d4ce28465cbee8c5 Autosync http jim pandora dyn o saur com 8080 cgi bin jsonp cgi Bytes Cards Artifacts Deltas Send 3293 55 0 2 Received 2438 53 0 0 Total network traffic 1972 bytes sent 1573 bytes received Pandora 2 jschimpf Public jsonp2 jim Figure 4 18 Fixing both branches Updated for fossil version 1 25 Page 51 of 107 M ag Fossil Version Control Fossil SCM i asonp Timeline Home Timeline Files Leaves Branches Tags Tickets Wiki Admin L 200 Events Checkins Only Older Tickets Only Wiki Only 20 most recent events 10 35 Ticket 2795e6c74d 1 0 Fix unused variable in main c status still Tested with 2 other changes u 10 34 762a31854d Leaf 2795e6c74d Fix unused variable user jim tags VER_2 0 10 32 Tested ticket 2795e6c74d 1 0 Fix unused variable in main c plus 4 other changes user jim 10 30 3b902585d0 Leaf 2795e6c74d Fix unused variable warning user jim tags VER_1 0 10 28 New ticket 2795e6c74d 1 0 Fix unused variable in main c user jim 10 23 Closed ticket 6df Se32ba Branch the repository plus 4 other changes user jim 1 similar event omitted 10 14 a1737916ec Create new branch named VER_2 0 user jim tags VER_2 0 10 13 65e 1148633 Create new branch named

Fossil Version Control A Users Guide

Contents

Download Pdf Manuals

Related Search

Related Contents