# No-brainer SCM with Fossil

## Introduction

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. The repository can live anywhere on your filesystem.

## Setup

To install, simply unzip the package, update the PATH so that the binary can be found anywhere, and run "fossil.exe".

Settings can be checked through "fossil settings". If you change a setting in any directory where a repository is currently open, Fossil will mark this as "(local)" and this will supersed the global setting. To undo this change, type eg. "fossil unset gdiff-command", and Fossil will go back to using the global setting.

If working on Windows, a modification is required to handle the CRLF issue ("[file] contains CR/NL line endings; commit anyhow (yes/no/all)?"):

1. fossil.exe ui
2. In the web interface: Admin > Settings, and set "crnl-glob" to *. Save.

Alternatively, the CRLF issue can be solved through the CLI: "fossil.exe settings crnl-glob '*' --global"

If you want to use a GUI differ such as WinMerge instead of Fossil's text-based differ, set the "gdiff-command" line to point to the application you wish to use when calling "fossil gdiff". If there are spaces in the path, use quotes, eg. fossil settings gdiff-command --global "\"C:\Program Files\WinMerge\WinMergeU.exe\""

Note: If WinMerge complains about missing Merge7z1602U.dll, download and unzip Merge7z0028-465-920.7z into the directory where WinMerge.exe lives.

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 ConEmu ("a Windows console emulator with tabs, which presents multiple consoles and simple GUI applications as one customizable GUI window with various features"), or the free TCC/LE shell ("Comparing Take Command, TCC/LE, and CMD").

## Tips

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)

For best performance…

• One project = One Fossil repository
• When adding/committing files, make sure the workdirectory only contains the required files, so that Fossil doesn't waste time going through unmonitored files and sub-directories

## Quick Example

After making sure fossil.exe is part of the system PATH so the OS can locate it, open a DOS box, and type the following commands to 1) create a new repository, 2) open it, 3) add files, and 4) commit the changes:

cd c:\temp\fossil_test

fossil new sample.repo
fossil open sample.repo

mkdir test
cd test

fossil commit -m "Original files"

fossil changes

fossil commit -m "Edited test\dummy2.c"

fossil close

## Main commands for local use

Those are the commands that are useful when working with a single repository, with no merges or branches:

• add: Adds new files to the next commit; must run "commit" afterwards for files to actually be added to the repository
• changes: Shows changes made to files in the work directory; if no output, it means that no checked out files have been modified yet
• close: Closes the connection to the repo, ie. the _FOSSIL_ file in the work directory
• commit: Saves all changes to the repository, eg. add/remove files, add changes, etc.
• extras: Lists files in the work directory and below that Fossil doesn't track, because they haven't been added and commited to the repo
• info: Provides information about the current tree (if no argument given) or a particular object (otherwise). See "changes" and "status"
• finfo: Infos on a specific file
• info: Infos about the repo
• ls: Lists files that Fossil tracks
• new: Creates a new repo
• open: Opens the connection to the repo, creating a _FOSSIL_ file in the current work directory
• mv: Same as "rename"
• revert: Forgets changes to one or all files that haven't been commited yet
• rm: Same as "delete". Deletes files from the repository (but not from the work directory). From now on, the file(s) will no longer be part of the repository, altough all versions until then are still available
• search: Searches for any comment that matches the pattern
• status: Same as "changes", but with additional infos about changes made to checked-out files, if any, ie. status = info + changes
• tag: Add a tag to a revision. Can be used either when commiting changes or later
• undo: Cancels "revert"

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:

http://www.fossil-scm.org/fossil/doc/trunk/www/build.wiki

(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.

## Up and running in 5mn as a single user

Once a file has been added and commited into the repository, it can be removed from the filesystem. Obviously, this means you trust Fossil not to screw up… As an insurance, you might want to add an automated backup that will perform a full check-out and save the files in their native format as well.

For better performance, before checking files out, make sure the repository file is located in an empty work directory, which will be used as a temporary workspace. Then, run "fossil open my.repo": It will check out all the files in the current directory. After you're done editing, commit the changes and close the repository: You can now empty the workspace directory if you so wish.

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.

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).

### Create a new repository

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.exe new c:\myrepo.repo

The repository can be created anywhere.

### Open the repository

cd c:\temp\test.fossil

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.

"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".

### Add new files

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

Also, if fossil complains that a file "contains invalid UTF-8", cancel, run "fossil ui", hit the Admin tab > Settings, and set the "encoding-glob" thusly: "The value is a comma or newline-separated list of GLOB patterns specifying files that the "commit" command will ignore when issuing warnings about text files that may use another encoding than ASCII or UTF-8. Set to "*" to disable encoding checking." The CLI command is "fossil settings encoding-glob '*' --global".

### Adding all files with a given extension

Note: Fossil will re-add files that are already part of the repository (as returned by "fossil ls"). This is harmless.

### Adding the current directory to the repository

... including all the sub-directories it contains, if any:

Note: To tell Fossil to ignore some files based on their extension, see below in the article.

### Cancelling a file added with "add"

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.

### Adding new files and removing delete files in one go

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.

### Remove files that haven't been commited yet

fossil delete myfile.c

This will simply remove the item from the list of files that were previously added through "fossil add".

### Removing a file entirely

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.

### Check current status

fossil changes

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.

### Checking changes before commiting them

fossil.exe changes

fossil.exe status (more verbose)

### Commit changes

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"."

### Commiting changes

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

### Try something new and keep/discard

To try something new, perform a check-in to save the file as it is now, and try some new code; If you're unhappy with it, tell Fossil to check this file out again as it was before and forget the changes you just made.

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:

1. Commit current code
2. Try new code
3. Make a decision:
1. if OK, commit new code : fossil commit -m "New stuff"
2. if NOK and don't care to save it, just go back to previous code:

fossil revert myfile.c (reverts just this file)
fossil revert (reverts all files)

3. if NOK but want to keep track of attempt, commit to experimental branch, and go back to main branch

fossil commit -m "Failed attempt" --branch experimental
fossil update trunk

4. To see the contents of a given revision of a file, regardless of which branch it lives in:

fossil finfo myfile.c: Note UUID (first hash)
fossil cat myfile.c -r UUID

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.

Notes:

• Caution: If the contents of any file in the work directory is different from what's in the branch, changes will be merged.
• If the  new code involves creating new files or deleting existing files that are part of the repository, remember to run "fossil addremove" before commiting, so that Fossil handles those files accordingly.
• To get the list of branches: "fossil branch list". The branch currently active is shown with the * character
• You can assign one or more tags to a revision, which makes it easier to locate code until Fossil adds support for grep
• What's the difference between branch and fork? "When multiple leaves are desirable, we call this branching instead of forking"

More information on branching: Branching, Forking, Merging, and Tagging.

### Commiting changes, trying something, and discarding changes

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:

1. Before trying something new, commit the current code: fossil commit -m "Before trying something new"
2. Edit the code and give it a try
3. If it didn't work and you just want to go back to the last revision from the repository, run "fossil revert myfile.c"

If you'd still like to commit the edited work file to keep track of things you tried and go back to the last revision from the repository, run:

fossil commit -m "Didn't work"
fossil finfo myfile.c, and find the artifact ID of the revision before-last
fossil revert -r ARTIFACT_ID myfile.c

Note: As of January 2013, there's no shortcut "fossil revert -r beforelast myfile.c", but it could be added one day.

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:

fossil revert

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:

fossil.exe undo

Alternatively, you could create a temporary branch just for testing, and either merge the changes into the trunk or simply delete the branch:

1. fossil commit -m "Before playing in branch" --branch just_testing
2. Edit files
3. If you want to chuck the changes and go back to the latest revisions from the repository:

fossil revert
fossil update trunk

OTOH, if you do like the changes, and want to commit them to the trunk:

fossil commit -m "Before merging branch into trunk"
fossil update trunk
fossil merge experimental

4. Check what states the files are in:

fossil status

5. Commit the changes:
fossil commit -m "Merged changes from branch into trunk"

### Discarding changes to a file and retrieving a specific revision

1. First, find the list of revision numbers for the file:

fossil.exe finfo "myfile.txt"

History of myfile.txt
2011-05-26 [6ae687415f] some comment (user: Me, artifact: [a16a331cb0])
2011-05-26 [7091e0aaf4] some comment (user: Me, artifact: [750ae972b4])

The revision number is the alphanumeric data after the date, and revisions are in descending order (most recent on top).

2. To check out the first revision of the file:

fossil.exe revert -r 7091e0aaf4 "myfile.txt"
REVERTED: myfile.txt

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".

### Compare two revisions of a file

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:

1. fossil finfo myfile: Note the first hash, which is the UUID of the commit when the file was commited
2. fossil gdiff --from UUID#1 --to UUID#2 myfile.c

Note: If using the Windows GUI Fuel, note that release 2.0.0 can't diff a file that's been checked in; Diff only works between a revision in the repo and a live file in the workspace

Alternatively, you can use the web server by clicking on the timeline graph node.

To compare files between the work directory and those in a given branch:

fossil diff --brief --branch <branch name>

### Cancel changes and go back to prevision revision

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.

### Check out an older revision of a file

1. fossil.exe finfo myfile.txt: Note the first hash
2. fossil checkout ?VERSION, where ?VERSION is the first harsh

### Tell Fossil to stop watching a directory

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

fossil changes

fossil commit

### Finding information

#### To get the lists of commits made so far

fossil timeline

The list can be limited to the "-n" last commits (default: 20)

#### To get the files that were part of each commit

fossil timeline --showfiles

#### To get the list of changes made to a specific file

##### If the changes have not yet been commited

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"

##### If the changes have been commited

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

### Finding changes between two revisions of a file

#### Web UI

Open the repository, run "fossil ui", click on Timeline: To tell Fossil the two revisions you wish to compare, click on the timeline graph node for the first version (so that it gets a red dot in the center) then click on the timeline graph node for the second version. This will show all the changes made to all the files that were part of that revision.

Alternatively, click on the Files tab, choose the file you're interested in, and click on the revision number ("part of check-in [123]"): By default, it will show the changes made between the most recente revision and the one before last. If you want to diff between other versions, click on the graph nodes on the left.

? Is there a way to configure the text size in the web interface? By default, it's a bit too small to read.

#### WinMerge

CHECK

You might find a GUI differ more user-friendly than using the text-based version or even the web interface: 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.

Besides WinDiff and Tcl/Tk, you can try BeyondCompare (commercial), Kdiff3 (cross-platform), ExamDiff (commercial), Compare++ (commercial), etc.

To locate the UUID of two artifacts you want to compare, you must use the web UI.
CHECK : no way to type eg. "fossil ??command?? myfile.txt" and have WinMerge diff the last revision + current file?

fossil finfo index.html: Displays history

fossil gdiff index.html: Nothing happens; Doesn't start WinMerge

fossil settings: gdiff-command    (global) "C:\Program Files\WinMerge\WinMergeU.exe"

>fossil help gdiff

Usage: fossil diff|gdiff ?OPTIONS? ?FILE1? ?FILE2 ...?

Show the difference between the current version of each of the FILEs specified (as they exist on disk) and that same file as it was checked out.  Or if the FILE arguments are omitted, show the unsaved changes currently in the working check-out.

+ CMD and fossil.exe with autocompletion : foTAB > fossil, fossil gdTAB > fossil gdiff , fossil gdiff myfTAB > fossil gdiff myfile.txt

Since Fossil can't edit a revision, if you want to make changes to a file such as copying code from a previous revision, you'll have to check it out beforehand.

#### Tcl/Tk

1. Install Tcl/Tk package for Windows : www.activestate.com/activetcl
2. Run "fossil diff --tk": Shows you differences across multiple files, instead of just one file at a time like gdiff does.  And, one may reasonably expect that the --tk option will be enhanced in the future.

An alternative to plain Tcl/Tk + "diff --tk" is Eskill : http://eskil.tcl.tk/index.html/doc/trunk/htdocs/

#### Command line

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".

### Finding a piece of code in a file somewhere

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:

1. Grep through the files in the work directory, eg. grep stuff_Iam_looking_for *.c

Note: command-line grep for Windows is available in different versions

2. If not found, commit the work files if need be, and tell Fossil to check out the last commited file from the repository until you find what you are looking for: "fossil update prev", and goto 1
3. Finally, go back to the last revision: "fossil update latest"

### Merging previous version with current work file

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"

### Checking out two revisions of a file

In case you want to check out two revisions of the same file:

1. To find the revision numbers for a given file, run "fossil finfo myfile.txt". The "artifact ID", ie. the revision number is the first hash number
2. How to check out two versions? Add eg. their revision number to the filename?

### Tagging revisions

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'

OR

fossil timeline (note hash for revision you wish to tag)

fossil tag add initial_version hash_here

### Close the repository

fossil close

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.

### Closing the repository

fossile.exe close

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.

## Batch files

Here are a couple of batch files you can use to work with Fossil from an IDE such as VB.Net's.

### Add + commit new files

@echo off

C:\fossil.exe commit -m "Added file(s)"

### Revert a change

@echo off

set FileName=%~pnx1

set FileName=%FileName:~1%

set FileName=%FileName:\=/%

c:\fossil.exe revert "%FileName%"

echo "%FileName%"

set FileName=

c:\fossil.exe revert %1

## Windows GUIs

Unlike SQLite, why isn't Fossil split into a DLL + EXE? Short story: Get used to the CLI + web GUI ("fossil.exe ui"). For a GUI differ, configure Fossil to use WinMerge.

### Fuel

Last update: "2015/08/23 Fuel version 1.0.1 has been released."

Kostas Karanikolas' fuel-scm is one of the GUIs available for Windows.

File > Open will check out files from the repository and create a _FOSSIL_ file in the same directory where the repo file lives; 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"):

• Modified: Files monitored by Fossil (ie. that have been added and committed to the Fossil repo) that have been modified since the repo was opened
• Unchanged: Files that live in the repo, ie. not modified since opening the repo
• Unknow: Will scan the whole filesystem starting at the root of where the repo file lives. This is what you should choose if you want to adding and committing folders/files to the repository. If there are lot of folders and files, it could take a long time and freeze the UI in the meantime. Also, since the four options in the View menu are cumulative (ie. you can have all of them checked simultaneously) the scan will occur every time if you leave that option checked
• Ignored: files that you have told fossil to explicitly ignore

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.

### WinFossil

(.Net) Ingo Koch's WinFossil

Note: SharpFossil is a C# wrapper around Fossil to implement a GUI.

#### Settings

Expects repos to have .fsl extension: Change this in Settings.

#### Getting Started

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

#### Q&A's

Repositories: Difference between "Select Checkout", and "Open"

Can I remove menu items I will never need (Repositories: Clone, Push, Pull, Sync)?

### Integrating Fossil in MS Express 2010 IDE

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:

1. Tools > Settings > Expert Settings
2. Tools > External Tools, where the items in this list map to "External Tool X" that we'll add to our own Fossil menu later:
1. Rename the default "[New Tool 1]" to eg. "Commit"
2. Change Command to where Fossil is located eg. "c:\fossil.exe"
3. Change Arguments to "commit -m". The user will be prompted to type the comment that Commit expects
4. Set "Initial Directory" to point it to the work directory where the source files are currently checked out by Fossil (eg. c:\Workspace). It's also possible to use system variables such as "$(ProjectDir)" instead of hard-coding the path 5. Check "Prompt for arguments", since Commit requires typing a comment. Useless for commands like Changes that don't require arguments 6. Uncheck "Close on Exit", so we can see what Fossil says before closing the DOS box. Note that "Use Output Window" will display the output in a child window within the IDE instead of opening a DOS box 7. Click on OK 3. Tools > Customize > Commands 1. With "Menu bar = Menu Bar" selected, click on "Add New Menu". A new "Fossil" menu is displayed in the IDE's menu bar 2. Click on "Modify Selection" to rename it "Fossil", and 3. Use the "Move Down" button to move it lower in the list 4. Still in Customize dialog: In the "Menu bar" combo, select the new Fossil menu you just created, and Click on "Add Command...": From Categories, select Tools, and select "External Command 1". Click on Close. It's unfortunate that the IDE doesn't say which command maps to "External Command X". FWIW, here are the commands I added to the IDE: • Changes • Commit • Revert • Undo • Ls • Add, with "Initial Directory =$(ProjectDir)"

If you want to add a horizontal line to separate groups of commands, click on "Modify Selection" and select "Begin a Group".

### Fossil through Windows' context menu

As FastExplorer is deadware, let's also check Plexdata's ContextMenu.

CM is composed of three binaries:

• pdcmse.composer.exe: Application that creates the items to be added to Windows Explorer, and saves the file as XML
• pdcmse.composer.x64/pdcmse.composer.x86: Used by the composer
• pdcmse64.dll/pdcmse32.dll: COM DLLs used by Windows Explorer

Note: You just need to distribute the two DLLs and your XML file, and run ??? to register the files into the user's PC.

Let's go:

1. DOESN'T PREVENT CLOSING First, write a batch file to prevent the Fossil DOS box from closing by using a simple Pause line:

fossil.exe %1%
pause

2. Next, run the composer and hit New > Extension to create a new extension; Fill the Name and Description fields, and check which objects it should handle (Files and Folders)
3. Hit New > Menu Item to add an item called eg. "Fossil GUI"
4. Select this item and click on Edit
5. Within the Edit Menu Item dialog, add items. I chose to add Changes, Commit, Gdiff, Undo, Revert, and Add
6. Save the file through Save > Save, and hit Register to register those new items into the Registry
7. Open Windows Explorer, and right-click on folders and files to check that your extension works as planned.

#### FastExplorer 2008

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):

1. Create the following fossil.bat batch file next to where you put fossil.exe:

fossil.exe %1%
pause

2. Install and run Fast Explorer 2008
3. Click on Submenu Items
4. Make sure "Enable Dynamic Items" is checked
5. In the treelist in the left pane, select the Folder item
6. Item > Add Item
7. Select fossil.bat, and change "File Type" to "Folder", so that this menu is displayed only when right-clicking on a... folder
8. With the focus on this new Fossil item, click on Item > Add Item
9. Add a few commands, eg. changes, commit, add "%1%", revert, undo

Not a good solution:

1. Requires installing Fast Explorer
2. Adding "gdiff --from previous "%1"" for "All files": %1 is empty and includes drive letter, so Fossil will choke on it

#### TortoiseFossil

www.tortoisefossil.org

### My own very basic, shell extension-based FossilGUI

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):

1. Create a new key: HKEY_CLASSES_ROOT\Directory\shell\FossilTest\Command
2. Double-click on the "Default" key, and set its value to: C:\FossilGUI.exe "%1"

### vcs-ramdebugger

http://www.compassis.com/ramdebugger/vcs-ramdebugger:%20Version%20control%20system%20for%20fossil

### Jurassic-Fossil

(Java) jurassic-fossil

### SnailFossil

MacOS only

https://langui.net/snailfossil/

### Fossil GUI Project

Sami Tikka's Fossil GUI project for MacOS

## Recompiling Fossil

"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."

http://www.fossil-scm.org/fossil/doc/trunk/www/build.wiki

1. Install mingw ("a native software port of the GNU Compiler Collection (GCC) and GNU Binutils for use in the development of native Microsoft Windows applications") and msys ("Bourne Shell command line interpreter system offered as an alternative to Microsoft's cmd.exe"):

1. Download and run the GUI mingw-get-inst installer which will let you install MinGW and MSYS. Choose a directory with no spaces in its name, eg. c:\MinGW
2. Add C:\MinGW\bin; to the PATH environment variable ("The MinGW team do not recommend modifying the Windows PATH variable system wide. We prefer that you use a script to set PATH for the processes on a per session basis. This is the reason that we do not adjust the PATH"). If editing the system-wide PATH anyway, you need to reboot.

You MUST also add C:\MinGW\MSYS\1.0\bin to your path and reboot, or "make" won't be found

2. Unpack the latest Fossil development source tarball, which which includes Zlib so you don't have to download it separately
3. (Off by default) If you want to to use HTTPS, from the OpenSSL page, download and unzip Binaries + Developer files within c:\MinGW
4. Run:  make -f win/makefile.mingw
5. Put the resulting "fossil.exe" file somewhere on your path, and give it a try.

## Q&A

### Does fossil.exe support autcompletion?

As of August 2018, no.

But some commands are also available in short versions, eg. "fossil gd" for "fossil gdiff"

### How to change the web UI look?

Launch the server through "fossil ui"

https://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg27941.html

https://www.fossil-scm.org/index.html/doc/trunk/www/customskin.md

### Diffing with WinMerge?

When diffing two revisions in WinMerge, easy way to check out file to copy/paste code from older revision?

### No search to locate text in the repository?

https://www.fossil-scm.org/xfer/help?cmd=test-grep

http://www.fossil-scm.org/index.html/help?cmd=/srchsetup

https://www.fossil-scm.org/index.html/help?cmd=fts-config

### After moving Fossil to another host, "Cannot figure out who you are!"

C:\>fossil commit -m "Some comment"
Cannot figure out who you are!  Consider using the --user command line option, setting your USER environment variable, or setting a default user with "fossil user default USER". cannot determine user

Add the user through "fossil user new joe".

C:\>fossil user new Joe
C:\>fossil user default Joe

### What are the two hashes returned by "fossil finfo"?

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

### undo vs. revert?

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.

### "myfile.txt does not exist in checkin"

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

### "filename contains illegal characters"

Fossil only accepts characters in filenames that are valid on all the platforms it is compiled for. Here are those you cannot use:

http://www.fossil-scm.org/fossil/artifact/79bed8df57b?ln=419

### Shunned files still listed in "fossil ls"

Even after running Rebuild, the files are still listed :-/

### How to tell Fossil to stop watching a file?

"fossil remove myfile.txt" will stop versioning a file but keep all the versions commited so far.

### How to add files recursively?

#### Windows

for /r %i in (*.*) do fossil add "%i"

#### Linux

find . -type f -print0 | xargs -0 fossil add --

### How to exclude file extensions when adding files to a repo?

#### Linux

fossil add \$(find . -type f | sed -e '/\.exe/d;/\.dcu/d')

#### Windows

"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."

### Which VB.Net files can I safely ignore?

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:

bin/
obj/

#User Specific Files
*.user
*.suo

#Resource Caches
_ReSharper.*
*.sln.cache

What about "My Project"?

What Visual Studio files should be ignored by subversion to minimize conflicts?

• *.bin
• *.obj
• *.exe
• *.dll
• *.pch
• *.user
• *.suo
• *.tlb
• TestResults (VSTS unit test directory)

Note: If sharing projects with other users, add *.suo to the list of files to ignore since this file is user-specific.

### "missing file"

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".

### "already within an open tree rooted"

You tried to open the repository a second time.

### "there are unsaved changes in the current checkout"

Run "fossil commit" to check in changes, and re-run "fossil close" to close the repository.

### "fossil.exe ui: not within an open checkout"

You must first check out the files using "fossil open c:\myrepo" before being able to view it through the web server.

### How to contribute to the wiki

1. fossil clone http://fossil-scm.org fossil.fsl
2. mkdir fossil
3. cd fossil
4. fossil open ..\fossil.fsl