Version Control Systems: Fossil Part I
Greetings, colleagues! 
Relatively recently, a survey was published on the version control systems used. As expected, Git won by a large margin, and Fossil was not even included in the list, only flashed in the comments a couple of times. Search on Habr showed that here about Fossil practically did not write. That's why I decided to publish this article - especially since the Russian-language information about Fossil is extremely scarce and monotonous.
Over the years of participation in open source development, I had the opportunity to use CVS, Subversion and Git, but I did not use it for personal and work-related projects of the version control system until I got acquainted with Fossil through a random link. Immediately hooked that you just have to download and copy to the right place one - the only executable file. If it's that simple, why not try? I also liked that the entire repository is also one file (SQLite database), which you can simply copy to take home or install on another computer at work. I generally like the minimalist approach - maybe that's why the hand did not rise to put for a team of 3-4 people or for personal use something like Subversion.
')
As it turned out, Fossil is a completely “adult” system, which is not inferior in terms of basic functionality to its more well-known competitors. As a solid bonus, we have a web-interface, an error tracking system (Bug Tracking) and a Wiki, with error notifications and wiki-pages located in the same repository, where the project files are also under the control of the version control system, t. e. their changes are also tracked. In the process of exploitation and as the documentation was studied, still small, but pleasant “goodies” emerged, which added conviction in the correctness of the choice made. Just want to emphasize: correctness for me. Everyone has different requirements, different habits, someone else is more suitable for something else. For me, Fossil is a perfectly suitable, if not more, solution.
Install Fossil
So, go to http://www.fossil-scm.org/download.html and download the package corresponding to our operating system. We unpack the executable file located there somewhere, from where it will be more convenient to start it later, preferably in a directory accessible via SET PATH. Everything, the system is ready to work.
Create and configure repository
Further, for definiteness, we will proceed from the assumption that we have Windows. Also, for definiteness, we will assume that all our repositories will be stored in a separate directory c: \ fossil, although, of course, you can not allocate for them a separate place, and place directly next to the files that we give under control Fossil Next, suppose that we have the Castle project, whose sources are in c: \ projects \ castle \ source \, we want to control Fossil - we will call them working files, and the source directory the working directory. And finally, we create an empty castle.fossil repository for these sources:
Fossil will create the file castle.fossil and tell us the name of the administrator (usually the username under which you entered the OS) and the password. Fossil is generally quite “talkative” and its messages must be read, it may contain important information. As you already understood, all this happens in the console, so to use Fossil, it is desirable to have the skills to work with the command line, as well as to be familiar with the English language - maybe I was looking bad, but I did not find any mention of internationalization.
The next step is to go to the c: \ projects \ castle directory and open the created repository:
Most Fossil operations are performed on an open repository, so this should be done immediately after creation. But to close it ( fossil close ) hardly makes sense - unless after the completion of the project. The fossil open opening command creates a service database file in the current directory, its name may depend on the Fossil version and on the OS — for Windows it is _FOSSIL_. This file stores information about the open repository and tracks changes to files. Please note that before opening the repository, I moved to the directory that is parental to the worker. This is important: the repository must be opened either in the working directory, or in one of the parent (at any level of the tree), otherwise Fossil will refuse to add files from the working directory to the repository.
In fact, fossil open not only creates a service file, but also checks the correspondence between files in the working directory and in the repository, and if any file from the repository is not in the working directory, or differs from it, it overwrites the file in the working directory from the repository (after warning all / yes / no). But since our repository is still empty, nothing like this happens.
Before you add files to the repository, I would advise something to pre-configure. This can be done in two ways.
1) From the console using the fossil settings command:
Setting crnl-glob to '*' (any) disables the end -of- character check, encoding-glob - checks the encoding of your files. If this is not done, and your files use the standard Windows CRNL sequence or encoding other than UTF-8, then Fossil will issue a warning and will require confirmation during the commit operation. In addition, it is desirable to specify a list of file masks that may be present in your working directory, but should not be included in the repository — object modules, executable files, etc., for example:
You can add the option --global to the fossil settings command - in this case this option will be set globally for all repositories on this computer. By the way, if the setting value is not specified, the fossil settings command will return the current parameter value to the response, and if the parameter name is not specified, then we will receive a list of all the preset parameters and their values.
2) The second method of setting parameters is using a graphical interface:
As a result of the execution of this command, the Fossil-built web server will be launched, in this case, local (the default port is 8080, you can specify with the other option --port) and the browser to the URL 127.0.0.1:8080. To set the parameters, open the admin menu item, then settings and change crnl-glob, encoding-glob and ignore-glob there. At the same time you can go to admin / configuration - set the name of the project and in admin / users - change your password.
And finally, add the files with the add command and send to the repository with the commit command:
Add can add both individual files and directories, and you can use a file mask. Team
Now that the repository is open and the files have been added to it, i.e., placed under the control of Fossil, you can actually continue to work on the project. We write programs, articles, books, with each important change we send it to the repository - we make a commit , accompanying it with a meaningful comment:
Here are some more commands to delete / move / add files:
And a few commands that provide information about the repository and individual files:
Commands for working with file versions — view changes, return
A file version identifier is an important concept, which should be discussed in more detail; it is used in many commands where something needs to be done with a specific revision of a file or the entire repository. There are the following ways to identify the version:
Each item in the Fossil repository — both file versions, tickets, and wiki pages, etc. — has a unique identifier, a 40-digit hash calculated from SHA-1. Since it’s not very convenient to enter all 40 characters in a team, you can limit it to a few (at least 4) of its first characters. So, the first way to identify the file version is the initial fragment of the hash. Another way is the date and time of the file creation recorded in one of the formats: YYYY-MM-DD, YYYY-MM-DD HH: MM, YYYY-MM-DD HH: MM: SS. See here for more details.
And, of course, help - as without it:
I can not help but tell more about one team - fossil all . It performs the specified action with all open repositories:
Web-interface, tickets, wiki
I have already mentioned the Fossil web-interface, launched by the fossil ui team, when I talked about configuring the repository. It looks like this:
In addition to viewing and changing the settings (Admin), you can see the project history (Timeline), the list of files (Files) and each file individually, the structure of the project branches (Branches), tags (Tags), work with the Bug Tracking system (Tickets) and Wiki - documentation.
Looking through the history (Timeline), you can select any version by clicking on its identifier (hash code in square brackets), and there you can see the list of files at that time, the list of changed files, differences from the previous version for each file (by clicking [ diff]), you can download a zip or tar archive of this version, edit its presentation in history, incl. touch up, etc.
I would like to briefly discuss the use of Tickets and Wiki. Tickets - in this case, this word will probably be correctly translated as “cards” - a way to implement an error tracking system, Bug Tracking, although these cards, generally speaking, can be used not only for error messages, but also for planning work on a project . So, choose Tickets, then - New ticket and fill in the card - a brief content, type, version number to which this record belongs, degree of criticality, email and a detailed description in which you can use wiki markup, which means refer to any objects in the repository by their identifier - other cards, wiki-pages, file versions. By the way, this possibility of using identifiers as links seems to me very valuable, because it increases the coherence of information in the repository, contributes to the maximum integration of all parts of the project. Once entered, the Ticket appears in both the list of All tickets and Timeline. It can now be opened, add additional notes, and impose a resolution (fixed, rejected, Unable_To_Reproduce, Works_As_Designed, etc.). If the ticket is closed, then with the commit of the corresponding correction, it is desirable to indicate the identifier of this card in square brackets, then in the version history in the corresponding line there will be a link to the ticket.
Before you start using the Wiki, it is advisable to indicate the name of the project, if this has not already been done: Admin / Configuration — fill in the Project Name field and click the Apply Changes button. Select the Wiki, click on the Castle project home page (we called the project Castle) and edit this page. We use the rules of the wiki markup in Formatting Rules. We use Preview Your Changes, to save click Apply These Changes. If everything is normal, then the created text should appear on the main page (Home) under the menu line. Let me remind you that changes in wiki-pages are recorded by the version control system and appear in the Timeline.
In addition to the usual named Fossil allows you to create wiki-pages tied to the time, they are called events (events) and appear in the Timeline. You can create such an event by selecting Wiki and, further, Create a new event. Enter the time to which we attach the event, Timeline Comment - the line for Timeline, choose the color and edit Page Content - that is, the actual content of the page. Fossil documentation recommends using events as
Conclusion
So, in the first part of the review, the use of Fossil in single user mode at one workplace was considered. We learned to create a repository,
In the next part we will move the repository to another workplace, for example, to use it at work and at home, and study the work in multi-user mode.
Relatively recently, a survey was published on the version control systems used. As expected, Git won by a large margin, and Fossil was not even included in the list, only flashed in the comments a couple of times. Search on Habr showed that here about Fossil practically did not write. That's why I decided to publish this article - especially since the Russian-language information about Fossil is extremely scarce and monotonous.
Over the years of participation in open source development, I had the opportunity to use CVS, Subversion and Git, but I did not use it for personal and work-related projects of the version control system until I got acquainted with Fossil through a random link. Immediately hooked that you just have to download and copy to the right place one - the only executable file. If it's that simple, why not try? I also liked that the entire repository is also one file (SQLite database), which you can simply copy to take home or install on another computer at work. I generally like the minimalist approach - maybe that's why the hand did not rise to put for a team of 3-4 people or for personal use something like Subversion.
')
As it turned out, Fossil is a completely “adult” system, which is not inferior in terms of basic functionality to its more well-known competitors. As a solid bonus, we have a web-interface, an error tracking system (Bug Tracking) and a Wiki, with error notifications and wiki-pages located in the same repository, where the project files are also under the control of the version control system, t. e. their changes are also tracked. In the process of exploitation and as the documentation was studied, still small, but pleasant “goodies” emerged, which added conviction in the correctness of the choice made. Just want to emphasize: correctness for me. Everyone has different requirements, different habits, someone else is more suitable for something else. For me, Fossil is a perfectly suitable, if not more, solution.
Install Fossil
So, go to http://www.fossil-scm.org/download.html and download the package corresponding to our operating system. We unpack the executable file located there somewhere, from where it will be more convenient to start it later, preferably in a directory accessible via SET PATH. Everything, the system is ready to work.
Create and configure repository
Further, for definiteness, we will proceed from the assumption that we have Windows. Also, for definiteness, we will assume that all our repositories will be stored in a separate directory c: \ fossil, although, of course, you can not allocate for them a separate place, and place directly next to the files that we give under control Fossil Next, suppose that we have the Castle project, whose sources are in c: \ projects \ castle \ source \, we want to control Fossil - we will call them working files, and the source directory the working directory. And finally, we create an empty castle.fossil repository for these sources:
fossil new c:\fossil\castle.fossil Fossil will create the file castle.fossil and tell us the name of the administrator (usually the username under which you entered the OS) and the password. Fossil is generally quite “talkative” and its messages must be read, it may contain important information. As you already understood, all this happens in the console, so to use Fossil, it is desirable to have the skills to work with the command line, as well as to be familiar with the English language - maybe I was looking bad, but I did not find any mention of internationalization.
The next step is to go to the c: \ projects \ castle directory and open the created repository:
c: cd \projects\castle fossil open c:\fossil\castle.fossil
Most Fossil operations are performed on an open repository, so this should be done immediately after creation. But to close it ( fossil close ) hardly makes sense - unless after the completion of the project. The fossil open opening command creates a service database file in the current directory, its name may depend on the Fossil version and on the OS — for Windows it is _FOSSIL_. This file stores information about the open repository and tracks changes to files. Please note that before opening the repository, I moved to the directory that is parental to the worker. This is important: the repository must be opened either in the working directory, or in one of the parent (at any level of the tree), otherwise Fossil will refuse to add files from the working directory to the repository.
In fact, fossil open not only creates a service file, but also checks the correspondence between files in the working directory and in the repository, and if any file from the repository is not in the working directory, or differs from it, it overwrites the file in the working directory from the repository (after warning all / yes / no). But since our repository is still empty, nothing like this happens.
Before you add files to the repository, I would advise something to pre-configure. This can be done in two ways.
1) From the console using the fossil settings command:
fossil settings crnl-glob '*' fossil settings encoding-glob '*'
Setting crnl-glob to '*' (any) disables the end -of- character check, encoding-glob - checks the encoding of your files. If this is not done, and your files use the standard Windows CRNL sequence or encoding other than UTF-8, then Fossil will issue a warning and will require confirmation during the commit operation. In addition, it is desirable to specify a list of file masks that may be present in your working directory, but should not be included in the repository — object modules, executable files, etc., for example:
fossil settings ignore-glob '*.o,*.obj,*.exe,*.bak,*.log'
You can add the option --global to the fossil settings command - in this case this option will be set globally for all repositories on this computer. By the way, if the setting value is not specified, the fossil settings command will return the current parameter value to the response, and if the parameter name is not specified, then we will receive a list of all the preset parameters and their values.
2) The second method of setting parameters is using a graphical interface:
fossil ui
As a result of the execution of this command, the Fossil-built web server will be launched, in this case, local (the default port is 8080, you can specify with the other option --port) and the browser to the URL 127.0.0.1:8080. To set the parameters, open the admin menu item, then settings and change crnl-glob, encoding-glob and ignore-glob there. At the same time you can go to admin / configuration - set the name of the project and in admin / users - change your password.
And finally, add the files with the add command and send to the repository with the commit command:
fossil add source fossil commit -m "Initial commit"
Add can add both individual files and directories, and you can use a file mask. Team
fossil add . adds all files from the current directory and subdirectories.
Now that the repository is open and the files have been added to it, i.e., placed under the control of Fossil, you can actually continue to work on the project. We write programs, articles, books, with each important change we send it to the repository - we make a commit , accompanying it with a meaningful comment:
fossil commit -m "Another brick in the wall"
Here are some more commands to delete / move / add files:
fossil rm source\wall\brick.c Remove brick.c from the repository. At the same time, all previous versions of this file remain in the repository, it is simply marked as deleted and its further changes in the repository are not recorded. This file is not removed from the working directory - if necessary, we must do it ourselves.
fossil mv source\bridge\item* source\wall\ Moving files with item * mask from one directory to another. Note that Fossil itself does not move files in the working directory, we need to do this by hand.
fossil addremove Add files from the working directory to the repository that are not in the repository (i.e., the list is issued by the fossil extras command) and delete files previously deleted from the working directory from the repository.
And a few commands that provide information about the repository and individual files:
fossil ls source\wall We display the list of files from the source directory \ walls in the repository, the -v parameter adds a column with the file status (EDITED, UNCHANGED), the parameter --age - the last commit time for each file.
fossil status We look at the current state of the repository.
fossil changes Display a list of files that have been modified since the last commit .
fossil extras We list the "extra" files - those that are present in the working directory, but not included in the repository.
Commands for working with file versions — view changes, return
fossil timeline fossil timeline after 2014-09-01 fossil timeline before 2014-07-15 We display the repository change history, the -v option adds to the output a list of files affected by each change. With -t, you can specify what kind of changes should be displayed: -t ci - in files, -te - in events, -tt - in tickets, -tw - in wiki.
fossil finfo source\wall\brick.c By default, we display the change history of the brick.c file. If the -s parameter is specified, then brief information about the file, if -p displays the contents of the file, and if, in addition to -p, a version identifier is also specified ( -r VERSION ), then the specified version of the file is output.
A file version identifier is an important concept, which should be discussed in more detail; it is used in many commands where something needs to be done with a specific revision of a file or the entire repository. There are the following ways to identify the version:
- SHA-1 hash
- tag name
- timestamp - date and time of creation
- distinguished names: tip, current, next, previous or prev
Each item in the Fossil repository — both file versions, tickets, and wiki pages, etc. — has a unique identifier, a 40-digit hash calculated from SHA-1. Since it’s not very convenient to enter all 40 characters in a team, you can limit it to a few (at least 4) of its first characters. So, the first way to identify the file version is the initial fragment of the hash. Another way is the date and time of the file creation recorded in one of the formats: YYYY-MM-DD, YYYY-MM-DD HH: MM, YYYY-MM-DD HH: MM: SS. See here for more details.
fossil diff source\wall\brick.c fossil diff --from VERSION1 --to VERSION2 source\wall\brick.c fossil diff --from previous --to current source\wall\brick.c Print to the console the difference (diff) between different versions of the specified file. Here, VERSION1 and VERSION2 are version identifiers, in accordance with the description given just above, to the fossil finfo command . If they are not specified, the difference between the latest version from the repository and the file in the working directory is displayed. If Tcl / Tk is installed (it usually stands on Linux-systems, but there is a port for Windows), then you can use the -tk option - in this case, the built-in graphical tools based on Tcl / Tk will be used to show the differences. If you have a GUI program for graphically representing the difference between text files (I use examdiff.exe in Windows), then you can preset it as the value of the Fossil diff-command parameter using the web interface or the fossil settings diff command command — then this program will be called when running fossil diff .
fossil gdiff Same as fossil diff , only the program used as the value of the Fossil gdiff-command parameter is used to display differences.
fossil tag add TAGNAME VERSION fossil tag cancel TAGNAME VERSION Add ( add ) or remove ( cancel ) the tag (tag) of the specified version of the repository. This label can be considered as an alias of the version identifier and used in the corresponding commands instead of the identifier, preferably with the tag: prefix. Usually tags put on the most significant, landmark versions of the project.
fossil revert fossil revert source\wall\brick.c fossil revert -r VERSION source\wall\brick.c We return to the working directory the specified version of the file (or all files, if the file name is not specified). If the version ( -r VERSION ) is not specified, then the last one is taken - the one that got into the repository during the last commit . The version identifier is specified in accordance with the rules described above (for the fossil finfo command ).
fossil undo We cancel changes in the working directory made by the revert , merge or update command (we will consider the last two later, in the second part).
And, of course, help - as without it:
fossil help fossil help add Help with no arguments displays a list of commands, and with the name of the command as an argument (for example, add , as in the example), a description of this command.
I can not help but tell more about one team - fossil all . It performs the specified action with all open repositories:
fossil all list fossil all changes fossil all extras fossil all pull fossil all push fossil all sync list - lists the repositories, changes - lists the changed files in all repositories, etc.
Web-interface, tickets, wiki
I have already mentioned the Fossil web-interface, launched by the fossil ui team, when I talked about configuring the repository. It looks like this:
In addition to viewing and changing the settings (Admin), you can see the project history (Timeline), the list of files (Files) and each file individually, the structure of the project branches (Branches), tags (Tags), work with the Bug Tracking system (Tickets) and Wiki - documentation.
Looking through the history (Timeline), you can select any version by clicking on its identifier (hash code in square brackets), and there you can see the list of files at that time, the list of changed files, differences from the previous version for each file (by clicking [ diff]), you can download a zip or tar archive of this version, edit its presentation in history, incl. touch up, etc.
I would like to briefly discuss the use of Tickets and Wiki. Tickets - in this case, this word will probably be correctly translated as “cards” - a way to implement an error tracking system, Bug Tracking, although these cards, generally speaking, can be used not only for error messages, but also for planning work on a project . So, choose Tickets, then - New ticket and fill in the card - a brief content, type, version number to which this record belongs, degree of criticality, email and a detailed description in which you can use wiki markup, which means refer to any objects in the repository by their identifier - other cards, wiki-pages, file versions. By the way, this possibility of using identifiers as links seems to me very valuable, because it increases the coherence of information in the repository, contributes to the maximum integration of all parts of the project. Once entered, the Ticket appears in both the list of All tickets and Timeline. It can now be opened, add additional notes, and impose a resolution (fixed, rejected, Unable_To_Reproduce, Works_As_Designed, etc.). If the ticket is closed, then with the commit of the corresponding correction, it is desirable to indicate the identifier of this card in square brackets, then in the version history in the corresponding line there will be a link to the ticket.
Before you start using the Wiki, it is advisable to indicate the name of the project, if this has not already been done: Admin / Configuration — fill in the Project Name field and click the Apply Changes button. Select the Wiki, click on the Castle project home page (we called the project Castle) and edit this page. We use the rules of the wiki markup in Formatting Rules. We use Preview Your Changes, to save click Apply These Changes. If everything is normal, then the created text should appear on the main page (Home) under the menu line. Let me remind you that changes in wiki-pages are recorded by the version control system and appear in the Timeline.
In addition to the usual named Fossil allows you to create wiki-pages tied to the time, they are called events (events) and appear in the Timeline. You can create such an event by selecting Wiki and, further, Create a new event. Enter the time to which we attach the event, Timeline Comment - the line for Timeline, choose the color and edit Page Content - that is, the actual content of the page. Fossil documentation recommends using events as
- Milestones of the project (Milestones) - for example, major releases
- Developer blog entries describing the current state of the project, road maps for further development
- Project Checkpoints
- Project related news
- Ads.
Conclusion
So, in the first part of the review, the use of Fossil in single user mode at one workplace was considered. We learned to create a repository,
fossil new c:\fossil\castle.fossil open, adjust and replenish it, c: cd \projects\castle fossil open c:\fossil\castle.fossil fossil settings crnl-glob '*' fossil settings encoding-glob '*' fossil settings ignore-glob '*.o,*.obj,*.exe,*.bak,*.log' fossil add source fossil commit -m "Initial commit" use console commands and the Fossil web-interface in the work on the project.
In the next part we will move the repository to another workplace, for example, to use it at work and at home, and study the work in multi-user mode.
Source: https://habr.com/ru/post/235369/
All Articles