I've been using Fossil for over a couple weeks now, and I think long enough to cover some pain points of the software. This post will be a fairly negative view of Fossil, but it is not meant to convey derision or contention, but rather criticism. I believe anything I list here can be improved upon.¹

As a background: I've been using Git for around 17 years now. I don't know the exact date, but I recall that GitHub wasn't even a thing yet when I started using it. It was not my first experience with version control, that claim would instead go to CVS and Subversion (again, not sure which was “first,” but they both existed and I used them simultaneously). It has probably been 14-15 years since I've had the displeasure of needing to interact with CVS/Subversion; Git was such an obviously better piece of software that I happily adopted it, even with some of the early rough edges.

Since SQLite was originally managed with CVS, Fossil seems to take some of its interface and model cues from it, whereas Linus Torvalds designed Git with a mantra of “when in doubt, do the opposite of CVS.” These attitudes reflect in the design of both pieces of software, and sometimes to their detriment. I do think both Fossil and Git are excellent at their jobs, and while I can lob criticism at Git as well, it is inappropriate in this forum. :-)

Documentation

Amendment: I have been added to the shimpf-book repository and can possibly tackle the areas that I perceive the documentation to be lacking. I may also submit patches for the official repository Fossil is developed in (probably need to sign a CLA though).

Even early in its history, Git gained a gittutorial manual page, and later manual pages like gitworkflows and gitfaq. These serve as good introductions to the version control concepts of Git, and were essential in my earliest year or two of using the software.

Fossil's documentation is spartan by comparison. The Fossil Quick Start Guide places greater emphasis on cloning a remote repository than starting a new one, and dumps lists of Fossil sub-commands that can be run. Git's built-in tutorial is a much more practical example of starting a new repository and walking through individual concepts.

Among the various commands listed, the Quick Start Guide also points to fossil branch, which I think should not be encouraged as good practice. It is nevertheless an obvious command to use for branching, but as outlined in the Branching, Forking, Merging, and Tagging document, the more intended route of creating branches is on the first check-in that will be in a branch: fossil commit --branch $BRANCH. This is a mistake I have already made in my own repositories, creating independent “new branch” artifacts instead of waiting for the first commit on the branch. This quasi-mistake also shows up in the main Fossil repository from time to time, in this example, eight hours passed between the fossil branch new operation and the first fossil commit on the branch.

Overall, the documentation that exists is written very much from the perspective of Fossil developers and does not offer easy avenues for those that are new to version control, or even users of other VCSes. The reason that I had personally made the fossil branch new mistake is because I did not have an obvious clue in documents linked from the home page, that it was the wrong direction to take.

This is all piled on there being no good local documentation for Fossil, especially if a user does not elect to clone the main repository. The fossil(1) manual page is not more useful than fossil help, and many of the fossil help $SUBCOMMAND displays leave me scratching my head after reading them. (e.g. I don't have a slightest clue about how to use fossil ticket.)

As an aside: there are at least a couple places in the existing documentation where Fossil's encouragement for multiple working directories is compared to Git, with a claim that Git makes it difficult or impossible. This hasn't been true since the git worktree showed up in version 2.6.0, released in 2015. The primary difference that remains is that Fossil is designed to support multiple working trees as a standard development model, while Git is designed for only one. The difference manifests in using the two DVCSes in different ways by default, not by technical limitations.

Creating a new fossil repository is clunky

Amendment: This was, from the very beginning, my weakest point of critique. I still believe Git's usability edges out Fossil's in this particular circumstance, but Fossil is only barely worse here. It's a one-and-done, once you make the repository, you don't have to keep remaking it.

With Git, the normal form to starting a repository is to begin when it is needed. You may start with a few loose files, or perhaps importing an existing project (and not going through a VCS converter). Whichever the case, you may have a directory that looks like this:

.
├── hello.c
└── Makefile

To get from there to a Git repository with an initial commit, requires only these commands:

$ git init
$ git add .
$ git commit -m "Initial commit: Hello, world!"

Comparatively, Fossil's init/new command only creates the repository file, which is normally expected to be outside a working check-out repository. The following sequence is the shortest path to the equivalent operation:

$ fossil new ../hello.fossil
$ fossil open --force ../hello.fossil
$ fossil add .
$ fossil commit -m "Hello, world!"

While the difference is just one command, it introduces the burden of understanding the difference between the repository and check-out, and in this example, the burden of using --force (which may be shortened to -f, in fairness) so that Fossil will not complain about the non-empty initial directory that will become the first check-in. Extending fossil new to automatically open a populated directory might be enough to replicate the git init behavior.

Selecting portions of files à la git add -p is not simple

Amendment: Patches are welcomed to add the equivalent feature via automation of the fossil stash command. This may become a completely solved issue in the future.

This is one of Git's killer features, that made it extremely compelling to move away from the older version control systems of CVS and Subversion.

In short: you can be working on a few files, adding functions here and there, and decide that you need to split up the commits so that each commit represents only a single feature. With git add -p, you can select the blocks of each file to add to the staging area, and afterward, git commit will save only the parts that you had explicitly added.

The only option to achieve the same result in Fossil is to use fossil stash and it's just a worse user experience overall. It would be much more pleasant if Fossil could have similar functionality, committing parts of files instead of having to commit the entirety of a file's changes at once. This may make the addition of a staging area a necessity, which might be against Fossil’s philosophy.

Fossil records file renames, if you remember to do it in Fossil

Amendment: In a reply below, I reflected on the nature of object storage in Git and Fossil. This section was predominantly written on the assumption that Fossil should track renames through the OS-level, because Git lets you get away with it. Fossil doesn't use heuristics to detect renames, it just demands you to tell it you're renaming.

I retract this section of critique as such.

In Git, I can simply mv src/foo.c test/bar.c, my operating system command, and then by running git add ., it'll automatically delete the old name and add a new name to the staging tree that points to the same blob. Commands like git status, git diff, git show can represent this operation as a “rename.”

Git's dirty little secret: it doesn't track renames. There are heuristics to determine if a rename happened based on a file's similarity to a previous version of another file. In the commit itself, there are always independent remove and add events. This makes it happen to work rather well if you use the normal mv command instead of git mv.

Fossil actually tracks file renames, but you must use fossil mv to perform them. Managing the files purely on the OS side, and using fossil add, will not result in the same view as in former command.

“Fossil Never Auto-Commits” causes needless busy work

Amendment: The primary reason merges are not auto-committed seems to be connected to two facets: (mostly) indestructible history, and autosync. The first part does have an exception (the fossil purge command, plus you could backup your repository file...), but the second part is harder to overcome, unless you turn it off. With Git, you can perform the git merge $BRANCH1 $BRANCH2 command, it'll automatically create a merge commit (and by default, show an editor window if you really want to edit the message), and that'll be that, your local repository has a new state. Without autosync, you can proceed to test the merged branch, and Git encourages you to amend the commit with code changes as needed, before pushing to any remotes.

The scale of repositories between Git and Fossil may make the “busy work” less of an issue than I made it seem. Git is designed for very large projects, with thousands of developers and multiple levels of hierarchy (aka, Linux). Linus Torvalds needs to perform dozens of merges per day, implicitly trusting his immediate subcommanders have already put in the work of verifying it to be working code.

Fossil is designed for much smaller teams (aka, SQLite). Merges are rare enough that performing the operation a few times a week is no big deal for having to type out a commit message after testing has been done.

I can get used to having to type out “Merged $BRANCH into trunk”, but if an automatically-generated commit message were made possible without auto-committing, I believe that might bring a “best of both worlds” balance to this critique.

In Fossil: Git to Fossil Translation Guide, this point is brought up as a benefit, but I'll argue that it does a detriment to the software.

Merging two branches is a frequent operation in modern version control systems, neither Git nor Fossil are an exception to this. When fossil merge is performed, Fossil dutifully grafts the branches together into the check-out's branch, and then leaves the check-out in a status that requires an additional fossil commit. It is rare that a merge check-in needs to be further edited, and no helpful message text is pre-filled, causing tedium when doing it yourself. git merge, on the other hand, defaults to performing the commit and opens an editor window pre-filled with a message such as Merge branch 'foo' of bar; this behavior can be inhibited with a --no-commit flag, making Git behave like Fossil. In 17 years, I've desired to suppress the automatic commit exactly zero times (maybe someone can come up with an anecdote where it was useful, but I cannot).

With check-ins in the main Fossil repository like 20250325015711z, 20250320211305z, 20250314095336z (taking a few examples from the current timeline), it doesn't appear that fossil merge leaving the status hanging for a manual commit bears out an advantage. Instead, a message like “Merge from trunk” is written manually and it's done with extra steps. With the ability to use fossil amend (or the WebUI action of “editing” a commit), an automatic commit and commit message could be nice, Fossil leaves open the possibility to edit it if desired.

Autosync is less than fully automatic

Autosync seems to only apply to operations that directly affect the versioned tree, such as fossil update, fossil commit, fossil branch. Making edits to the wiki, forum, and tickets through the WebUI are not automatically synchronized and require a manual fossil sync (or fossil push) to get out to a remote server.

fossil grep is worse than git grep

Amendment: It has been pointed out that fossil grep searches all historical versions of files passed to it. Neat, perhaps, but I don’t think that makes a strong usability case (I have rarely used git log -p to perform a similar task in Git). I can just get used to using standard grep (or alike programs), but I still think git grep is superior.

I'm not even sure what this command is for, except perhaps to give Windows users a working grep program. git grep is simple: you can type git grep $PATTERN and it automatically searches the contents of the current check-out, and quickly. It is easy and convenient.

fossil grep on the other hand still requires a file specification at the end, and at that point, why not just use the normal grep command (assuming a Unix environment)?

---

1. ^{^} With due respect, I know this is a long post, I had been drafting it over a few days. In this footnote, I'll at least sing a praise of Fossil: to accomplish drafting this forum post, I created a new repository just to use the forum by myself, and make sure all the formatting comes out good. I do have more praises to sing of the software, but that's not the purpose of the post (nor support forums in general…).

Selecting portions of files à la git add -p is not simple

I'd like to see that, too. In fossil philosophy, an approach would be to automatically stash the change set, except for the parts you want to include. Then you have the selected changes only in the working directory, and can run the test suite. Then check-in, and pop the rest of the change set back from the stash.

The issue with the unit tests is why the feature currently doesn't exist. You cannot run tests against the state captured by partial check-ins. The captured change set didn't exist on disk as-checked-in, so you cannot assert that the check-in actually works.

“Fossil Never Auto-Commits” causes needless busy work

On all of my projects with test suites, I run the unit tests between merge and commit. Especially when there were multiple check-ins on both sides, interface changes can break the merge, even if both branch heads work independently. As an example, think of branch A removing a redundant method parameter, while adding a call to that method on branch B, where it still includes the parameter. The merge cannot detect this (as code on branch B is new and independent), introducing breakage.

So running the tests or at least compiling the project should catch this. Auto-commit merges is something I'd disable immediately.

“Fossil Never Auto-Commits” causes needless busy work

On all of my projects with test suites, I run the unit tests between merge and commit. Especially when there were multiple check-ins on both sides, interface changes can break the merge, even if both branch heads work independently. As an example, think of branch A removing a redundant method parameter, while adding a call to that method on branch B, where it still includes the parameter. The merge cannot detect this (as code on branch B is new and independent), introducing breakage.

So running the tests or at least compiling the project should catch this. Auto-commit merges is something I'd disable immediately.

I had not considered this perspective, and I think it's probably influenced by autosync (correct me if I'm wrong). In Git, there is no autosync, which may offer greater freedom to run the tests and re-do the merge commit if necessary, before pushing it out to a remote.

Thanks for the counterpoint, I appreciate it :)

I'd like to see [git add -p], too.

I'd be willing to accept a -p option on "fossil stash save" or on "fossil stash apply" or similar. In other words, if you want to stash some subset of your local edits, or apply some subset of the edits in a stash to your local checkout, then I have no problem with that. Simply submit your proposed patch to implement the same and it will be given due consideration. However, committing untested changes is frowned upon in Fossil, and so a "fossil commit -p" option is far less likely to be accepted.

These are the main points of Swanson's essay, from my perspective:

1. Fossil documentation is written by and for Fossil users, not Git users
2. The fact that repositories are distinct from checkouts in Fossil means that you have two commands, not just one, to get a new project started in Fossil.
3. The lack of something like "git add -p" makes it more difficult to commit untested code.
4. It's hard to remember to do "fossil mv" when renaming a file; it is much easier to remember to do "git add .." since you are doing that all the time, anyhow.
5. Fossil's lack of auto-commit makes it more difficult to commit untested code.
6. Auto-sync only works from the command-line, not from the web interface.
7. The "fossil grep" command works across all historical versions of a single file, rather than across all files in the current checkout, which is different from what I expected.

1. Fossil documentation is written by and for Fossil users, not Git users

It is okay to keep the exiting Fossil Versus Git and Git to Fossil Translation Guide as the only references and comparisons to Git. I suspect that with Git's market prominence, it will be the overwhelmingly majority source of users migrating from another VCS.

Beyond that, I think Fossil's documentation is possibly written by those too close to the software, and may need to be expanded for people that are unfamiliar with Fossil, or unfamiliar with VCS altogether (it is important to consider those that choose to use Fossil as their first). spindrift made a suggestion in a sibling reply that I might be one to start editing the docs. I think it'll take more time than this post took, but it is always more rewarding to build up than making critiques.

3. The lack of something like "git add -p" makes it more difficult to commit untested code.

I tried to make the opposite case, but I think I was not clear. git add -p enables you to commit only working code, and code relevant to the commit topic itself. Granted, it probably does increase the risk of individual commits being broken. Hypothetically, Git's lack of autosync and git rebase -i would allow you to test the entire change-set and fix it before pushing, but I've never bothered with that, and I'd be surprised if anybody makes it regular practice while using fine-grained patch additions.

4. It's hard to remember to do "fossil mv" when renaming a file; it is much easier to remember to do "git add .." since you are doing that all the time, anyhow.

Partly, yes, but also that the two routes of operation are treated as distinct courses of action, whereas in Git, using git mv foo.c bar.c and OS-level mv foo.c bar.c && git add foo.c bar.c would be effectively the same course of action. It's a minor nitpick, but (I have not investigated deeply) perhaps it'll affect how fossil blame works.

7. The "fossil grep" command works across all historical versions of a single file, rather than across all files in the current checkout, which is different from what I expected.

That's actually pretty cool, but I think the burden of needing a filespec still places it as more cumbersome utility than regular grep. Not sure how I missed the historical part of it, it's right there in fossil help grep after all. :-)

\4. It's hard to remember to do "`fossil mv`" when renaming a file; it is much easier
   to remember to do "`git add ..`" since you are doing that all the time, anyhow.

Partly, yes, but also that the two routes of operation are treated as distinct courses of action, whereas in Git, using `git mv foo.c bar.c` and OS-level `mv foo.c bar.c && git add foo.c bar.c` would be effectively the same course of action.

fossil mv and OS mv are different animals. It is easy to overlook a detail of the Fossil data model: unlike Git, the unique identifier for a file is not it's name but a system generated id. The (current) name on disk is an attribute associated with that id. fossil mv records an intention to modify that attribute.

So to compare Git and Fossil: in Git when you rename a file you have to stitch together seperate histories in order to see the full picture (I believe that git mv may do something towards that, but the docs I looked at are not clear - I am only an occasional git user and had not seen git mv before). In Fossil there is only one history which includes a rename.

Incidentally when you say

`git mv foo.c bar.c` and OS-level `mv foo.c bar.c && git add foo.c bar.c` would be effectively the same course of action

is that a typo? Surely you are removing foo.c, not adding it? Or does Git read this as 'adding a file that isn't there'?

unlike Git, the unique identifier for a file is not it's name but a system generated id.

That's actually not Git's unique identifier either, it is the hash of the blob the "file" references. The contents of files are hashed and stored as blobs, and then tree objects can assign links from file names to the blobs. There is no actual rename operation in Git, but some commands (like git diff, git show, git log) compare blobs referenced by the trees to determine if they are similar enough to be considered a rename. The easiest case, of course, is when blobs have the same hash, but two trees reference it with different names. And since the heuristics can generate false positives and false negatives, the commands offer the -M parameter to tweak the similarity level that would make it output as being a rename.¹

All git mv does is create a new tree object where the old name is unlinked from a blob, and a new name is linked to it.

Incidentally when you say

`git mv foo.c bar.c` and OS-level `mv foo.c bar.c && git add foo.c bar.c` would be effectively the same course of action

is that a typo? Surely you are removing foo.c, not adding it? Or does Git read this as 'adding a file that isn't there'?

It is not a typo. You can use git rm if you want, but if you use git add $DELETED_FILE, the add command will see that there's no such file and remove it from the tree being built. I can see the confusion, I've been using Git since before git rm was added. git add still does the same thing it always has, and so it's the only command I bother to use.

---

1. ^{^} Actually I think I've just convinced myself that Fossil's system is better. You have to actually rename files in Fossil to show up as renames. No heuristics, it just reports what was actually done.

You can always use "fossil mv OLDNAME NEWNAME --hard", then you don't have to rely on the OS to mv the file.

Similarly, enabling the mv-rm-files setting causes "fossil mv" to default to --hard.

To enable it globally, do:

$ fossil set -g mv-rm-files 1

yes, just wanted to point that out, too :).

AFAIAC, this is a desirable "always on" setting. I really wonder whether it should not become the default at some point in the future? decoupling renaming of tracked files in the checkout (on the file system level) from notifying fossil of the rename never has made real sense to me, I admit.

semi-off-topic: any plans to make commands like finfo or grep work across renames in the future? it is a really pity that this seems not to be possible right now although fossil obviously "knows" about the rename...

I really wonder whether it [mv-rm-files] should not become the default at some point in the future?

It probably should, but there's been no concentrated effort to make that so. All causes require a champion.

semi-off-topic: any plans to make commands like finfo or grep work across renames in the future?

Plans, no, but patches will be thoughtfully considered :).

It probably should, but there's been no concentrated effort to make that so. All causes require a champion.

if you agree: how about you, then? :) or how about a vote within the core group? it is quite hard for me to imagine a scenario where the "decoupled" behaviour is actually desirable (let alone the generally preferable one): why should users regularly want to rename a tracked file on the file system level w/o telling fossil of the rename?

Plans, no, but patches will be thoughtfully considered :).

always a valid answer (I was expecting it ;)). however, it is used somewhat "reflexively" in the fossil community in my view: of course the group of users that would be realistically able to implement this themselves in finite time (or at all) is a small subset of all fossil users (and I am not part of that subset I'd say ;)).

so I just wonder how difficult/time consuming it would be to do for someone in the know. naively (probably) it seems that all the information is there and "crossing" the rename should be straightforward? but the fact that it has not been done so far seems to imply that it is actually complicated?

personally, I have always found absence of this ability the most obvious shortcoming of fossil compared to some competitors (mercurial, say). it really makes me use renames only very reluctantly, even where they would be really desirable for one reason or another, for the sole reason that I do not want to loose the ability to grep through (or even only view) the full history of the concerned file. functionality-wise the current state of affairs is mostly (not quite, sure) equivalent to a situation where fossil wouldn't support renames at all and one would have to remove the "old" file from the repro and to add/checkin the renamed file as "new": history of "old" file stops at rename, history of "new" file starts at rename.

but if it does not happen, so be it :).

if you agree: how about you, then? :)

Because i'm not currently willing to take on the outrage from folks who complain that that change breaks their workflows ;). It's a tiny code change with the potential for disproportionately large debate, which places it in my personal pile of "if it ain't broke, don't fix it." (That said, anyone making that change would get no push-back from me.)

it is quite hard for me to imagine a scenario where the "decoupled" behaviour is actually desirable (let alone the generally preferable one)

FWIW, agreed entirely. The current default is historical, from a time before fossil had the ability to do the filesystem-level part of moving/renaming files.

however, it is used somewhat "reflexively" in the fossil community in my view:

Possibly mostly from me, and it's intended to suggest that the feature in question would be welcomed (at least by me) but that time, energy, and motivation are real constraints for all of our volunteers.

Fossil's features are almost exclusively added by people either scratching a personal itch or who are intrigued by a particular feature request. Perhaps someone seeing your request will be intrigued enough by it to take that on.

so I just wonder how difficult/time consuming it would be to do for someone in the know. naively (probably) it seems that all the information is there and "crossing" the rename should be straightforward?

Conceptually straightforward, but the devil is in the details. As you say...

but the fact that it has not been done so far seems to imply that it is actually complicated?

Presumably so, but it's not a failing which has ever bothered me enough to go investigate it. However, see the note above about personal itches and feature requests.

Here's a 10 yo pretty long mailing list thread on this subject.

I'm not sure if we've reached a better consensus 10 years later.

neither am I. :).

since the behaviour can be configured in settings (especially on a global level, as stephan pointed out) it is of course a curable problem/issue on a per user basis -- if you know about the issue etc. that's why it does not bother me personally anymore (it sure caught me by surprise when first encountering this).

but I would argue that for new fossil users (most of whom will have been previously exposed to other VCSes) the current default behaviour (mv --soft rather than mv --hard) is for sure not "least surprise" behaviour. that in itself would seem to justify to change the default. and long time users that disagree and prefer the legacy behaviour could change their global settings instead, no?

I really wonder whether it [mv-rm-files] should not become the default at some point in the future?

It probably should, but there's been no concentrated effort to make that so.

If not changing the default, then maybe at least a heuristic for fossil mv: if the source does not exists in workdir, but the destination does, then do the "soft" move (just like with current default), but when the source exists and the destination does not, then do the "hard" move? In all other situations (when both exist or both do not), then do the default kind of move.

could work but I find this sort of "clever" behaviour (sometimes doing mv --hard, sometimes mv --soft) prone to cause confusion more often than not :). so personally I would vote for "do what subversion and mercurial do" (git, too, probably -- although that might be considered a counter-argument in itself ;)), i.e. provide a mv command to fossil that renames files in the checkout and as a "side effect" notifies the VCS of the rename (mv --hard). being able to handle the "decoupled" case (renaming at file system level and notifying the VCS after the fact: mv --soft) sure might be considered a feature and be kept (I think subversion and mercurial at least can't do that) but the default should be changed from the current mv --soft to mv --hard AFAIAC.

It makes sense to me. I want Fossil to report to me when a file has been removed, rather than automatically assume that I actually intended to have it be renamed.

does this need/wish interfere with fossil mv acting per default as fossil mv --hard rather than as fossil mv --soft? when first encountering revision control (with svn in my case) I was advised to strictly remember to use svn mv rather than to do file system level mv for the obvious reason that the rename should be done "under control" of the VCS. not adhering to this approach simply was an error/oversight. mercurial behaved the same. it seems only fossil disagrees that mv should by default always affect the repo and the file system simultaneously (by default, anyway) and I continue to not understand why this is a wise decision :).

There are some historical discussions on this I believe.

I guess that's true. I seem to recall I've asked the same question ≈10y ago :)

With Fossil at the very least, file renames I think are considered a rare event.

can't say. but depending on the project/context it sure does happen often enough, so it is an issue rather than a non-issue in my view.

best, joerg

Just by way of making sure you have at least some reply to your thoughtfully crafted post:

I honestly don't recognise any of the critisms you raise as issues on a day to day basis.

There is a central core of "fossil does things differently than git" which I'm sure you would agree is simply a matter of personal opinion and style.

New repositories for example - I have never created them the way you seem to suggest. I have always created and opened the repository first and then started creating files in the new, empty directory.

I read the documentation when I first started using fossil, and found it precise, unambiguous, and comprehensive.

I read the instructions on the use of branches, and opened a new branch when checking in the first set of changed on that branch, and never created it beforehand.

Much of this is because, I suspect, I've never used git, so I don't have comparative assumptions.

From that perspective most of your criticisms rather evaporate, I think.

Equally in terms of fossil grep - exactly as you have stated, on Linux I have simply never used it.

On windows it is incredibly useful to have.

My muscle memory (obviously) adds a filespec to any grep command... because I'm just using grep.

So the issues you consider just have never occured to me.

I think you are correct that a comprehensive new user guide could be improved.

Perhaps you are in the perfect position to formulate one?

The conflicts you have identified and overcome are really valuable for anyone else taking the same route that you have done to get to this point, and I'm sure would be well written and hopefully well received.

That's the main takeaway, for me at least, from your post.

Regards,

S

Just by way of making sure you have at least some reply to your thoughtfully crafted post:

Hah. More fool me for not noticing I hadn't refreshed the thread for a couple of hours before replying... 😆

Much of this is because, I suspect, I've never used git, so I don't have comparative assumptions.

From that perspective most of your criticisms rather evaporate, I think.

It's very possible I've developed a Git-shaped brain, so I definitely did not plan to convey anything otherwise. There are a lot of other usage differences between the two software, but most of them are different commands, or different parameters. To put it blunt too, the fact that Fossil is an entire forge in one would make it compelling even if Fossil were significantly worse than just the points I've brought up.

I don't have much else to add to my reply, with apologies. I think I've already covered things in sibling replies, and I have already been enlightened to use cases I had not considered.

Equally in terms of fossil grep - exactly as you have stated, on Linux I have simply never used it. <…>

My muscle memory (obviously) adds a filespec to any grep command... because I'm just using grep.

I beg to disagree for these reasons:

• git grep is much faster that grep on Linux-provided filesystems, even when they are on an NVMe device.

• The point of git grep is to search the whole source tree, so you do not know what files to search, IOW it's much more akin to

  grep -r .
  

  …which I and people around me use all the time. I do not know whether this option -r (--recursive) is a feature specific to GNU grep but anyway.

  Also note that all those "grep killers" such as ripgrep, ag etc concentrate exactly on searching through a heap of files, as the task of searching through a single file is a non-problem: it's handled just okay with a plain GNU grep ;-)

All-in-all, I would say, I would have been equally confused to learn that $VCS grep by default pefrorms a "depth" search through a file (or a set of files) rather than shallow search through all the files in the current tip commit.

The Fossil Quick Start Guide places greater emphasis on cloning a remote repository than starting a new one

I've just expanded the relevant section. With the understanding that we wish to avoid the tl;dr problem in this particular doc more than any other doc in the tree short of the main index page, does this purposely-brief addition cover your concern?

fossil branch…should not be encouraged as good practice

I agree. While I do believe the prior text already made that point adequately, I have nevertheless made the point stronger.

Overall, the documentation that exists is written very much from the perspective of Fossil developers and does not offer easy avenues for those that are new to version control, or even users of other VCSes.

That gap is filled by the Schimpf book. I don't keep up with the 3rd edition efforts, having lost my beginner's mind with respect to Fossil long ago, but I expect you will find it more valuable to start with than chasing through the current task-focused "official" docs.

there are at least a couple places in the existing documentation where Fossil's encouragement for multiple working directories is compared to Git, with a claim that Git makes it difficult or impossible

I thought we had clarified all those obsolete points by mentioning git worktree while continuing to point out that the switch-in-place workflow remains the least-effort and best-documented path with Git. Defaults matter.

I would appreciate having direct citations rather than being sent on an open-ended chase through docs you have been through more recently than I. 🤓

With git add -p…

That's covered in the docs here, including multiple solutions.

The bright line we will not cross is direct commits of partial, untested changes. The Fossil way is to give you the option to test each change before making a commitment out of it, a philosophy that falls directly out of its autosync-by-default nature. We argue the virtues of this in the Fossil Versus Git doc.

Fossil records file renames, if you remember to do it in Fossil

At risk of sounding glib, develop the habit, then.

In Fossil: Git to Fossil Translation Guide, this point is brought up as a benefit, but I'll argue that it does a detriment to the software.

We'll have to agree to disagree since, to a first approximation, I wrote that doc, and I would not have made those philosophical claims if I believed they were indefensible.

it automatically searches the contents of the current check-out, and quickly

If that's what you're after, I highly recommend ag. There are alternatives, some of which are referenced on that linked page.

I've just expanded the relevant section. With the understanding that we wish to avoid the tl;dr problem in this particular doc more than any other doc in the tree short of the main index page, does this purposely-brief addition cover your concern?

I believe it does, thanks and well done.

fossil branch…should not be encouraged as good practice

I agree. While I do believe the prior text already made that point adequately, I have nevertheless made the point stronger.

(Amendment: the below paragraph is obsolete as of 2025-03-30 18:40:06.)

I wonder if the mere existence of fossil branch new is a problem, or at least that it's displayed in the standard help text. I don't have the problem with other subcommands of fossil branch (I think I was unclear on this in my first post). I am unsure of the real solution to it, I can imagine desirability in creating a branch explicitly before commit, especially if you operate on the repository file directly before making a directory to do fossil open $BRANCH. At the same time, you can just do fossil open $VERSION and wait to create the branch as-needed. With the extreme care to backwards compatibility from the SQLite and Fossil teams (as much overlap as there is), it is hard to imagine fossil branch new actually going away.

Relatedly, I think the Quick Start Guide should only be mentioning commands in the standard fossil help,not fossil help -a, output. The only strangler I know of is the mention of fossil checkout.

That gap is filled by the Schimpf book. I don't keep up with the 3rd edition efforts, having lost my beginner's mind with respect to Fossil long ago, but I expect you will find it more valuable to start with than chasing through the current task-focused "official" docs.

It might be worth finding out if I could contribute to the 3rd edition. :)

I thought we had clarified all those obsolete points by mentioning git worktree while continuing to point out that the switch-in-place workflow remains the least-effort and best-documented path with Git. Defaults matter.

I would appreciate having direct citations rather than being sent on an open-ended chase through docs you have been through more recently than I. 🤓

In the Git to Fossil Translation Guide, I don't think obsolete hacks around a former Git limitation is worth mentioning, a limitation that has not existed for over 10 years at this point. I believe removing mentions of symlinking the git repository is unnecessary, and it could start out just with the mention and comparison to the git worktree feature. I do believe Fossil still makes a strong usability case compared to the Git feature.

In Fossil Versus Git, the section places much greater emphasis on the philosophical and practical differences between how both VCSes treat default workflows, though I think a link to a search engine as evidence for Git's failings is about as useful as an "open-ended chase" is. Both sections 2.5.3 and 2.6 link to a dispute to the claims in a separate forum post, this link should be removed with a text revision.

Fossil records file renames, if you remember to do it in Fossil

At risk of sounding glib, develop the habit, then.

This is probably the correct answer. My Git-shaped brain causes me to treat OS-level and VCS-level renames as the same thing, and Fossil just isn't like that.

If that's what you're after, I highly recommend ag. There are alternatives, some of which are referenced on that linked page.

I already use rg, but thanks. The core was more that fossil grep doesn't present much apparent utility over bare OS commands. drh pointed out to me that it also searches all historical versions of files too, which does cause it to provide a similar utility that I've performed in git with git log -p and using less's search functionality, but the action is rare enough that I don't see myself using it much.

I wonder if the mere existence of fossil branch new is a problem, or at least that it's displayed in the standard help text.

"branch new" predates the "ci -b ..." flag by (IIRC) several years. Early on in fossil's development, that was how all new branches were created. It's still "not wrong" to do so, but "ci -b ..." is not only more convenient, but lets you delay the decision of whether or not to create a branch until the first code would be checked in for that branch. Perhaps you want to throw it away or check it in to the current branch, in which cases a premature "branch new" leaves cruft lying around.

It might be worth finding out if I could contribute to the 3rd edition. :)

You may! Unlike the main source repo, that one does not require a copyright waiver. i'll set you up an account using the same user info as you have on file here and email you the login info.

But how many people in Git actually use "git worktree" for anything? I would venture to guess that 90% of git users don't use it.

I can vouch that I use it, primarily to track different MAME forks that are pulled into the same local repository. Contrary to the current “Fossil Versus Git” text, the old limitations that are painted as downsides of using git worktree no longer apply. They appear as fully functional trees from the Git side. fetch works, pull works, et al.

Maybe most don't. I have yet to utilize Fossil's multiple-check-out model either, I find that using "fossil up" to switch around versions fits my existing pattern fine. I think it's OK that both VCSes can accommodate both styles. :)

Now, I wonder, is there a config option for it so I can enable it by default in .gitconfig? I've always been annoyed by Git's behavior with respect to merges, now I know it can actually do better.

Looking at man git-config, it doesn't appear such an option presently exists. It probably would not be hard to make one.

Are you saying that with --no-commit that it will perform the merge, but leave the files

Don't forget to add --no-ff, since fast-foward will always commit.

is there a config option for it so I can enable it by default in .gitconfig?

There is:

[merge]
    ff = no
    commit = no

Reading through that question, it is more complicated^Git-TM, so I'll leave it to the Git gurus.

Don't forget to add --no-ff, since fast-foward will always commit.

There may be a slight terminological problem: the so-called "fast-forward" merge is neither a merge nor a commit.
Basically, when you have a source branch ...-> A -> B -> C -> D and a destination branch ...-> A -> B, merging the former into the latter in Git will, by default, result in a fast-forward because the source branch fully contains the destination branch (in the graph theory parlance) and hence it's possible to merely update the destination's branch tip to point at D.
As you can see, there's no commit created when fast-forwarding, and while people are colloquially using the term "fast-forward merge", it's not really a merge, it's just "fast-forwarding" (of the tip of a branch to the tip of another branch).

The --no-ff option can be used to defeat this behaviour, and, if it were to be used in the case being discussed, if would create a so-called "bubble merge" — referring to how a merged side branch look in a typical visualization: its history line starts and ends at the same point on the history line of the base branch.
In this case, the commit is created, and it's a merge commit as it has multiple parents.

This wasn't part of the critique, but a recognition that Git and Fossil have fundamental differences and trying to make Fossil into Git isn't going to fly.

Actually everything being in a SQL database has a lot of appeal to me. I'm fairly familiar with Git's file structure, but some parts of it (like pack files) are intentionally difficult just for performance reasons. Fossil doesn't have the same problem, even though I don't really have an understanding of SQLite's file format; not that I can't learn, but I just don't need to. If it ever comes to a point I want to throw SQL commands at the repository, I know that I can do that.

Ha, well you just taught me that git commit $FILE is a thing. I had no idea. I knew about git commit -a, but I never use it, I feel far more comfortable with preparing a staged tree before shooting off to commit it.

With due respect, I know this is a long post, I had been drafting it over a few days. In this footnote, I'll at least sing a praise of Fossil: to accomplish drafting this forum post, I created a new repository just to use the forum by myself, and make sure all the formatting comes out good. I do have more praises to sing of the software, but that's not the purpose of the post (nor support forums in general…).

Tip: /wikiedit/Sandbox is a convenient way to draft long forum posts, and they will persist using JavaScript's "localStorage" (it saves every time the editor input field loses focus). That wiki page is special, in that it is intended solely for experimentation with the wiki and any attempts to save it will fail.

That's pretty cool, but I think I trust Fossil a lot more to not lose my data than my web browser. :)

...As a background: I've been using Git for around 17 years now.

Just makes me wonder why not just keep on using Git?

VCS is not some magic tool, it's just a utility for coordinated backup of mostly text files. If Git is in your muscle memory -- so why wasting time/effort to deal with another utility? Molding Fossil into Git is equally wasteful.

If your project benefits from Git -- have it installed and configured. Fossil's main advantage (in my experience) is that it does not need installation, just one local binary. Fossil has other nice points, but on a project level lots of tools integrate with Git so, operationally, users may not care much to known the nitty-gritty of whatever VCS beyond the basics.

Just makes me wonder why not just keep on using Git?

I have no plans to stop using Git, both for projects that aren’t mine, and for projects where the bazaar style of development is desired. I bring up my background as a point for where my comparisons are coming from.

VCS is not some magic tool, it's just a utility for coordinated backup of mostly text files. If Git is in your muscle memory -- so why wasting time/effort to deal with another utility? Molding Fossil into Git is equally wasteful.

VCSes are so much more than "just a utility for coordinated backup"—in my experience, those that treat them as such are always the ones landing into problems. VCSes should be a tool to assist in software development, especially to the point that they offer nearly fearless editing of source code.

Fossil is compelling and desirable because it is the entire forge rolled into one managed repository. The bug tracker, wiki, and forum are all really big deals. It’s true, if Fossil were only the code tracking component, I likely would not bother, but all the other features make the difference in that component worth it.

I do not intend to “Mold Fossil into Git.” There are design decisions I do not agree with (eg, Rebase Considered Harmful), but where there is a clear philosophy and intent, I do not bring it up, I already know there’s a hard no on that. But on the points, especially for comparison, I believe Git performs tasks better than Fossil without any real philosophical/design driven reason behind them, I would prefer Fossil to improve.

Actually, on the opposite side, I would like to see Git become more like Fossil and integrate forge features. It is unlikely to ever happen in upstream, but Git is flexible enough that it’s easy to imagine implementing almost all of Fossil's forge features in the form of specialized branches. git-bug is an example of doing exactly this. It is not the first of its kind, I remember several competitors before GitHub came along with its “let’s copy SourceForge, but make it for Git” and it won the marketshare, detached forge and all.

Fossil's main advantage (in my experience) is that it does not need installation, just one local binary.

Probably good for Windows (and Mac OS X?) users, but for me, apt install git and apt install fossil are effectively the same operation, and I don't need to know how many files Git installs versus Fossil. :)

But on the points, especially for comparison, I believe Git performs tasks better than Fossil without any real philosophical/design driven reason behind them, I would prefer Fossil to improve.

The emboldened part sounds so utterly weird and alien to me that I'm really curious. I know I'm a mere observer, but could you list some of those tasks for easy reference?

That was the whole point of the post that started the thread, but some other things on my mind:

• git show makes it easy to display the diffs of commits on the terminal. As far as I know, Fossil only really offers the WebUI for the same functionality.
• Git allows easy relative names for commits. Perhaps related to the above point, but Git lets you use identifiers like HEAD^ to refer to the parent of the current check-out, you can also use HEAD~n for the n-th parent of the check-out. This syntax expands for branch and tag names. Fossil appears to be much more focused on using the WebUI for these operations, and it’s just missing on the command line.
• Overall, there seems to be a lot more focus on providing functionality via the WebUI instead of terminal. For some features (tickets, wiki, forum), this makes sense, but some fairly core versioned-code features that Git offers a terminal experience for, Fossil doesn’t. fnc appears to be the way to bridge this divide.
• fossil timeline defaults to displaying history starting at the tip of the repository, whereas git log displays history starting from the current HEAD. fossil timeline current is the closest equivalent to git log. (This is something that actually was in my earlier drafts, I removed it because I did not feel confident in the critique; it’s hard to avoid the feeling of “I don’t like things that are different.”)

git show makes it easy to display the diffs of commits on the terminal. As far as I know, Fossil only really offers the WebUI for the same functionality.

$ fossil diff

or a hybrid approach:

$ fossil diff -by

:-?

Git allows easy relative names for commits. Perhaps related to the above point, but Git lets you use identifiers like HEAD^ to refer to the parent of the current check-out

That topic came up a decade or more ago and it didn't go anywhere because (IIRC, which might not be correct) that approach breaks down once you have multiple merges and branches. e.g. saying "back up one version" is ambiguous if you have two merge parents. Perhaps someone else has a clearer recollection of that discussion (or perhaps Martin G., our expert data archeologist, can find it in the old email archives).

Overall, there seems to be a lot more focus on providing functionality via the WebUI instead of terminal.

Kinda. Fossil's initial and primary purpose in life is to support sqlite's development. The sqlite devs work exclusively from plain text editors (be it emacs, vi, or "e.tcl" (Richard's home-grown one)), so fossil definitely has a strong CLI focus. Some things are simply easier to use with the UI, though, and that's where the development goes. e.g the /timeline web page is easily fossil's single most complex component, and there's little motivation to attempt to replicate more than the most basic of its features in the UI.

fossil timeline defaults to displaying history starting at the tip of the repository, whereas git log displays history starting from the current HEAD.

You're presumably talking about the CLI there, as "the current head" means little without a checkout (where the head is defined, whereas without a checkout, "current" doesn't mean anything to fossil). Assuming that's the case...

There's no accounting for taste! The timeline CLI command has a --branch flag which can limit its output to one specific branch, or, more simply the -c|--current-branch flag works like --branch NAME_OF_CURRENT_BRANCH.

$ fossil diff

or a hybrid approach:

$ fossil diff -by

:-?

That doesn't seem to do the job at all, if you could provide a usage example, it might help enlighten me.

Edit the third: Looks like the equivalent command to git show is fossil diff --from prev --to current (minus the commit message information), which is also equivalent to git diff HEAD^. Fossil's command is a bit clunky, and it'll work even less well with random commit identifiers. Eg, fossil diff --from 6e47e6b38b --to 271a6bd31d where Git would only require git show 271a6bd31d. It's workable, but the command syntax is long and requires looking up/pasting identifiers beforehand too.

That topic came up a decade or more ago and it didn't go anywhere because (IIRC, which might not be correct) that approach breaks down once you have multiple merges and branches. e.g. saying "back up one version" is ambiguous if you have two merge parents.

Git defaults to choosing the first parent, and you can stack the suffixes to select different branches of the DAG. man gitrevisions describes all the awful details (most of the time, the normal syntax is fine for my purposes).

fossil timeline [...]

There's no accounting for taste!

Yeah, there's a reason I decided to remove my section on it entirely when I decided to post a final draft to this forum. :)

That doesn't seem to do the job at all, if you could provide a usage example, it might help enlighten me.

How does fossil diff not do that job at all?

git show makes it easy to display the diffs of commits on the terminal.

That's literally fossil diff's job.

Invoking it with no arguments spits out the diffs from the current checkout to the version it's checked out from. Alternately pass the --from X and/or --to Y flags to specify the "before" and "after" versions. e.g. from any checkout try:

$ fossil diff --from prev

will show the diffs from the "previous version" (or the primary merge parent) to the "current" (i.e. checked-out) version.

Invoking it with no arguments spits out the diffs from the current checkout to the version it's checked out from.

That's not what git show is for though, that's the equivalent of git diff (they even output the same diff format). git show is to display objects of the repository (git has four types: blob, tree, tag, commit), and when you pass in a commit object (default without parameters is the HEAD commit), it'll show all the information about that commit.

Sure, you can use diff to do somewhat the same job, but it really isn't the same job.

... Perhaps someone else has a clearer recollection of that discussion (or perhaps Martin G., our expert data archeologist, can find it in the old email archives).

I found this about the +N / -N relative to current checkout..

Suggested by you ;-)

Git allows easy relative names for commits.

For basic ones, we have "next" "current" and "prev".

There's also "root:BRANCH", "start:BRANCH", etc.. More details here.

I remember there was discussion about adding relative increment (e.g. +N, or -N) from current checkout before, this would be nice to have for sure.

fossil timeline ...

The fossil timeline is really the cli command I would like to see improved for sure.
(this is not from the point of view of a git user, more a git illiterate)

The variation I use often use is:

• fossil timeline after current -p <somepath> -b <trunk|some-branch>
  • when I know my checkout is a few version behind the remote, I want to see changes that will affect <somepath> after an update.
  • most of the time, since the timeline on the cli don't have the equivalent of the branch rails like on the webui, I specify the current branch (or trunk) because it's very hard to follow when there's multiple branches.

The -p path is useful but it will not show the "*CURRENT*" mark from the list when the specified file or path is changed in the current checkout, so we end up with a big wall of timeline text and it's hard to spot the current checkout from it. + In this case I think we could add a kind of marker between 2 the checkout where the current one is.

... fossil timeline -n 10 -t ci after 1970-01-01, but that just ends up displaying the 10 most recent check-ins. ...

Hmm, this looks like a bug.

Kind of too bad that fossil info root:trunk on Fossil's own repository doesn't seem to go all the way back ...

I found out that you can cascade many "root:" to pass those branching issue in trunk..

example:

• fossil info root:root:trunk bring to to another branch point.
• fossil info root:root:root:trunk bring you way back to the initial checkin.

---

I would guess something like fossil timeline -n 10 -t ci after 1970-01-01, but that just ends up displaying the 10 most recent check-ins.

I started a branch fix-timeline-cli-after that fix most of the issue with the after keyword.

It should fix the issue you mention for the 10 first check-ins. (also when relative to any date or check-ins).

I found out that you can cascade many "root:" to pass those branching issue in trunk..

Nice. I could have sworn I tried that, but apparently not. It's working fine with version 2.25 even. :)

I started a branch fix-timeline-cli-after that fix most of the issue with the after keyword.

It should fix the issue you mention for the 10 first check-ins. (also when relative to any date or check-ins).

It appears to be working when I build the branch. Thanks!

Yes, that's exactly it. Thank you :)

I would like to see Git become more like Fossil and integrate forge features.

I think i've read/heard drh make similar remarks to this as well.

but for me, apt install git and apt install fossil are effectively the same operation

Well if you're on debian based systems, you likely know the available versions usually lag behind significantly. If that's acceptable to you, then you're right, doesn't matter what the OS does to have git running.