Fossil SCM
Reduce one level of indentation in the whyusefossil.wiki document, for improved readability on mobile.
Commit
eec971fdeb143f0f41ce01a47af3b5757104e19ed30502a6a1849ee30d80970e
Parent
3ff09684873cb57…
1 file changed
+253
-246
+253
-246
| --- www/whyusefossil.wiki | ||
| +++ www/whyusefossil.wiki | ||
| @@ -2,12 +2,11 @@ | ||
| 2 | 2 | <h1 align='center'>Why You Should Use Fossil</h1> |
| 3 | 3 | <p align='center'><b>Or, if not Fossil, at least some kind of modern |
| 4 | 4 | version control<br>such as Git, Mercurial, or Subversion.</b></p> |
| 5 | 5 | <p align='center'>(Presented in outline form, for people in a hurry)</p> |
| 6 | 6 | |
| 7 | -<ol> | |
| 8 | -<li><p><b>Benefits of Version Control</b> | |
| 7 | +<b>I. Benefits of Version Control</b> | |
| 9 | 8 | <ol type='A'> |
| 10 | 9 | <li><p><b>Immutable file and version identification</b> |
| 11 | 10 | <ol type='i'> |
| 12 | 11 | <li>Simplified and unambiguous communication between developers |
| 13 | 12 | <li>Detect accidental or surreptitious changes |
| @@ -37,250 +36,258 @@ | ||
| 37 | 36 | <li>Failed disk-drives cause no loss of work |
| 38 | 37 | <li>Avoid wasting time doing manual file copying |
| 39 | 38 | <li>Avoid human errors during manual backups |
| 40 | 39 | </ol> |
| 41 | 40 | </ol> |
| 42 | -<a name='definitions'></a> | |
| 43 | -<li><p><b>Definitions</b></p> | |
| 44 | - <ul> | |
| 45 | - <li><p><b>Project</b> → | |
| 46 | - a collection of computer files that serve some common | |
| 47 | - purpose. Often the project is a software application and the | |
| 48 | - individual files are source code together with makefiles, scripts, and | |
| 49 | - "README.txt" files. Other examples of projects include books or | |
| 50 | - manuals in which each chapter or section is held in a separate file. | |
| 51 | - <ul> | |
| 52 | - <li><p>Projects change and evolve. The whole purpose of version | |
| 53 | - control is to track and manage that evolution. | |
| 54 | - <li><p>Most projects contain many files, but it is possible | |
| 55 | - to have a project consisting of just a single file. | |
| 56 | - <li><p>Fossil requires that | |
| 57 | - all the files for a project must be collected into a single | |
| 58 | - directory hierarchy - a single folder possibly with layers | |
| 59 | - of subfolders. Fossil is not a good choice for managing a | |
| 60 | - project that has files scattered hither and yon all over | |
| 61 | - the disk. In other words, Fossil only works for projects | |
| 62 | - where the files are laid out such that they can be archived | |
| 63 | - into a ZIP file or tarball. | |
| 64 | - </ul> | |
| 65 | - <li><p><b>Repository</b> → | |
| 66 | - (also called "repo") a single file that contains | |
| 67 | - all historical versions of all files in a project. A repo is similar | |
| 68 | - to a ZIP archive in that it is a single file that stores compressed | |
| 69 | - versions of many other files. Files can be extracted from the | |
| 70 | - repo and new files can be added to the repo, just as with a ZIP | |
| 71 | - archive. But a repo has other capabilities above and beyond | |
| 72 | - what a ZIP archive can do. | |
| 73 | - <ul> | |
| 74 | - <li><p>Fossil does not care what you name your repository files, | |
| 75 | - though names ending with ".fossil" are recommended. | |
| 76 | - <li><p>A single project typically has multiple, redundant repositories on | |
| 77 | - separate machines. | |
| 78 | - <li><p>All repositories stay synchronized with one another by exchanging | |
| 79 | - information via HTTP or SSH. | |
| 80 | - <li><p>All repos for a single project redundantly store all information | |
| 81 | - about that project. So if any one repo is lost due to a disk | |
| 82 | - crash, all content is preserved in the surviving repos. | |
| 83 | - <li><p>The usual arrangement is one repository per user. And since | |
| 84 | - most users these days have their own computer, that means one | |
| 85 | - repository per computer. But this is not a requirement. It is | |
| 86 | - ok to have multiple copies of the same repository on the same | |
| 87 | - computer. | |
| 88 | - <li><p>Fossil works fine with just a single copy of the repository. | |
| 89 | - But in that case there is no redundancy. If that one repository | |
| 90 | - file is lost due to a hardware malfunction, then there is no way | |
| 91 | - to recover the project. | |
| 92 | - <li><p>Best practice is to keep all repositories for a user in a single | |
| 93 | - folder. Folders such as "~/Fossils" or "%USERPROFILE%\Fossils" | |
| 94 | - are recommended. Fossil itself does not care where the repositories | |
| 95 | - are stored. Nor does Fossil require repositories to be | |
| 96 | - kept in the same folder. But it is easier to organize your work | |
| 97 | - if all repositories are kept in the same place. | |
| 98 | - </ul> | |
| 99 | - <li><p><b>Check-out</b> → | |
| 100 | - a set of files that have been extracted from a | |
| 101 | - repository and that represent a particular version or snapshot of | |
| 102 | - the project. | |
| 103 | - <ul> | |
| 104 | - <li><p>Check-outs must be on the same computer as the repository from | |
| 105 | - which they are extracted. This is just like with a ZIP archive: | |
| 106 | - one must have the ZIP archive file on the local machine before | |
| 107 | - extracting files from ZIP archive. | |
| 108 | - <li><p>There can be multiple check-outs (in different folders) from | |
| 109 | - the same repository. | |
| 110 | - <li><p>The repository must be on the same computer as the check-out, but | |
| 111 | - the relative locations of the repo and the check-out are arbitrary. | |
| 112 | - The repository may be located inside the folder holding the | |
| 113 | - check-out, but it certainly does not have to be and usually is | |
| 114 | - not. | |
| 115 | - <li><p>A special file exists in every check-out that tells Fossil from | |
| 116 | - which repository the check-out was extracted, and which version of | |
| 117 | - the project the check-out represents. This is the ".fslckout" file | |
| 118 | - on unix systems or the "_FOSSIL_" file on Windows. | |
| 119 | - </ul> | |
| 120 | - <li><p><b>Check-in</b> → | |
| 121 | - another name for a particular version of the project. | |
| 122 | - A check-in is a collection of files inside of a repository that | |
| 123 | - represent a snapshot of the project for an instant in time. | |
| 124 | - Check-ins exist only inside of the repository. This contrasts with | |
| 125 | - a check-out which is a collection of files outside of the repository. | |
| 126 | - <ul> | |
| 127 | - <li><p>Every check-out knows the check-in from which it was derived. | |
| 128 | - But check-outs might have been edited and so might not exactly | |
| 129 | - match their associated check-in. | |
| 130 | - <li><p>Check-ins are immutable. They can never be changed. But | |
| 131 | - check-outs are collections of ordinary files on disk. The | |
| 132 | - files of a check-out can be edited just like any other file. | |
| 133 | - <li><p>A check-in can be thought of as an historical snapshot of a | |
| 134 | - check-out. | |
| 135 | - <li><p>"Check-in", "version", "snapshot", and "revision" are synonyms. | |
| 136 | - <li><p> When used as a noun, the word "commit" is another synonym | |
| 137 | - for "check-in". When used as a verb, the word "commit" | |
| 138 | - means to create a new check-in. | |
| 139 | - </ul> | |
| 140 | - </ul> | |
| 141 | -<li><p><b>Basic Fossil commands</b> | |
| 142 | - <ul> | |
| 143 | - <li><p><b>clone</b> → | |
| 144 | - Make a copy of a repository. The original repository | |
| 145 | - is usually (but not always) on a remote machine and the copy is on | |
| 146 | - the local machine. The copy remembers the network location from | |
| 147 | - which it was copied and (by default) tries to keep itself synchronized | |
| 148 | - with the original. | |
| 149 | - <li><p><b>open</b> → | |
| 150 | - Create a new check-out from a repository on the local machine. | |
| 151 | - <li><p><b>update</b> → | |
| 152 | - Modify an existing check-out so that it is derived from a | |
| 153 | - different version of the same project. | |
| 154 | - <li><p><b>commit</b> → | |
| 155 | - Create a new version (a new check-in) of the project that | |
| 156 | - is a snapshot of the current check-out. | |
| 157 | - <li><p><b>revert</b> → | |
| 158 | - Undo all local edits on a check-out. Make the check-out | |
| 159 | - be an exact copy of its associated check-in. | |
| 160 | - <li><p><b>push</b> → | |
| 161 | - Copy content found in a local repository over to a remote | |
| 162 | - repository. (Fossil usually does this automatically in response to | |
| 163 | - a "commit" and so this command is seldom used, but it is important | |
| 164 | - to understand it.) | |
| 165 | - <li><p><b>pull</b> → | |
| 166 | - Copy new content found in a remote repository into a local | |
| 167 | - repository. A "pull" by itself does not modify any check-out. The | |
| 168 | - "pull" command only moves content between repositories. However, | |
| 169 | - the "update" command will (often) automatically do a "pull" before | |
| 170 | - attempting to update the local check-out. | |
| 171 | - <li><p><b>sync</b> → | |
| 172 | - Do both a "push" and a "pull" at the same time. | |
| 173 | - <li><p><b>add</b> → | |
| 174 | - Add a new file to the local check-out. The file must already be | |
| 175 | - on disk. This command tells Fossil to start tracking and managing | |
| 176 | - the file. This command affects only the local check-out and does | |
| 177 | - not modify any repository. The new file is inserted into the | |
| 178 | - repository at the next "commit" command. | |
| 179 | - <li><p><b>rm/mv</b> → | |
| 180 | - Short for 'remove' and 'move', these commands are like "add" | |
| 181 | - in that they specify pending changes to the structure of the check-out. | |
| 182 | - As with "add", no changes are made to the repository until the next | |
| 183 | - "commit". | |
| 184 | - </ul> | |
| 185 | -<li><p><b>The history of a project is a Directed Acyclic Graph (DAG)</b> | |
| 186 | - <ul> | |
| 187 | - <li><p>Fossil (and other distributed VCSes like Git and Mercurial, but | |
| 188 | - not Subversion) represent | |
| 189 | - the history of a project as a directed acyclic graph (DAG). | |
| 190 | - <ul> | |
| 191 | - <li><p>Each check-in is a node in the graph | |
| 192 | - <li><p>If check-in Y is derived from check-in X then there is | |
| 193 | - an arc in the graph from node X to node Y. | |
| 194 | - <li><p>The older check-in (X) is call the "parent" and the newer | |
| 195 | - check-in (Y) is the "child". The child is derived from | |
| 196 | - the parent. | |
| 197 | - </ul> | |
| 198 | - <li><p>Two users (or the same user working in different check-outs) | |
| 199 | - might commit different changes against the same check-in. This | |
| 200 | - results in one parent node having two or more children. | |
| 201 | - <li><p>Command: <b>merge</b> → | |
| 202 | - combines the work of multiple check-ins into | |
| 203 | - a single check-out. That check-out can then be committed to create | |
| 204 | - a new check-in that has two (or more) parents. | |
| 205 | - <ul> | |
| 206 | - <li><p>Most check-ins have just one parent, and either zero or | |
| 207 | - one child. | |
| 208 | - <li><p>When a check-in has two or more parents, one of those parents | |
| 209 | - is the "primary parent". All the other parent nodes are "secondary" | |
| 210 | - or "merge" parents. | |
| 211 | - Conceptually, the primary parent shows the main line of | |
| 212 | - development. Content from the merge parents is added | |
| 213 | - into the main line. | |
| 214 | - <li><p>The "direct children" of a check-in X are all children that | |
| 215 | - have X as their primary parent. | |
| 216 | - <li><p>A check-in node with no direct children is sometimes called | |
| 217 | - a "leaf". | |
| 218 | - <li><p>The "merge" command changes only the check-out. | |
| 219 | - The "commit" command must be run subsequently to make the merge | |
| 220 | - a permanent part of project. | |
| 221 | - </ul> | |
| 222 | - <li><p>Definition: <b>branch</b> → | |
| 223 | - a sequence of check-ins that are all linked | |
| 224 | - together in the DAG through the primary parent. | |
| 225 | - <ul> | |
| 226 | - <li><p>Branches are often given names which propagate to direct children. | |
| 227 | - The tradition in Fossil is to call the main branch "trunk". In | |
| 228 | - Git, it's called "master" by default, though some call it | |
| 229 | - something else, like "main". | |
| 230 | - <li><p>It is possible to have multiple branches with the same name. | |
| 231 | - Fossil has no problem with this, but it can be confusing to | |
| 232 | - humans, so best practice is to give each branch a unique name. | |
| 233 | - <li><p>The name of a branch can be changed by adding special tags | |
| 234 | - to the first check-in of a branch. The name assigned by this | |
| 235 | - special tag automatically propagates to all direct children. | |
| 236 | - </ul> | |
| 237 | - </ul> | |
| 238 | -<li><p><b>Why version control is important (reprise)</b> | |
| 239 | - <ol type="A"> | |
| 240 | - <li><p>Every check-in and every individual file has a unique name - its | |
| 241 | - SHA1 or SHA3-256 hash. Team members can unambiguously identify | |
| 242 | - any specific | |
| 243 | - version of the overall project or any specific version of an | |
| 244 | - individual file. | |
| 245 | - <li><p>Any historical version of the whole project or of any individual | |
| 246 | - file can be easily recreated at any time and by any team member. | |
| 247 | - <li><p>Accidental changes to files can be detected by recomputing their | |
| 248 | - cryptographic hash. | |
| 249 | - <li><p>Files of unknown origin can be identified using their hash. | |
| 250 | - <li><p>Developers are able to work in parallel, review each others work, | |
| 251 | - and easily merge their changes together. External revisions to | |
| 252 | - the baseline can be easily incorporated into the latest changes. | |
| 253 | - <li><p>Developers can follow experimental lines of development, then | |
| 254 | - revert back to an earlier stable version if the experiment does | |
| 255 | - not work out. Creativity is enhanced by allowing crazy ideas to | |
| 256 | - be investigated without destabilizing the project. | |
| 257 | - <li><p>Developers can work on several independent subprojects, flipping | |
| 258 | - back and forth from one subproject to another at will, and merge | |
| 259 | - patches together or back into the main line of development as they | |
| 260 | - mature. | |
| 261 | - <li><p>Older changes can be easily backed out of recent revisions, for | |
| 262 | - example if bugs are found long after the code was committed. | |
| 263 | - <li><p>Enhancements in a branch can be easily copied into other branches, | |
| 264 | - or into the trunk. | |
| 265 | - <li><p>The complete history of all changes is plainly visible to | |
| 266 | - all team members. Project leaders can easily keep track of what | |
| 267 | - all team members are doing. Check-in comments help everyone to | |
| 268 | - understand and/or remember the reason for each change. | |
| 269 | - <li><p>New team members can be brought up-to-date with all of the historical | |
| 270 | - code, quickly and easily. | |
| 271 | - <li><p>New developers, interns, or inexperienced staff members who still | |
| 272 | - do not understand all the details of the project or who are otherwise | |
| 273 | - prone to making mistakes can be assigned significant subprojects to | |
| 274 | - be carried out in branches without risking main line stability. | |
| 275 | - <li><p>Code is automatically synchronized across all machines. No human | |
| 276 | - effort is wasted copying files from machine to machine. The risk | |
| 277 | - of human errors during file transfer and backup is eliminated. | |
| 278 | - <li><p>A hardware failure results in minimal lost work because | |
| 279 | - all previously committed changes will have been automatically | |
| 280 | - replicated on other machines. | |
| 281 | - <li><p>The complete work history of the project is conveniently archived | |
| 282 | - in a single file, simplifying long-term record keeping. | |
| 283 | - <li><p>A precise historical record is maintained which can be used to | |
| 284 | - support copyright and patent claims or regulatory compliance. | |
| 285 | - </ol> | |
| 41 | + | |
| 42 | +<a name='definitions'></a> | |
| 43 | +<p><b>II. Definitions</b></p> | |
| 44 | + | |
| 45 | +<ul> | |
| 46 | +<li><p><b>Project</b> → | |
| 47 | + a collection of computer files that serve some common | |
| 48 | + purpose. Often the project is a software application and the | |
| 49 | + individual files are source code together with makefiles, scripts, and | |
| 50 | + "README.txt" files. Other examples of projects include books or | |
| 51 | + manuals in which each chapter or section is held in a separate file. | |
| 52 | + <ul> | |
| 53 | + <li><p>Projects change and evolve. The whole purpose of version | |
| 54 | + control is to track and manage that evolution. | |
| 55 | + <li><p>Most projects contain many files, but it is possible | |
| 56 | + to have a project consisting of just a single file. | |
| 57 | + <li><p>Fossil requires that | |
| 58 | + all the files for a project must be collected into a single | |
| 59 | + directory hierarchy - a single folder possibly with layers | |
| 60 | + of subfolders. Fossil is not a good choice for managing a | |
| 61 | + project that has files scattered hither and yon all over | |
| 62 | + the disk. In other words, Fossil only works for projects | |
| 63 | + where the files are laid out such that they can be archived | |
| 64 | + into a ZIP file or tarball. | |
| 65 | + </ul> | |
| 66 | +<li><p><b>Repository</b> → | |
| 67 | + (also called "repo") a single file that contains | |
| 68 | + all historical versions of all files in a project. A repo is similar | |
| 69 | + to a ZIP archive in that it is a single file that stores compressed | |
| 70 | + versions of many other files. Files can be extracted from the | |
| 71 | + repo and new files can be added to the repo, just as with a ZIP | |
| 72 | + archive. But a repo has other capabilities above and beyond | |
| 73 | + what a ZIP archive can do. | |
| 74 | + <ul> | |
| 75 | + <li><p>Fossil does not care what you name your repository files, | |
| 76 | + though names ending with ".fossil" are recommended. | |
| 77 | + <li><p>A single project typically has multiple, redundant repositories on | |
| 78 | + separate machines. | |
| 79 | + <li><p>All repositories stay synchronized with one another by exchanging | |
| 80 | + information via HTTP or SSH. | |
| 81 | + <li><p>All repos for a single project redundantly store all information | |
| 82 | + about that project. So if any one repo is lost due to a disk | |
| 83 | + crash, all content is preserved in the surviving repos. | |
| 84 | + <li><p>The usual arrangement is one repository per user. And since | |
| 85 | + most users these days have their own computer, that means one | |
| 86 | + repository per computer. But this is not a requirement. It is | |
| 87 | + ok to have multiple copies of the same repository on the same | |
| 88 | + computer. | |
| 89 | + <li><p>Fossil works fine with just a single copy of the repository. | |
| 90 | + But in that case there is no redundancy. If that one repository | |
| 91 | + file is lost due to a hardware malfunction, then there is no way | |
| 92 | + to recover the project. | |
| 93 | + <li><p>Best practice is to keep all repositories for a user in a single | |
| 94 | + folder. Folders such as "~/Fossils" or "%USERPROFILE%\Fossils" | |
| 95 | + are recommended. Fossil itself does not care where the repositories | |
| 96 | + are stored. Nor does Fossil require repositories to be | |
| 97 | + kept in the same folder. But it is easier to organize your work | |
| 98 | + if all repositories are kept in the same place. | |
| 99 | + </ul> | |
| 100 | +<li><p><b>Check-out</b> → | |
| 101 | + a set of files that have been extracted from a | |
| 102 | + repository and that represent a particular version or snapshot of | |
| 103 | + the project. | |
| 104 | + <ul> | |
| 105 | + <li><p>Check-outs must be on the same computer as the repository from | |
| 106 | + which they are extracted. This is just like with a ZIP archive: | |
| 107 | + one must have the ZIP archive file on the local machine before | |
| 108 | + extracting files from ZIP archive. | |
| 109 | + <li><p>There can be multiple check-outs (in different folders) from | |
| 110 | + the same repository. | |
| 111 | + <li><p>The repository must be on the same computer as the check-out, but | |
| 112 | + the relative locations of the repo and the check-out are arbitrary. | |
| 113 | + The repository may be located inside the folder holding the | |
| 114 | + check-out, but it certainly does not have to be and usually is | |
| 115 | + not. | |
| 116 | + <li><p>A special file exists in every check-out that tells Fossil from | |
| 117 | + which repository the check-out was extracted, and which version of | |
| 118 | + the project the check-out represents. This is the ".fslckout" file | |
| 119 | + on unix systems or the "_FOSSIL_" file on Windows. | |
| 120 | + </ul> | |
| 121 | +<li><p><b>Check-in</b> → | |
| 122 | + another name for a particular version of the project. | |
| 123 | + A check-in is a collection of files inside of a repository that | |
| 124 | + represent a snapshot of the project for an instant in time. | |
| 125 | + Check-ins exist only inside of the repository. This contrasts with | |
| 126 | + a check-out which is a collection of files outside of the repository. | |
| 127 | + <ul> | |
| 128 | + <li><p>Every check-out knows the check-in from which it was derived. | |
| 129 | + But check-outs might have been edited and so might not exactly | |
| 130 | + match their associated check-in. | |
| 131 | + <li><p>Check-ins are immutable. They can never be changed. But | |
| 132 | + check-outs are collections of ordinary files on disk. The | |
| 133 | + files of a check-out can be edited just like any other file. | |
| 134 | + <li><p>A check-in can be thought of as an historical snapshot of a | |
| 135 | + check-out. | |
| 136 | + <li><p>"Check-in", "version", "snapshot", and "revision" are synonyms. | |
| 137 | + <li><p> When used as a noun, the word "commit" is another synonym | |
| 138 | + for "check-in". When used as a verb, the word "commit" | |
| 139 | + means to create a new check-in. | |
| 140 | + </ul> | |
| 141 | +</ul> | |
| 142 | + | |
| 143 | +<p><b>III. Basic Fossil commands</b> | |
| 144 | + | |
| 145 | + <ul> | |
| 146 | + <li><p><b>clone</b> → | |
| 147 | + Make a copy of a repository. The original repository | |
| 148 | + is usually (but not always) on a remote machine and the copy is on | |
| 149 | + the local machine. The copy remembers the network location from | |
| 150 | + which it was copied and (by default) tries to keep itself synchronized | |
| 151 | + with the original. | |
| 152 | + <li><p><b>open</b> → | |
| 153 | + Create a new check-out from a repository on the local machine. | |
| 154 | + <li><p><b>update</b> → | |
| 155 | + Modify an existing check-out so that it is derived from a | |
| 156 | + different version of the same project. | |
| 157 | + <li><p><b>commit</b> → | |
| 158 | + Create a new version (a new check-in) of the project that | |
| 159 | + is a snapshot of the current check-out. | |
| 160 | + <li><p><b>revert</b> → | |
| 161 | + Undo all local edits on a check-out. Make the check-out | |
| 162 | + be an exact copy of its associated check-in. | |
| 163 | + <li><p><b>push</b> → | |
| 164 | + Copy content found in a local repository over to a remote | |
| 165 | + repository. (Fossil usually does this automatically in response to | |
| 166 | + a "commit" and so this command is seldom used, but it is important | |
| 167 | + to understand it.) | |
| 168 | + <li><p><b>pull</b> → | |
| 169 | + Copy new content found in a remote repository into a local | |
| 170 | + repository. A "pull" by itself does not modify any check-out. The | |
| 171 | + "pull" command only moves content between repositories. However, | |
| 172 | + the "update" command will (often) automatically do a "pull" before | |
| 173 | + attempting to update the local check-out. | |
| 174 | + <li><p><b>sync</b> → | |
| 175 | + Do both a "push" and a "pull" at the same time. | |
| 176 | + <li><p><b>add</b> → | |
| 177 | + Add a new file to the local check-out. The file must already be | |
| 178 | + on disk. This command tells Fossil to start tracking and managing | |
| 179 | + the file. This command affects only the local check-out and does | |
| 180 | + not modify any repository. The new file is inserted into the | |
| 181 | + repository at the next "commit" command. | |
| 182 | + <li><p><b>rm/mv</b> → | |
| 183 | + Short for 'remove' and 'move', these commands are like "add" | |
| 184 | + in that they specify pending changes to the structure of the check-out. | |
| 185 | + As with "add", no changes are made to the repository until the next | |
| 186 | + "commit". | |
| 187 | + </ul> | |
| 188 | + | |
| 189 | +<b>IV. The history of a project is a Directed Acyclic Graph (DAG)</b> | |
| 190 | + | |
| 191 | + <ul> | |
| 192 | + <li><p>Fossil (and other distributed VCSes like Git and Mercurial, but | |
| 193 | + not Subversion) represent | |
| 194 | + the history of a project as a directed acyclic graph (DAG). | |
| 195 | + <ul> | |
| 196 | + <li><p>Each check-in is a node in the graph | |
| 197 | + <li><p>If check-in Y is derived from check-in X then there is | |
| 198 | + an arc in the graph from node X to node Y. | |
| 199 | + <li><p>The older check-in (X) is call the "parent" and the newer | |
| 200 | + check-in (Y) is the "child". The child is derived from | |
| 201 | + the parent. | |
| 202 | + </ul> | |
| 203 | + <li><p>Two users (or the same user working in different check-outs) | |
| 204 | + might commit different changes against the same check-in. This | |
| 205 | + results in one parent node having two or more children. | |
| 206 | + <li><p>Command: <b>merge</b> → | |
| 207 | + combines the work of multiple check-ins into | |
| 208 | + a single check-out. That check-out can then be committed to create | |
| 209 | + a new check-in that has two (or more) parents. | |
| 210 | + <ul> | |
| 211 | + <li><p>Most check-ins have just one parent, and either zero or | |
| 212 | + one child. | |
| 213 | + <li><p>When a check-in has two or more parents, one of those parents | |
| 214 | + is the "primary parent". All the other parent nodes are "secondary" | |
| 215 | + or "merge" parents. | |
| 216 | + Conceptually, the primary parent shows the main line of | |
| 217 | + development. Content from the merge parents is added | |
| 218 | + into the main line. | |
| 219 | + <li><p>The "direct children" of a check-in X are all children that | |
| 220 | + have X as their primary parent. | |
| 221 | + <li><p>A check-in node with no direct children is sometimes called | |
| 222 | + a "leaf". | |
| 223 | + <li><p>The "merge" command changes only the check-out. | |
| 224 | + The "commit" command must be run subsequently to make the merge | |
| 225 | + a permanent part of project. | |
| 226 | + </ul> | |
| 227 | + <li><p>Definition: <b>branch</b> → | |
| 228 | + a sequence of check-ins that are all linked | |
| 229 | + together in the DAG through the primary parent. | |
| 230 | + <ul> | |
| 231 | + <li><p>Branches are often given names which propagate to direct children. | |
| 232 | + The tradition in Fossil is to call the main branch "trunk". In | |
| 233 | + Git, it's called "master" by default, though some call it | |
| 234 | + something else, like "main". | |
| 235 | + <li><p>It is possible to have multiple branches with the same name. | |
| 236 | + Fossil has no problem with this, but it can be confusing to | |
| 237 | + humans, so best practice is to give each branch a unique name. | |
| 238 | + <li><p>The name of a branch can be changed by adding special tags | |
| 239 | + to the first check-in of a branch. The name assigned by this | |
| 240 | + special tag automatically propagates to all direct children. | |
| 241 | + </ul> | |
| 242 | + </ul> | |
| 243 | + | |
| 244 | +<b>V. Why version control is important (reprise)</b> | |
| 245 | + | |
| 246 | + <ol> | |
| 247 | + <li><p>Every check-in and every individual file has a unique name - its | |
| 248 | + SHA1 or SHA3-256 hash. Team members can unambiguously identify | |
| 249 | + any specific | |
| 250 | + version of the overall project or any specific version of an | |
| 251 | + individual file. | |
| 252 | + <li><p>Any historical version of the whole project or of any individual | |
| 253 | + file can be easily recreated at any time and by any team member. | |
| 254 | + <li><p>Accidental changes to files can be detected by recomputing their | |
| 255 | + cryptographic hash. | |
| 256 | + <li><p>Files of unknown origin can be identified using their hash. | |
| 257 | + <li><p>Developers are able to work in parallel, review each others work, | |
| 258 | + and easily merge their changes together. External revisions to | |
| 259 | + the baseline can be easily incorporated into the latest changes. | |
| 260 | + <li><p>Developers can follow experimental lines of development, then | |
| 261 | + revert back to an earlier stable version if the experiment does | |
| 262 | + not work out. Creativity is enhanced by allowing crazy ideas to | |
| 263 | + be investigated without destabilizing the project. | |
| 264 | + <li><p>Developers can work on several independent subprojects, flipping | |
| 265 | + back and forth from one subproject to another at will, and merge | |
| 266 | + patches together or back into the main line of development as they | |
| 267 | + mature. | |
| 268 | + <li><p>Older changes can be easily backed out of recent revisions, for | |
| 269 | + example if bugs are found long after the code was committed. | |
| 270 | + <li><p>Enhancements in a branch can be easily copied into other branches, | |
| 271 | + or into the trunk. | |
| 272 | + <li><p>The complete history of all changes is plainly visible to | |
| 273 | + all team members. Project leaders can easily keep track of what | |
| 274 | + all team members are doing. Check-in comments help everyone to | |
| 275 | + understand and/or remember the reason for each change. | |
| 276 | + <li><p>New team members can be brought up-to-date with all of the historical | |
| 277 | + code, quickly and easily. | |
| 278 | + <li><p>New developers, interns, or inexperienced staff members who still | |
| 279 | + do not understand all the details of the project or who are otherwise | |
| 280 | + prone to making mistakes can be assigned significant subprojects to | |
| 281 | + be carried out in branches without risking main line stability. | |
| 282 | + <li><p>Code is automatically synchronized across all machines. No human | |
| 283 | + effort is wasted copying files from machine to machine. The risk | |
| 284 | + of human errors during file transfer and backup is eliminated. | |
| 285 | + <li><p>A hardware failure results in minimal lost work because | |
| 286 | + all previously committed changes will have been automatically | |
| 287 | + replicated on other machines. | |
| 288 | + <li><p>The complete work history of the project is conveniently archived | |
| 289 | + in a single file, simplifying long-term record keeping. | |
| 290 | + <li><p>A precise historical record is maintained which can be used to | |
| 291 | + support copyright and patent claims or regulatory compliance. | |
| 292 | + </ol> | |
| 286 | 293 | </ol> |
| 287 | 294 |
| --- www/whyusefossil.wiki | |
| +++ www/whyusefossil.wiki | |
| @@ -2,12 +2,11 @@ | |
| 2 | <h1 align='center'>Why You Should Use Fossil</h1> |
| 3 | <p align='center'><b>Or, if not Fossil, at least some kind of modern |
| 4 | version control<br>such as Git, Mercurial, or Subversion.</b></p> |
| 5 | <p align='center'>(Presented in outline form, for people in a hurry)</p> |
| 6 | |
| 7 | <ol> |
| 8 | <li><p><b>Benefits of Version Control</b> |
| 9 | <ol type='A'> |
| 10 | <li><p><b>Immutable file and version identification</b> |
| 11 | <ol type='i'> |
| 12 | <li>Simplified and unambiguous communication between developers |
| 13 | <li>Detect accidental or surreptitious changes |
| @@ -37,250 +36,258 @@ | |
| 37 | <li>Failed disk-drives cause no loss of work |
| 38 | <li>Avoid wasting time doing manual file copying |
| 39 | <li>Avoid human errors during manual backups |
| 40 | </ol> |
| 41 | </ol> |
| 42 | <a name='definitions'></a> |
| 43 | <li><p><b>Definitions</b></p> |
| 44 | <ul> |
| 45 | <li><p><b>Project</b> → |
| 46 | a collection of computer files that serve some common |
| 47 | purpose. Often the project is a software application and the |
| 48 | individual files are source code together with makefiles, scripts, and |
| 49 | "README.txt" files. Other examples of projects include books or |
| 50 | manuals in which each chapter or section is held in a separate file. |
| 51 | <ul> |
| 52 | <li><p>Projects change and evolve. The whole purpose of version |
| 53 | control is to track and manage that evolution. |
| 54 | <li><p>Most projects contain many files, but it is possible |
| 55 | to have a project consisting of just a single file. |
| 56 | <li><p>Fossil requires that |
| 57 | all the files for a project must be collected into a single |
| 58 | directory hierarchy - a single folder possibly with layers |
| 59 | of subfolders. Fossil is not a good choice for managing a |
| 60 | project that has files scattered hither and yon all over |
| 61 | the disk. In other words, Fossil only works for projects |
| 62 | where the files are laid out such that they can be archived |
| 63 | into a ZIP file or tarball. |
| 64 | </ul> |
| 65 | <li><p><b>Repository</b> → |
| 66 | (also called "repo") a single file that contains |
| 67 | all historical versions of all files in a project. A repo is similar |
| 68 | to a ZIP archive in that it is a single file that stores compressed |
| 69 | versions of many other files. Files can be extracted from the |
| 70 | repo and new files can be added to the repo, just as with a ZIP |
| 71 | archive. But a repo has other capabilities above and beyond |
| 72 | what a ZIP archive can do. |
| 73 | <ul> |
| 74 | <li><p>Fossil does not care what you name your repository files, |
| 75 | though names ending with ".fossil" are recommended. |
| 76 | <li><p>A single project typically has multiple, redundant repositories on |
| 77 | separate machines. |
| 78 | <li><p>All repositories stay synchronized with one another by exchanging |
| 79 | information via HTTP or SSH. |
| 80 | <li><p>All repos for a single project redundantly store all information |
| 81 | about that project. So if any one repo is lost due to a disk |
| 82 | crash, all content is preserved in the surviving repos. |
| 83 | <li><p>The usual arrangement is one repository per user. And since |
| 84 | most users these days have their own computer, that means one |
| 85 | repository per computer. But this is not a requirement. It is |
| 86 | ok to have multiple copies of the same repository on the same |
| 87 | computer. |
| 88 | <li><p>Fossil works fine with just a single copy of the repository. |
| 89 | But in that case there is no redundancy. If that one repository |
| 90 | file is lost due to a hardware malfunction, then there is no way |
| 91 | to recover the project. |
| 92 | <li><p>Best practice is to keep all repositories for a user in a single |
| 93 | folder. Folders such as "~/Fossils" or "%USERPROFILE%\Fossils" |
| 94 | are recommended. Fossil itself does not care where the repositories |
| 95 | are stored. Nor does Fossil require repositories to be |
| 96 | kept in the same folder. But it is easier to organize your work |
| 97 | if all repositories are kept in the same place. |
| 98 | </ul> |
| 99 | <li><p><b>Check-out</b> → |
| 100 | a set of files that have been extracted from a |
| 101 | repository and that represent a particular version or snapshot of |
| 102 | the project. |
| 103 | <ul> |
| 104 | <li><p>Check-outs must be on the same computer as the repository from |
| 105 | which they are extracted. This is just like with a ZIP archive: |
| 106 | one must have the ZIP archive file on the local machine before |
| 107 | extracting files from ZIP archive. |
| 108 | <li><p>There can be multiple check-outs (in different folders) from |
| 109 | the same repository. |
| 110 | <li><p>The repository must be on the same computer as the check-out, but |
| 111 | the relative locations of the repo and the check-out are arbitrary. |
| 112 | The repository may be located inside the folder holding the |
| 113 | check-out, but it certainly does not have to be and usually is |
| 114 | not. |
| 115 | <li><p>A special file exists in every check-out that tells Fossil from |
| 116 | which repository the check-out was extracted, and which version of |
| 117 | the project the check-out represents. This is the ".fslckout" file |
| 118 | on unix systems or the "_FOSSIL_" file on Windows. |
| 119 | </ul> |
| 120 | <li><p><b>Check-in</b> → |
| 121 | another name for a particular version of the project. |
| 122 | A check-in is a collection of files inside of a repository that |
| 123 | represent a snapshot of the project for an instant in time. |
| 124 | Check-ins exist only inside of the repository. This contrasts with |
| 125 | a check-out which is a collection of files outside of the repository. |
| 126 | <ul> |
| 127 | <li><p>Every check-out knows the check-in from which it was derived. |
| 128 | But check-outs might have been edited and so might not exactly |
| 129 | match their associated check-in. |
| 130 | <li><p>Check-ins are immutable. They can never be changed. But |
| 131 | check-outs are collections of ordinary files on disk. The |
| 132 | files of a check-out can be edited just like any other file. |
| 133 | <li><p>A check-in can be thought of as an historical snapshot of a |
| 134 | check-out. |
| 135 | <li><p>"Check-in", "version", "snapshot", and "revision" are synonyms. |
| 136 | <li><p> When used as a noun, the word "commit" is another synonym |
| 137 | for "check-in". When used as a verb, the word "commit" |
| 138 | means to create a new check-in. |
| 139 | </ul> |
| 140 | </ul> |
| 141 | <li><p><b>Basic Fossil commands</b> |
| 142 | <ul> |
| 143 | <li><p><b>clone</b> → |
| 144 | Make a copy of a repository. The original repository |
| 145 | is usually (but not always) on a remote machine and the copy is on |
| 146 | the local machine. The copy remembers the network location from |
| 147 | which it was copied and (by default) tries to keep itself synchronized |
| 148 | with the original. |
| 149 | <li><p><b>open</b> → |
| 150 | Create a new check-out from a repository on the local machine. |
| 151 | <li><p><b>update</b> → |
| 152 | Modify an existing check-out so that it is derived from a |
| 153 | different version of the same project. |
| 154 | <li><p><b>commit</b> → |
| 155 | Create a new version (a new check-in) of the project that |
| 156 | is a snapshot of the current check-out. |
| 157 | <li><p><b>revert</b> → |
| 158 | Undo all local edits on a check-out. Make the check-out |
| 159 | be an exact copy of its associated check-in. |
| 160 | <li><p><b>push</b> → |
| 161 | Copy content found in a local repository over to a remote |
| 162 | repository. (Fossil usually does this automatically in response to |
| 163 | a "commit" and so this command is seldom used, but it is important |
| 164 | to understand it.) |
| 165 | <li><p><b>pull</b> → |
| 166 | Copy new content found in a remote repository into a local |
| 167 | repository. A "pull" by itself does not modify any check-out. The |
| 168 | "pull" command only moves content between repositories. However, |
| 169 | the "update" command will (often) automatically do a "pull" before |
| 170 | attempting to update the local check-out. |
| 171 | <li><p><b>sync</b> → |
| 172 | Do both a "push" and a "pull" at the same time. |
| 173 | <li><p><b>add</b> → |
| 174 | Add a new file to the local check-out. The file must already be |
| 175 | on disk. This command tells Fossil to start tracking and managing |
| 176 | the file. This command affects only the local check-out and does |
| 177 | not modify any repository. The new file is inserted into the |
| 178 | repository at the next "commit" command. |
| 179 | <li><p><b>rm/mv</b> → |
| 180 | Short for 'remove' and 'move', these commands are like "add" |
| 181 | in that they specify pending changes to the structure of the check-out. |
| 182 | As with "add", no changes are made to the repository until the next |
| 183 | "commit". |
| 184 | </ul> |
| 185 | <li><p><b>The history of a project is a Directed Acyclic Graph (DAG)</b> |
| 186 | <ul> |
| 187 | <li><p>Fossil (and other distributed VCSes like Git and Mercurial, but |
| 188 | not Subversion) represent |
| 189 | the history of a project as a directed acyclic graph (DAG). |
| 190 | <ul> |
| 191 | <li><p>Each check-in is a node in the graph |
| 192 | <li><p>If check-in Y is derived from check-in X then there is |
| 193 | an arc in the graph from node X to node Y. |
| 194 | <li><p>The older check-in (X) is call the "parent" and the newer |
| 195 | check-in (Y) is the "child". The child is derived from |
| 196 | the parent. |
| 197 | </ul> |
| 198 | <li><p>Two users (or the same user working in different check-outs) |
| 199 | might commit different changes against the same check-in. This |
| 200 | results in one parent node having two or more children. |
| 201 | <li><p>Command: <b>merge</b> → |
| 202 | combines the work of multiple check-ins into |
| 203 | a single check-out. That check-out can then be committed to create |
| 204 | a new check-in that has two (or more) parents. |
| 205 | <ul> |
| 206 | <li><p>Most check-ins have just one parent, and either zero or |
| 207 | one child. |
| 208 | <li><p>When a check-in has two or more parents, one of those parents |
| 209 | is the "primary parent". All the other parent nodes are "secondary" |
| 210 | or "merge" parents. |
| 211 | Conceptually, the primary parent shows the main line of |
| 212 | development. Content from the merge parents is added |
| 213 | into the main line. |
| 214 | <li><p>The "direct children" of a check-in X are all children that |
| 215 | have X as their primary parent. |
| 216 | <li><p>A check-in node with no direct children is sometimes called |
| 217 | a "leaf". |
| 218 | <li><p>The "merge" command changes only the check-out. |
| 219 | The "commit" command must be run subsequently to make the merge |
| 220 | a permanent part of project. |
| 221 | </ul> |
| 222 | <li><p>Definition: <b>branch</b> → |
| 223 | a sequence of check-ins that are all linked |
| 224 | together in the DAG through the primary parent. |
| 225 | <ul> |
| 226 | <li><p>Branches are often given names which propagate to direct children. |
| 227 | The tradition in Fossil is to call the main branch "trunk". In |
| 228 | Git, it's called "master" by default, though some call it |
| 229 | something else, like "main". |
| 230 | <li><p>It is possible to have multiple branches with the same name. |
| 231 | Fossil has no problem with this, but it can be confusing to |
| 232 | humans, so best practice is to give each branch a unique name. |
| 233 | <li><p>The name of a branch can be changed by adding special tags |
| 234 | to the first check-in of a branch. The name assigned by this |
| 235 | special tag automatically propagates to all direct children. |
| 236 | </ul> |
| 237 | </ul> |
| 238 | <li><p><b>Why version control is important (reprise)</b> |
| 239 | <ol type="A"> |
| 240 | <li><p>Every check-in and every individual file has a unique name - its |
| 241 | SHA1 or SHA3-256 hash. Team members can unambiguously identify |
| 242 | any specific |
| 243 | version of the overall project or any specific version of an |
| 244 | individual file. |
| 245 | <li><p>Any historical version of the whole project or of any individual |
| 246 | file can be easily recreated at any time and by any team member. |
| 247 | <li><p>Accidental changes to files can be detected by recomputing their |
| 248 | cryptographic hash. |
| 249 | <li><p>Files of unknown origin can be identified using their hash. |
| 250 | <li><p>Developers are able to work in parallel, review each others work, |
| 251 | and easily merge their changes together. External revisions to |
| 252 | the baseline can be easily incorporated into the latest changes. |
| 253 | <li><p>Developers can follow experimental lines of development, then |
| 254 | revert back to an earlier stable version if the experiment does |
| 255 | not work out. Creativity is enhanced by allowing crazy ideas to |
| 256 | be investigated without destabilizing the project. |
| 257 | <li><p>Developers can work on several independent subprojects, flipping |
| 258 | back and forth from one subproject to another at will, and merge |
| 259 | patches together or back into the main line of development as they |
| 260 | mature. |
| 261 | <li><p>Older changes can be easily backed out of recent revisions, for |
| 262 | example if bugs are found long after the code was committed. |
| 263 | <li><p>Enhancements in a branch can be easily copied into other branches, |
| 264 | or into the trunk. |
| 265 | <li><p>The complete history of all changes is plainly visible to |
| 266 | all team members. Project leaders can easily keep track of what |
| 267 | all team members are doing. Check-in comments help everyone to |
| 268 | understand and/or remember the reason for each change. |
| 269 | <li><p>New team members can be brought up-to-date with all of the historical |
| 270 | code, quickly and easily. |
| 271 | <li><p>New developers, interns, or inexperienced staff members who still |
| 272 | do not understand all the details of the project or who are otherwise |
| 273 | prone to making mistakes can be assigned significant subprojects to |
| 274 | be carried out in branches without risking main line stability. |
| 275 | <li><p>Code is automatically synchronized across all machines. No human |
| 276 | effort is wasted copying files from machine to machine. The risk |
| 277 | of human errors during file transfer and backup is eliminated. |
| 278 | <li><p>A hardware failure results in minimal lost work because |
| 279 | all previously committed changes will have been automatically |
| 280 | replicated on other machines. |
| 281 | <li><p>The complete work history of the project is conveniently archived |
| 282 | in a single file, simplifying long-term record keeping. |
| 283 | <li><p>A precise historical record is maintained which can be used to |
| 284 | support copyright and patent claims or regulatory compliance. |
| 285 | </ol> |
| 286 | </ol> |
| 287 |
| --- www/whyusefossil.wiki | |
| +++ www/whyusefossil.wiki | |
| @@ -2,12 +2,11 @@ | |
| 2 | <h1 align='center'>Why You Should Use Fossil</h1> |
| 3 | <p align='center'><b>Or, if not Fossil, at least some kind of modern |
| 4 | version control<br>such as Git, Mercurial, or Subversion.</b></p> |
| 5 | <p align='center'>(Presented in outline form, for people in a hurry)</p> |
| 6 | |
| 7 | <b>I. Benefits of Version Control</b> |
| 8 | <ol type='A'> |
| 9 | <li><p><b>Immutable file and version identification</b> |
| 10 | <ol type='i'> |
| 11 | <li>Simplified and unambiguous communication between developers |
| 12 | <li>Detect accidental or surreptitious changes |
| @@ -37,250 +36,258 @@ | |
| 36 | <li>Failed disk-drives cause no loss of work |
| 37 | <li>Avoid wasting time doing manual file copying |
| 38 | <li>Avoid human errors during manual backups |
| 39 | </ol> |
| 40 | </ol> |
| 41 | |
| 42 | <a name='definitions'></a> |
| 43 | <p><b>II. Definitions</b></p> |
| 44 | |
| 45 | <ul> |
| 46 | <li><p><b>Project</b> → |
| 47 | a collection of computer files that serve some common |
| 48 | purpose. Often the project is a software application and the |
| 49 | individual files are source code together with makefiles, scripts, and |
| 50 | "README.txt" files. Other examples of projects include books or |
| 51 | manuals in which each chapter or section is held in a separate file. |
| 52 | <ul> |
| 53 | <li><p>Projects change and evolve. The whole purpose of version |
| 54 | control is to track and manage that evolution. |
| 55 | <li><p>Most projects contain many files, but it is possible |
| 56 | to have a project consisting of just a single file. |
| 57 | <li><p>Fossil requires that |
| 58 | all the files for a project must be collected into a single |
| 59 | directory hierarchy - a single folder possibly with layers |
| 60 | of subfolders. Fossil is not a good choice for managing a |
| 61 | project that has files scattered hither and yon all over |
| 62 | the disk. In other words, Fossil only works for projects |
| 63 | where the files are laid out such that they can be archived |
| 64 | into a ZIP file or tarball. |
| 65 | </ul> |
| 66 | <li><p><b>Repository</b> → |
| 67 | (also called "repo") a single file that contains |
| 68 | all historical versions of all files in a project. A repo is similar |
| 69 | to a ZIP archive in that it is a single file that stores compressed |
| 70 | versions of many other files. Files can be extracted from the |
| 71 | repo and new files can be added to the repo, just as with a ZIP |
| 72 | archive. But a repo has other capabilities above and beyond |
| 73 | what a ZIP archive can do. |
| 74 | <ul> |
| 75 | <li><p>Fossil does not care what you name your repository files, |
| 76 | though names ending with ".fossil" are recommended. |
| 77 | <li><p>A single project typically has multiple, redundant repositories on |
| 78 | separate machines. |
| 79 | <li><p>All repositories stay synchronized with one another by exchanging |
| 80 | information via HTTP or SSH. |
| 81 | <li><p>All repos for a single project redundantly store all information |
| 82 | about that project. So if any one repo is lost due to a disk |
| 83 | crash, all content is preserved in the surviving repos. |
| 84 | <li><p>The usual arrangement is one repository per user. And since |
| 85 | most users these days have their own computer, that means one |
| 86 | repository per computer. But this is not a requirement. It is |
| 87 | ok to have multiple copies of the same repository on the same |
| 88 | computer. |
| 89 | <li><p>Fossil works fine with just a single copy of the repository. |
| 90 | But in that case there is no redundancy. If that one repository |
| 91 | file is lost due to a hardware malfunction, then there is no way |
| 92 | to recover the project. |
| 93 | <li><p>Best practice is to keep all repositories for a user in a single |
| 94 | folder. Folders such as "~/Fossils" or "%USERPROFILE%\Fossils" |
| 95 | are recommended. Fossil itself does not care where the repositories |
| 96 | are stored. Nor does Fossil require repositories to be |
| 97 | kept in the same folder. But it is easier to organize your work |
| 98 | if all repositories are kept in the same place. |
| 99 | </ul> |
| 100 | <li><p><b>Check-out</b> → |
| 101 | a set of files that have been extracted from a |
| 102 | repository and that represent a particular version or snapshot of |
| 103 | the project. |
| 104 | <ul> |
| 105 | <li><p>Check-outs must be on the same computer as the repository from |
| 106 | which they are extracted. This is just like with a ZIP archive: |
| 107 | one must have the ZIP archive file on the local machine before |
| 108 | extracting files from ZIP archive. |
| 109 | <li><p>There can be multiple check-outs (in different folders) from |
| 110 | the same repository. |
| 111 | <li><p>The repository must be on the same computer as the check-out, but |
| 112 | the relative locations of the repo and the check-out are arbitrary. |
| 113 | The repository may be located inside the folder holding the |
| 114 | check-out, but it certainly does not have to be and usually is |
| 115 | not. |
| 116 | <li><p>A special file exists in every check-out that tells Fossil from |
| 117 | which repository the check-out was extracted, and which version of |
| 118 | the project the check-out represents. This is the ".fslckout" file |
| 119 | on unix systems or the "_FOSSIL_" file on Windows. |
| 120 | </ul> |
| 121 | <li><p><b>Check-in</b> → |
| 122 | another name for a particular version of the project. |
| 123 | A check-in is a collection of files inside of a repository that |
| 124 | represent a snapshot of the project for an instant in time. |
| 125 | Check-ins exist only inside of the repository. This contrasts with |
| 126 | a check-out which is a collection of files outside of the repository. |
| 127 | <ul> |
| 128 | <li><p>Every check-out knows the check-in from which it was derived. |
| 129 | But check-outs might have been edited and so might not exactly |
| 130 | match their associated check-in. |
| 131 | <li><p>Check-ins are immutable. They can never be changed. But |
| 132 | check-outs are collections of ordinary files on disk. The |
| 133 | files of a check-out can be edited just like any other file. |
| 134 | <li><p>A check-in can be thought of as an historical snapshot of a |
| 135 | check-out. |
| 136 | <li><p>"Check-in", "version", "snapshot", and "revision" are synonyms. |
| 137 | <li><p> When used as a noun, the word "commit" is another synonym |
| 138 | for "check-in". When used as a verb, the word "commit" |
| 139 | means to create a new check-in. |
| 140 | </ul> |
| 141 | </ul> |
| 142 | |
| 143 | <p><b>III. Basic Fossil commands</b> |
| 144 | |
| 145 | <ul> |
| 146 | <li><p><b>clone</b> → |
| 147 | Make a copy of a repository. The original repository |
| 148 | is usually (but not always) on a remote machine and the copy is on |
| 149 | the local machine. The copy remembers the network location from |
| 150 | which it was copied and (by default) tries to keep itself synchronized |
| 151 | with the original. |
| 152 | <li><p><b>open</b> → |
| 153 | Create a new check-out from a repository on the local machine. |
| 154 | <li><p><b>update</b> → |
| 155 | Modify an existing check-out so that it is derived from a |
| 156 | different version of the same project. |
| 157 | <li><p><b>commit</b> → |
| 158 | Create a new version (a new check-in) of the project that |
| 159 | is a snapshot of the current check-out. |
| 160 | <li><p><b>revert</b> → |
| 161 | Undo all local edits on a check-out. Make the check-out |
| 162 | be an exact copy of its associated check-in. |
| 163 | <li><p><b>push</b> → |
| 164 | Copy content found in a local repository over to a remote |
| 165 | repository. (Fossil usually does this automatically in response to |
| 166 | a "commit" and so this command is seldom used, but it is important |
| 167 | to understand it.) |
| 168 | <li><p><b>pull</b> → |
| 169 | Copy new content found in a remote repository into a local |
| 170 | repository. A "pull" by itself does not modify any check-out. The |
| 171 | "pull" command only moves content between repositories. However, |
| 172 | the "update" command will (often) automatically do a "pull" before |
| 173 | attempting to update the local check-out. |
| 174 | <li><p><b>sync</b> → |
| 175 | Do both a "push" and a "pull" at the same time. |
| 176 | <li><p><b>add</b> → |
| 177 | Add a new file to the local check-out. The file must already be |
| 178 | on disk. This command tells Fossil to start tracking and managing |
| 179 | the file. This command affects only the local check-out and does |
| 180 | not modify any repository. The new file is inserted into the |
| 181 | repository at the next "commit" command. |
| 182 | <li><p><b>rm/mv</b> → |
| 183 | Short for 'remove' and 'move', these commands are like "add" |
| 184 | in that they specify pending changes to the structure of the check-out. |
| 185 | As with "add", no changes are made to the repository until the next |
| 186 | "commit". |
| 187 | </ul> |
| 188 | |
| 189 | <b>IV. The history of a project is a Directed Acyclic Graph (DAG)</b> |
| 190 | |
| 191 | <ul> |
| 192 | <li><p>Fossil (and other distributed VCSes like Git and Mercurial, but |
| 193 | not Subversion) represent |
| 194 | the history of a project as a directed acyclic graph (DAG). |
| 195 | <ul> |
| 196 | <li><p>Each check-in is a node in the graph |
| 197 | <li><p>If check-in Y is derived from check-in X then there is |
| 198 | an arc in the graph from node X to node Y. |
| 199 | <li><p>The older check-in (X) is call the "parent" and the newer |
| 200 | check-in (Y) is the "child". The child is derived from |
| 201 | the parent. |
| 202 | </ul> |
| 203 | <li><p>Two users (or the same user working in different check-outs) |
| 204 | might commit different changes against the same check-in. This |
| 205 | results in one parent node having two or more children. |
| 206 | <li><p>Command: <b>merge</b> → |
| 207 | combines the work of multiple check-ins into |
| 208 | a single check-out. That check-out can then be committed to create |
| 209 | a new check-in that has two (or more) parents. |
| 210 | <ul> |
| 211 | <li><p>Most check-ins have just one parent, and either zero or |
| 212 | one child. |
| 213 | <li><p>When a check-in has two or more parents, one of those parents |
| 214 | is the "primary parent". All the other parent nodes are "secondary" |
| 215 | or "merge" parents. |
| 216 | Conceptually, the primary parent shows the main line of |
| 217 | development. Content from the merge parents is added |
| 218 | into the main line. |
| 219 | <li><p>The "direct children" of a check-in X are all children that |
| 220 | have X as their primary parent. |
| 221 | <li><p>A check-in node with no direct children is sometimes called |
| 222 | a "leaf". |
| 223 | <li><p>The "merge" command changes only the check-out. |
| 224 | The "commit" command must be run subsequently to make the merge |
| 225 | a permanent part of project. |
| 226 | </ul> |
| 227 | <li><p>Definition: <b>branch</b> → |
| 228 | a sequence of check-ins that are all linked |
| 229 | together in the DAG through the primary parent. |
| 230 | <ul> |
| 231 | <li><p>Branches are often given names which propagate to direct children. |
| 232 | The tradition in Fossil is to call the main branch "trunk". In |
| 233 | Git, it's called "master" by default, though some call it |
| 234 | something else, like "main". |
| 235 | <li><p>It is possible to have multiple branches with the same name. |
| 236 | Fossil has no problem with this, but it can be confusing to |
| 237 | humans, so best practice is to give each branch a unique name. |
| 238 | <li><p>The name of a branch can be changed by adding special tags |
| 239 | to the first check-in of a branch. The name assigned by this |
| 240 | special tag automatically propagates to all direct children. |
| 241 | </ul> |
| 242 | </ul> |
| 243 | |
| 244 | <b>V. Why version control is important (reprise)</b> |
| 245 | |
| 246 | <ol> |
| 247 | <li><p>Every check-in and every individual file has a unique name - its |
| 248 | SHA1 or SHA3-256 hash. Team members can unambiguously identify |
| 249 | any specific |
| 250 | version of the overall project or any specific version of an |
| 251 | individual file. |
| 252 | <li><p>Any historical version of the whole project or of any individual |
| 253 | file can be easily recreated at any time and by any team member. |
| 254 | <li><p>Accidental changes to files can be detected by recomputing their |
| 255 | cryptographic hash. |
| 256 | <li><p>Files of unknown origin can be identified using their hash. |
| 257 | <li><p>Developers are able to work in parallel, review each others work, |
| 258 | and easily merge their changes together. External revisions to |
| 259 | the baseline can be easily incorporated into the latest changes. |
| 260 | <li><p>Developers can follow experimental lines of development, then |
| 261 | revert back to an earlier stable version if the experiment does |
| 262 | not work out. Creativity is enhanced by allowing crazy ideas to |
| 263 | be investigated without destabilizing the project. |
| 264 | <li><p>Developers can work on several independent subprojects, flipping |
| 265 | back and forth from one subproject to another at will, and merge |
| 266 | patches together or back into the main line of development as they |
| 267 | mature. |
| 268 | <li><p>Older changes can be easily backed out of recent revisions, for |
| 269 | example if bugs are found long after the code was committed. |
| 270 | <li><p>Enhancements in a branch can be easily copied into other branches, |
| 271 | or into the trunk. |
| 272 | <li><p>The complete history of all changes is plainly visible to |
| 273 | all team members. Project leaders can easily keep track of what |
| 274 | all team members are doing. Check-in comments help everyone to |
| 275 | understand and/or remember the reason for each change. |
| 276 | <li><p>New team members can be brought up-to-date with all of the historical |
| 277 | code, quickly and easily. |
| 278 | <li><p>New developers, interns, or inexperienced staff members who still |
| 279 | do not understand all the details of the project or who are otherwise |
| 280 | prone to making mistakes can be assigned significant subprojects to |
| 281 | be carried out in branches without risking main line stability. |
| 282 | <li><p>Code is automatically synchronized across all machines. No human |
| 283 | effort is wasted copying files from machine to machine. The risk |
| 284 | of human errors during file transfer and backup is eliminated. |
| 285 | <li><p>A hardware failure results in minimal lost work because |
| 286 | all previously committed changes will have been automatically |
| 287 | replicated on other machines. |
| 288 | <li><p>The complete work history of the project is conveniently archived |
| 289 | in a single file, simplifying long-term record keeping. |
| 290 | <li><p>A precise historical record is maintained which can be used to |
| 291 | support copyright and patent claims or regulatory compliance. |
| 292 | </ol> |
| 293 | </ol> |
| 294 |