|Last modified: 02-06-2015|
Fossil is a single-EXE, cross-platform, distributed source control management program written by SQLite author Dr. Richard Hipp. Unsurprisingly, data is saved in an SQLite database file, making it very easy to back up.
A project resides in one or more repositories. Each change ("commit", a.k.a. check-in) is identified by an "artifact ID", which can refer either to a specific change made to a specific file, or to the whole commit.
"At its lowest level, a Fossil repository consists of an unordered set of immutable "artifacts". You might think of these artifacts as "files", since in many cases the artifacts exactly correspond to source code files that are stored in the Fossil repository. But other "control artifacts" are also included in the mix. These control artifacts define the relationships between artifacts - which files go together to form a particular version of the project, who checked in that version and when, what was the check-in comment, what wiki pages are included with the project, what are the edit histories of each wiki page, what bug reports or tickets are included, who contributed to the evolution of each ticket, and so forth, and so on." (source)
To install, simply unzip the package, update the PATH so that the binary can be found anywhere, and run "fossil.exe".
If working on Windows, a modification is required to handle the CRLF issue ("[file] contains CR/NL line endings; commit anyhow (yes/no/all)?"):
Alternatively, the CRLF issue can be solved through the CLI: "fossil.exe settings crnl-glob '*' --global"
Note: When using WinMerge (188.8.131.52 Unicode), you might see the error message "Merge7z465U.dll The specified module could not be found." To solve this, from http://sourceforge.net/projects/winmerge/files/7-zip-plugin/, cd into the latest directory, eg. DllBuild 0028, and download Merge7z*.7z which should contain Merge7z465U.dll. Just unzip this file and put it in the WinMerge directory.
If you prefer to use the native Fossil command-line application instead of the few GUI solutions, a better alternative to Windows' cmd.exe is the free TCC/LE shell ("Comparing Take Command, TCC/LE, and CMD") or the open-source CLink combine with the open-source ConEmu terminal ("a Windows console emulator with tabs, which presents multiple consoles and simple GUI applications as one customizable GUI window with various features").
Those are the commands that are useful when working with a single repository, with no merges or branches:
Note: As of November 2012, Fossil won't let you search through all the artifacts of one or more files. It might be implemented in the future.
Note: "fossil add *.html" won't work on Windows. Try to recompile with MinGW:
(1) Install mingw/msys
(2) Unpack the Fossil source tarball, or clone the fossil repository.
(3) Run: make -f win/makefile.mingw
(4) Put the resulting "fossil.exe" file somewhere on your path.
Below are the main basic Fossil commands for a single user, ie. with no additional users, with no need to synchronize with some remote repository, and no need for branching/forking.
fossil new c:\test.repo
This will create the new SQLite binary file that holds the repository, ie. files, tickets, wiki, etc. It can be located anywhere, although it's considered best practise to keep it outside the work directory where you will work on files after they've been checked out of the repository.
fossil open c:\test.repo
This will check out the last revision of all the files in the repository, if any, into the current work directory. In addition, it will create a binary file _FOSSIL_ to keep track of changes.
fossil add .
To tell Fossil to add new files to the repository. The files aren't actually added until you run "commit". When using ".", it tells Fossil to add all the files in the current directory recursively, ie. including all the files in all the subdirectories.
Note: To tell Fossil to ignore some extensions and directories:
fossil settings ignore-glob "*.o,*.obj,*.exe, */obj/*, */bin/*, */debug/*" --global
fossil delete myfile.c
This will simply remove the item from the list of files that were previously added through "fossil add".
This shows the list of changes that have been done and will be commited the next time you run "fossil commit". It's a useful command to run before running "fossil commit" just to check that things are OK before proceeding.
fossil commit -m "Added stuff"
To actually apply the pending changes to the repository, eg. new files marked for addition, checked-out files that have been edited and must be checked-in, etc.
If you want to only commit some specific files, use "fossil commit myfile.c -m "Changed stuff"."
If you want to try some new code, and then decide to either keep it (whether it worked or not, just to keep track of things you tried) or discard it, here's how to proceed:
As of January 2013, Fossil doesn't support grep, and switching to another branch implies checking files out of the repository into the work directory with "fossil deconstruct c:\temp\fossil", and grepping through all the files.
More information on branching: Branching, Forking, Merging, and Tagging.
If you wish to compare the last revision of a file and its checked out version in your work directory:
fossil gdiff myfile.c
If you wish to compare two different revisions of a file in the repository:
fossil finfo myfile: Note the first hash, which is the UUID of the commit when the file was commited
fossil gdiff --from UUID#1 --to UUID#2 myfile.c
To compare files between the work directory and those in a given branch:
fossil diff --brief --branch <branch name>
fossil revert myfile.c
This will replace the file in the current directory with its latest revision in the repository. In case you ran "revert" by mistake, run "undo" to cancel and have Fossil recover the work file you just replaced.
This will not remove the changes made to the files up to that point, but will tell Fossil to ignore them from now on:
fossil rm -rf mydir
This will simply remove the _FOSSIL_ at the root of the work directory but will not delete the files in the work directory. From then on, any use of "fossil" will trigger an error since there is no longer any connection.
Note that closing the repository is not required after you're done for the day, as opening a repository simply creates the _FOSSIL_ file, nothing more.
Note that commands must be typed within the working checkout and the current directory must match the location of the files in the repository.
For instance, if the repository is opened in D:\Projects and the repository contains "Project1/myfile.txt", you must first cd to D:\Projects before running any command that affects "Project1/myfile.txt"; Otherwise, Fossil will complain with "no such file", which would happen if you ran that command in D:\Projects\Project2 (causing Fossil to look for Project2/Project1/myfile.txt in the repository).
fossil.exe new c:\myrepo.repo
The repository can be created anywhere.
"cd C:\myprojects\" followed by "fossil.exe open c:\myrepo.repo" will check out all the files from the repository into the current work directory, and create a control file (_FOSSIL_). After that, you can close the DOS box where you ran the fossil binary. From then on, you can add any file below c:\myprojects into the Fossil repository.
If you open the repository in a directory that is non-empty and contains files with the same name as those being checked out, Fossil prompts the user about what to do.
Once a repository has been opened in a directory, you must be located anywhere within that directory before asking Fossil to perform a task such as adding a file or commiting changes, or you'll get "not within an open checkout".
fossil.exe add "myfile.txt"
fossil.exe add "*.bas"
Note: Fossil will re-add files that are already part of the repository (as returned by "fossil ls"). This is harmless.
... including all the sub-directories it contains, if any:
fossil.exe add .
Note: To tell Fossil to ignore some files based on their extension, see below in the article.
In case you mistakenly added a file and wish to tell Fossil to remove it from the list before running "commit":
fossil delete myfile.c
Note: "delete" has another use, which is to tell Fossil to stop watching a file that is currently in the repository while keeping all the revisions until now.
fossill.exe commit -m "Added/removed files"
This will simply add new files that Fossil finds in the current directory that aren't found in the repository, and remove all files that are found in the repository but not in the current directory (caution!)
Actually, the files aren't removed: Fossil will keep all the revisions up to now and simply stop watching this file from then on.
As shown, this simply marks the files to add/remove, and you must then run "commit" to actually enact those commands.
fossil.exe status (more verbose)
fossil.exe commit -m "Some comment"
As of 1.19, there is an undocumented switch that lets you perform a dry-run to check which files will be commited without actually checking them in:
fossil commit -m "Some comment" --test
The list can be limited to the "-n" last commits (default: 20)
fossil timeline --showfiles
IOW, the file that you edited is still in the work directory and hasn't been commited yet. Running the following command will show the changes between the file in the work directory and the latest revision in the repository:
fossil gdiff "path/to/myfile.txt"
fossil.exe finfo "myfile.txt"
The first hash is the UUID of the whole commit, ie. all the changes made to all the files, while the the second hash is the artifact ID and identifies the file itself. Run "fossil finfo" and "fossil timeline" for more.
To view the state of a file at a given revision, fetch the UUID from "finfo" (ie. the first hash), and run this:
fossil.exe gdiff --from 225c3b5f64 --to fd6e31f942 myfile.txt
Note: Using a GUI differ is more user-friendly than using the text-based version: To tell Fossil which GUI differ to use, run "fossil ui" > Admin > Settings, and set the "gdiff-command" line to point to the application; From the command-line, type this: "fossil settings gdiff-command "c:\path\to\WinMergeU.exe"". If not set, Fossil will try to call WinDiff (WinMerge is more recent), and revert to the text-based solution if not found.
If you want Fossil to show the diffs between the last commited version of a file and its current state in the work directory, use "fossil gdiff myfile.txt". Fossil will check out the latest commited version of the file under a temporary filename (something like "myfile.txt~0") which will be automatically deleted after you close the differ.
If you want Fossil to show the diffs between the last and before-last revisions of a file that has been commited, use "fossil gdiff --from-previous myfile.txt".
Note: If you don't run the command where the file can be found, the path to myfile.txt must match what is reported by "fossil ls".
Alternatively, you can use Tcl/Tk:
An alternative to plain Tcl/Tk + "diff --tk" is Eskill : http://eskil.tcl.tk/index.html/doc/trunk/htdocs/
As of December 2012, Fossil doesn't include a way to grep through the repository to find a piece of code, although some grep/regex is in the works.
Here's a temporary work-around solution:
We often want to test a new piece of code, see if it works, and go back to the previous code because it didn't work any better. Here's how to do this:
In case you added a file by mistake and don't want them added to the repository the next time "fossil commit" is executed, run"fossil rm myfile.c". You can use patterns if applicable, eg. "fossil rm *.c".
In case you tried something in code but it didn't work and you'd like to just chuck the changes, first run "fossil commit" before making the changes, play with the code, and when you're ready to cancel the changes, run:
To just cancel the changes made to a single file:
fossil.exe revert myfile.txt
If, after all, you did want to keep the changes you did to the work file, type this to recover them:
Alternatively, you could create a temporary branch just for testing, and either merge the changes into the trunk or simply delete the branch:
In case the work directory already contains the file and it was edited before you ran the above commands, Fossil will display ""fossil undo" is available to undo changes to the working checkout.": This means that the work version was replaced with the revision retrieved from the Fossil repository, but in case you wanted to go back to the work version, run "fossil undo".
In case you checked out a file, made changes in the work directory, and would like to merge those changes with the latest commited revision in the depository:
c:\fossil.exe update "latest" "myfile.txt"
In case you want to check out two revisions of the same file:
You can add one or more tags to a revision, either when running "commit" (or later after finding the revision through "fossil timeline"):
fossil commit -f -tag release -tag version-3.7.15 -bgcolor "#d0c0ff'
fossil timeline (note hash for revision you wish to tag)
fossil tag add initial_version hash_here
This will remove the _FOSSIL_ file from the directory where you opened the repository. From then on, no change to the repository will be accepted.
If the file is currently checked out, run "fossil commit". Next, run "fossil ui", go to the "Files" section, select a file, click on Shun, followed by Rebuild.
Note that files will still be listed in the Files section, but no revisions will be listed when clicking on a shunned file.
Here are a couple of batch files you can use to work with Fossil from an IDE such as VB.Net's.
C:\fossil.exe add %1
C:\fossil.exe commit -m "Added file(s)"
set FileName=%~pnx1 set FileName=%FileName:~1% set FileName=%FileName:\=/% c:\fossil.exe revert "%FileName%" echo "%FileName%" set FileName=
c:\fossil.exe revert %1
The Express version of Visual Studio doesn't support add-in's and plug-in's, but it's not an issue since it's still possible to use Fossil through the External Tools menu and Fossil is a CLI application anyway:
FWIW, here are the commands I added to the IDE:
If you want to add a horizontal line to separate groups of commands, click on "Modify Selection" and select "Begin a Group".
As FastExplorer is deadware, let's also check Plexdata's ContextMenu.
CM is composed of three binaries:
Note: You just need to distribute the two DLLs and your XML file, and run ??? to register the files into the user's PC.
If you'd rather right-click on a folder to perform some basic Fossil commands, here's a way to add items to the context menu that is displayed when right-clicking on a folder in Windows Explorer (or any other file manager, eg. Total Commander):
Not a good solution:
Still no release as of Dec 2013.
First, create a GUI in eg. VB.Net that will let the user type commands and see the output
Next, using ContextMenu, add shell extensions to handle files and folders
Manually (only works for folders):
Kostas Karanikolas' fuel-scm is one of the GUIs available for Windows.
File > Open will check out files from the repository, and created a _FOSSIL_ file in the same directory where the repo file lives, and you will be prompted with "Open Fossil: No workspace found. Would you like to make one here?"
Options in the View menu (essentially matches output of "fossil ls-l"):
In case there are a lot of files in the directories below where the repository lives, before aiming it to the workspace, ie. where the _FOSSIL_ file lives, you can tell Fuel to ignore files that aren't part of the repository through its View menu: Check Modified/Unchanged, and uncheck Unknown/Ignored, and then select Workspace > Open Workspace to have Fuel loop through all the files below.
(.Net) Ingo Koch's WinFossil
Note: SharpFossil is a C# wrapper around Fossil to implement a GUI.
Expects repos to have .fsl extension: Change this in Settings.
Make sure the repo is currently closed
Settings > WinFossil Settings: Fossil location + Default repository extension
Repositories > Select Checkout to check out files into a work directory
Work on the files with your development tools
Repositories: Difference between "Select Checkout", and "Open"
Can I remove menu items I will never need (Repositories: Clone, Push, Pull, Sync)?
Sami Tikka's Fossil GUI project for MacOS
"I think it will work better if you recompile using mingw instead of msvc. The crt0 for msvc does not process wildcards in command-line arguments whereas the crt0 for mingw does."
Add the user through "fossil user new joe".
2013-01-26 [3f672148c8] Some comment (user: Joe, artifact: [113f75d46f], branch: trunk)
The first hash refers to the commit, which could include more than one file. The second hash is the artifact, ie. the specific set of changes made to this particular file during this commit.
"fossil artifact <first hash>" provides infos about the commit
"fossil artifact <second hash>" shows the state of the file at that point
They are two totally different things:
"undo" kills the most recent update or merge operation; "revert" discards any changes made to the files in the work directory and fetches the latest commited versions from the repository.
The directory where you run the diff/gdiff command must match the path to the file in the repository.
For instance, if the repository is C:\MyProjects\my.repo and C:\MyProjects\Project1\myfile.txt was added to the repository, the following command must be typed:
C:\MyProjects\>fossil gdiff --from previous Project1/myfile.txt
This won't work, as myfile.txt is not located in C:\MyProjects:
C:\MyProjects\>fossil gdiff --from previous myfile.txt
Fossil only accepts characters in filenames that are valid on all the platforms it is compiled for. Here are those you cannot use:
Even after running Rebuild, the files are still listed :-/
Does it loop from the current directory all the way to the top of the file system until it finds _FOSSIL_?
"fossil remove myfile.txt" will stop versioning a file but keep all the versions commited so far.
for /r %i in (*.*) do fossil add "%i"
find . -type f -print0 | xargs -0 fossil add --
fossil add .
fossil add $(find . -type f | sed -e '/\.exe/d;/\.dcu/d')
"The --ignore option is a comma-separate list of glob patterns for files to be excluded. Example: '*.o,*.obj,*.exe' If the --ignore option does not appear on the command line then the "ignore-glob" setting is used."
This can either be used on an ad hoc basis with "fossil add . --ignore" or be used by default by launching the Fossil UI > Admin > Settings, and edit the "ignore-glob" setting.
Alternatively, here's how to set this global setting through the CLI: "fossil settings --global ignore-glob "*.exe,*.pdb,*.vb~*,*/bin/*,*/obj/*""
According to GitHub:
What about "My Project"?
Note: If sharing projects with other users, add *.suo to the list of files to ignore since this file is user-specific.
The file might have been removed from disk while it was still checked out. Cd to the directory shown by Fossil, and run "fossil rm myfile".
You tried to open the repository a second time.
Run "fossil commit" to check in changes, and re-run "fossil close" to close the repository.
You must first check out the files using "fossil open c:\myrepo" before being able to view it through the web server.