Version Control Systems: Fossil Part I
- Tutorial
Greetings, colleagues! 
Relatively recently, a survey was published here on the version control systems used. As expected, Git won by a wide margin, and Fossil was not even included in the list, only flashed a couple of times in the comments. A search in Habr showed that almost nothing was written about Fossil here. Therefore, 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 the version control system for personal and work-related projects, until I met Fossil through a random link. Immediately hooked on the fact that you just need to download and copy to a suitable place, one - the only executable file. If so simple, why not give it a try? I also liked that the entire repository is also one file (SQLite database), which you can simply copy to take home or install it on another computer at work. I generally like the minimalist approach - maybe that’s why the hand didn’t rise to put something like Subversion for a team of 3-4 people.
As it turned out, Fossil is a completely “adult” system, not inferior in terms of basic functionality to its more well-known competitors. As a solid bonus, we have here a web interface, a bug tracking system and Wiki, and error notifications and wiki pages are in the same repository where the project files are also under the control of the version control system, etc. e. their changes are also tracked. In the process of operation and as the documentation was studied, even small but pleasant “goodies” were revealed that added confidence in the correctness of the choice made. I want to emphasize right away: rightness for me. Everyone has different requirements, different habits, someone else is more suitable for something else. For me, Fossil is a perfectly suitable, to say the least, solution.
Fossil Installation
So, go to http://www.fossil-scm.org/download.html and download the package that corresponds to our operating system. Unpack the executable file located somewhere, from where it will then be more convenient to run it, preferably in a directory accessible by SET PATH. Everything, the system is ready to work.
Create and configure a repository
Further, for definiteness, we will proceed from the assumption that we have Windows. Also, for definiteness, we assume that all of our repositories will be stored in a separate directory c: \ fossil, although, of course, you can not allocate any separate space for them, but place them directly next to the files that we give control Fossil. Next, suppose we have a Castle project, whose sources located in c: \ projects \ castle \ source \, we want to put under Fossil control - we will call them working files, and the source directory will be the working directory. And finally, create an empty castle.fossil repository for these sources:
Fossil will create a castle.fossil file and tell us the administrator name (usually the username under which you are logged into the OS) and password. Fossil is generally quite "talkative" and his messages must be read; important information may be contained there. As you already understood, all this happens in the console, so to use Fossil it is advisable to have command line skills and also be familiar with the English language - maybe I searched poorly, 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 - except after the completion of the project. The fossil open command creates a database service file in the current directory, its name may depend on the version of Fossil and on the OS - under Windows it is _FOSSIL_. This file stores information about the open repository and tracks changes in the files. Please note that before opening the repository, I went to the directory parent to the worker. This is important: the repository must be open 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 empty so far, nothing of the kind happens.
Before adding files to the repository, I would advise you to pre-configure something. There are two ways to do this.
1) From the console using the fossil settings command :
Setting crnl-glob to '*' (any) disables checking the characters of the end of the line, encoding-glob - checking the encoding of your files. If this is not done, and your files use a 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 advisable 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 --global option to the fossil settings command - in this case this parameter will be set globally for all repositories on this computer. By the way, if the set value is not specified, then the fossil settings command will return the current value of the parameter in response, and if you do not specify the parameter name, we will get a list of all the preset parameters and their values.
2) The second way to set parameters - using the graphical interface:
As a result of this command, the Fossil web server will be launched, in this case the local one (the default port is 8080, you can specify another option --port) and the browser will use 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 into admin / configuration - set the name of the project and in admin / users - change your password.
Well, finally, add the files with the add command and send it to the repository with the commit command :
Add can add both individual files and directories, and you can use a file mask. Command
Now that the repository is open and the files have been added to it, that is, put under the control of Fossil, you can actually continue work on the project. We write programs, articles, books, with each important change we send it to the repository - we make commit , accompanied by 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 - viewing changes, reverting
File version identifier is an important concept that should be discussed in more detail; it is used in many commands where you need to do something with a specific revision of a file or the entire repository. The following methods for identifying a version exist:
Each element in the Fossil repository — file versions, tickets, wiki pages, etc. — has a unique identifier, a 40-digit hash calculated using SHA-1. Since entering all 40 characters in a command is not very convenient, you can limit yourself to a few (at least 4) first characters. So, the first way to identify the version of the file is the initial fragment of the hash. Another way is the file creation date and time 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 .
Well and, of course, help - how could without it:
I can not help but tell about another team - fossil all . It performs the specified action with all open repositories:
Web interface, tickets, wiki
I already mentioned the Fossil web interface launched by the fossil ui command when I talked about configuring the repository. It looks something like this:
In addition to viewing and changing settings (Admin), here you can see the project history (Timeline), a list of files (Files) and each file separately, the structure of the project branches (Branches), tags (Tags), work with the Bug Tracking system (Tickets) and with 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, a list of changed files, differences from the previous version for each file (by clicking [ diff]), you can download the zip- or tar- archive of this version, edit its representation in the history, including tint, etc.
I would like to briefly dwell on the use of Tickets and Wiki. Tickets - in this case, this word will probably be correctly translated as “cards” - a way to implement the bug tracking system, Bug Tracking, although these cards, generally speaking, can be used not only for error messages, but also for planning work on the project . So, we select Tickets, then - New ticket and fill out the card - a brief summary, type, version number, to which this entry belongs, the degree of criticality, email and a detailed description in which you can use wiki markup, which means referring 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, since it increases the coherence of information in the repository, contributes to the maximum integration of all parts of the project. Once entered, Ticket appears in both the All tickets list and the Timeline. You can now open it, add additional comments, apply a resolution (fixed, rejected, Unable_To_Reproduce, Works_As_Designed, etc.). If ticket is closed, then atcommit 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 ticket.
Before you start using the Wiki, it is advisable to indicate the name of the project, if it has not already been done: Admin / Configuration - fill in the Project Name field and click the Apply Changes button. Select Wiki, click on the Castle project home page (we called the Castle project) and edit this page. We look at the rules of the used wiki markup in Formatting Rules. We use Preview Your Changes, to save click Apply These Changes. If everything is fine, then the created text should appear on the main page (Home) under the menu bar. Let me remind you that changes to wiki pages are captured by the version control system and appear in Timeline.
In addition to the usual named Fossil, it allows you to create time-related wiki pages, they are called events and appear in Timeline. You can create such an event by selecting Wiki and then Create a new event. We enter the time to which we attach the event, Timeline Comment - a line for Timeline, select a color and edit Page Content - i.e., in fact, the contents of the page. The 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 workstation was examined. We learned how to create a repository,
In the next part, we will transfer the repository to another workstation in order, for example, to use it at work and at home, and study the work in multi-user mode.
Relatively recently, a survey was published here on the version control systems used. As expected, Git won by a wide margin, and Fossil was not even included in the list, only flashed a couple of times in the comments. A search in Habr showed that almost nothing was written about Fossil here. Therefore, 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 the version control system for personal and work-related projects, until I met Fossil through a random link. Immediately hooked on the fact that you just need to download and copy to a suitable place, one - the only executable file. If so simple, why not give it a try? I also liked that the entire repository is also one file (SQLite database), which you can simply copy to take home or install it on another computer at work. I generally like the minimalist approach - maybe that’s why the hand didn’t rise to put something like Subversion for a team of 3-4 people.
As it turned out, Fossil is a completely “adult” system, not inferior in terms of basic functionality to its more well-known competitors. As a solid bonus, we have here a web interface, a bug tracking system and Wiki, and error notifications and wiki pages are in the same repository where the project files are also under the control of the version control system, etc. e. their changes are also tracked. In the process of operation and as the documentation was studied, even small but pleasant “goodies” were revealed that added confidence in the correctness of the choice made. I want to emphasize right away: rightness for me. Everyone has different requirements, different habits, someone else is more suitable for something else. For me, Fossil is a perfectly suitable, to say the least, solution.
Fossil Installation
So, go to http://www.fossil-scm.org/download.html and download the package that corresponds to our operating system. Unpack the executable file located somewhere, from where it will then be more convenient to run it, preferably in a directory accessible by SET PATH. Everything, the system is ready to work.
Create and configure a repository
Further, for definiteness, we will proceed from the assumption that we have Windows. Also, for definiteness, we assume that all of our repositories will be stored in a separate directory c: \ fossil, although, of course, you can not allocate any separate space for them, but place them directly next to the files that we give control Fossil. Next, suppose we have a Castle project, whose sources located in c: \ projects \ castle \ source \, we want to put under Fossil control - we will call them working files, and the source directory will be the working directory. And finally, create an empty castle.fossil repository for these sources:
fossil new c:\fossil\castle.fossilFossil will create a castle.fossil file and tell us the administrator name (usually the username under which you are logged into the OS) and password. Fossil is generally quite "talkative" and his messages must be read; important information may be contained there. As you already understood, all this happens in the console, so to use Fossil it is advisable to have command line skills and also be familiar with the English language - maybe I searched poorly, 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.fossilMost 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 - except after the completion of the project. The fossil open command creates a database service file in the current directory, its name may depend on the version of Fossil and on the OS - under Windows it is _FOSSIL_. This file stores information about the open repository and tracks changes in the files. Please note that before opening the repository, I went to the directory parent to the worker. This is important: the repository must be open 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 empty so far, nothing of the kind happens.
Before adding files to the repository, I would advise you to pre-configure something. There are two ways to do this.
1) From the console using the fossil settings command :
fossil settings crnl-glob '*'
fossil settings encoding-glob '*'Setting crnl-glob to '*' (any) disables checking the characters of the end of the line, encoding-glob - checking the encoding of your files. If this is not done, and your files use a 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 advisable 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 --global option to the fossil settings command - in this case this parameter will be set globally for all repositories on this computer. By the way, if the set value is not specified, then the fossil settings command will return the current value of the parameter in response, and if you do not specify the parameter name, we will get a list of all the preset parameters and their values.
2) The second way to set parameters - using the graphical interface:
fossil uiAs a result of this command, the Fossil web server will be launched, in this case the local one (the default port is 8080, you can specify another option --port) and the browser will use 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 into admin / configuration - set the name of the project and in admin / users - change your password.
Well, finally, add the files with the add command and send it 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. Command
fossil add .Now that the repository is open and the files have been added to it, that is, put under the control of Fossil, you can actually continue work on the project. We write programs, articles, books, with each important change we send it to the repository - we make commit , accompanied by 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.cfossil mv source\bridge\item* source\wall\fossil addremoveAnd a few commands that provide information about the repository and individual files:
fossil ls source\wallfossil statusfossil changesfossil extrasCommands for working with file versions - viewing changes, reverting
fossil timeline
fossil timeline after 2014-09-01
fossil timeline before 2014-07-15
fossil finfo source\wall\brick.cFile version identifier is an important concept that should be discussed in more detail; it is used in many commands where you need to do something with a specific revision of a file or the entire repository. The following methods for identifying a version exist:
- SHA-1 hash
- label name (tag)
- timestamp - creation date and time
- distinguished names: tip, current, next, previous or prev
Each element in the Fossil repository — file versions, tickets, wiki pages, etc. — has a unique identifier, a 40-digit hash calculated using SHA-1. Since entering all 40 characters in a command is not very convenient, you can limit yourself to a few (at least 4) first characters. So, the first way to identify the version of the file is the initial fragment of the hash. Another way is the file creation date and time 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.cfossil gdifffossil tag add TAGNAME VERSION
fossil tag cancel TAGNAME VERSIONfossil revert
fossil revert source\wall\brick.c
fossil revert -r VERSION source\wall\brick.cfossil undoWell and, of course, help - how could without it:
fossil help
fossil help addI can not help but tell about another 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
Web interface, tickets, wiki
I already mentioned the Fossil web interface launched by the fossil ui command when I talked about configuring the repository. It looks something like this:
In addition to viewing and changing settings (Admin), here you can see the project history (Timeline), a list of files (Files) and each file separately, the structure of the project branches (Branches), tags (Tags), work with the Bug Tracking system (Tickets) and with 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, a list of changed files, differences from the previous version for each file (by clicking [ diff]), you can download the zip- or tar- archive of this version, edit its representation in the history, including tint, etc.
I would like to briefly dwell on the use of Tickets and Wiki. Tickets - in this case, this word will probably be correctly translated as “cards” - a way to implement the bug tracking system, Bug Tracking, although these cards, generally speaking, can be used not only for error messages, but also for planning work on the project . So, we select Tickets, then - New ticket and fill out the card - a brief summary, type, version number, to which this entry belongs, the degree of criticality, email and a detailed description in which you can use wiki markup, which means referring 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, since it increases the coherence of information in the repository, contributes to the maximum integration of all parts of the project. Once entered, Ticket appears in both the All tickets list and the Timeline. You can now open it, add additional comments, apply a resolution (fixed, rejected, Unable_To_Reproduce, Works_As_Designed, etc.). If ticket is closed, then atcommit 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 ticket.
Before you start using the Wiki, it is advisable to indicate the name of the project, if it has not already been done: Admin / Configuration - fill in the Project Name field and click the Apply Changes button. Select Wiki, click on the Castle project home page (we called the Castle project) and edit this page. We look at the rules of the used wiki markup in Formatting Rules. We use Preview Your Changes, to save click Apply These Changes. If everything is fine, then the created text should appear on the main page (Home) under the menu bar. Let me remind you that changes to wiki pages are captured by the version control system and appear in Timeline.
In addition to the usual named Fossil, it allows you to create time-related wiki pages, they are called events and appear in Timeline. You can create such an event by selecting Wiki and then Create a new event. We enter the time to which we attach the event, Timeline Comment - a line for Timeline, select a color and edit Page Content - i.e., in fact, the contents of the page. The Fossil documentation recommends using events as
- Milestones of the project - for example, major releases
- Developer blog entries describing the current status of the project, roadmaps for further development
- Project Milestones
- Project related news
- Ads.
Conclusion
So, in the first part of the review, the use of Fossil in single-user mode at one workstation was examined. We learned how to create a repository,
fossil new c:\fossil\castle.fossilc:
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"In the next part, we will transfer the repository to another workstation in order, for example, to use it at work and at home, and study the work in multi-user mode.