I felt compelled to provide constructive feedback...

Always welcomed. Even better: Send in a mock-up of your idea :-)

Failing that, just providing feedback from a newbie's perspective is helpful. You might be struggling with some concept that we think is obvious because we've been working with it for 15 years. Unless you speak up, we will never know.

I'll have questions about your suggestions later. I'm busy with other things right this moment. I just wanted to quickly thank you for speaking up and offering to help.

Hi Richard, I appreciate your openness to feedback. Here is a mock-up:

What Is Fossil?

${Nothing changed in this section}

Latest Release

${Mimic SQLite here}

Version 2.10 (2019-10-04). Download

Quick Start

1. Download fossil or install it using a package manager

2. In one directory, create the repository:

   fossil init test.fossil
   

3. In another directory, create a checkout:

   fossil open ${STEP1DIR}/test.fossil
   

4. Create a new file in the second directory and then see it in uncommitted files:

   fossil extras
   

5. Add your new file to the project:

   fossil add ${FILE}
   

6. Commit the file to the repository:

   fossil commit -m "Added file"
   

7. Open the web UI:

   fossil ui
   

8. For details, see the Quick Start Guide

Links For Fossil Users

${Remove this section from the homepage and move into its own wiki page}

Links For Fossil Developers

${Remove this section from the homepage and move into its own wiki page}

FWIW: i recommend against the inclusion of step 4. In 12+ years of using fossil, i've never once felt compelled to use "extras". In this context it just clutters up the otherwise minimal steps needed to get Your Stuff into fossil.

I don't think "Getting Started" is about the minimum necessary to get stuff into a repository. It should be more along the lines of "Here is the subset of actions needed to start using Fossil which fit common use cases."

In my opinion, putting stuff into a VCS that does not belong there is something to be assiduously avoided, and use of "fossil extras" helps to do that. It also helps detection of what has not yet been added but perhaps should be. In short, it is a good habit when just getting started or changing what is put under version control.

A case can be made for extending the "Getting Started" steps to include doing a few edits, use of "fossil changes", and another commit. That helps to avoid another error, which is overlooking something that should have been committed. It is another good habit.

Both of those good habits fall under the rubric of "Consider, then act." I do not think encouraging "Just do." is justified by brevity or simplicity.

It should be more along the lines of "Here is the subset of actions needed to start using Fossil which fit common use cases."

That was kind of my point (admittedly poorly expressed): if i can go 12 years without ever needing "extras", across several dozen repos, then it can't be all that common of a need, especially for a newly-created repository, where everything is "extra."

(Please excuse brevity - i'm on a tablet.)

First, I want to emphasize that I do not see this as a "right way" versus "wrong way" issue. I know people who, because they have excellent memory, rarely get distracted, and usually enjoy clarity of intention, would not need the "extras" or the "changes" fossil commands. I imagine you are one of those people.

However, there are people who need little memory refreshers, particularly after they get pulled way from a sequence of related tasks on one project. Those people can even forget whether they committed a set of changes after otherwise getting them ready to make more persistent, or forget which files were touched. I identify with those people. And I think that, for that set of people, those commands are a very useful part of an initial fossil command repertoire.

And because "extras" and "changes" are so useful, even vital, for some (or many?) people, and because they can be easily skipped over by those who have no need for such aids, I think they belong in a not-quite-minimal "Getting Started" scenario.

To your point, "where everything is 'extra'": True, but "Getting Started" would perhaps be better titled "Fossil Basics, for Everyday Use". And those superfluous-to-some commands might be commented something like, "When you're unsure what was added or changed since the last commit, ...".

I think one more aspect we need to consider in showcasing Fossil which is the motivation of the new user.

I'm not sure what was the motivation that led you to Fossil. In my case, years back it was a search for non-install and portable VCS solution. I had no admin rights in somewhat high red-tape dev environment, but needed to track changes in scriptable manner, instead of mouse clicks.

I was familiar with VCS and obvioisly not intimidated by command line prompt. So I suspect are most of those who end up at Fossil's page for the first time.

From what I remember of anything that needed introduction was the following:

• Fossil repo file, how to name it, where to put it
• what to do about Fossil's CR-LF prompt (used to be the mysterious cr-nl) on Windows
• how to set up .ignore file (well, a setting in Fossil's case)
• what to do about signing prompt during commit (used to be enabled by default)
• how to set up default user for the first time with repo
• how to remove a file wrongly added and committed (shim concept was new to be, had to lookup the word in dictionary to better grasp the designer's intent)
• how to correct a typo in commit message (now we have amend!!)
• figure out the versatility of 'update' command (to change branch and fast forward to pulled tip of current branch, while merging current uncommitted changes)
• the 'status' meanings resulting from merge (those may be more familiar to cvs/svn users)
• remembering those special check-out names (tip, root, current, etc.)
• where to upload my public SSH keys (no need, unike with GitHub)
• where to find or set up Fossil plugins for *Studio (that included Sun Studio back in time; or Eclipse)

That's a few from a prospective of more or less experienced programmer, back in time not familiar much with Git and intimidated by Git's 'staging' concept and miriad of switches.

Even then, I found that .pdf book/guide very helpful in giving me confidence in establishing Fossil for routine use.

As for the 'extra' command, I almost exclusively use 'status', once project is established. I agree, for Git users, 'status' can be configured to flag the extra files, as potentially forgotten to be 'add'ed. These days I rely on my mental discipline, or Fossil plugin's features when possible.

I have started a branch to prototype these suggestions. Few on-line at https://fossil-scm.org/fossil/doc/revamp-home-page/www/index.wiki

Hey Richard, this is absolutely wonderful, thanks! I like how you further simplified the quick start and changed the title of the tab to Support at the top.

I think this change is sufficient; however, I think the thread between Larry and Stephan is worth considering. I'm strongly on Larry's side because, as someone who comes mainly from git (I used cvs and svn long ago, but have since forgotten them), one of the most commonly used features of git is $(git status) which shows both un-added files (fossil extras) and uncommitted files, whereas $(fossil status) doesn't show un-added files. One of the questions that was clearly on my mind before I found $(fossil extras) was, "How do I find which files haven't been added yet?"

The risk is that people working in a team forget to push files to others. In fact, I'd take the suggestion one step further, and suggest that $(fossil status) should display un-added files just like $(git status).

$ cd /tmp/
$ mkdir gitplay
$ cd gitplay
$ git init .
Initialized empty Git repository in /tmp/gitplay/.git/
$ touch helloworld.txt
$ git status
On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        helloworld.txt

nothing added to commit but untracked files present (use "git add" to track)
$ git add helloworld.txt 
$ git commit -m "first commit"
[master (root-commit) 649266a] first commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 helloworld.txt
$ echo "play" > helloworld.txt 
$ git status
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   helloworld.txt

no changes added to commit (use "git add" and/or "git commit -a")

as someone who comes mainly from git

Can you prepare a bullet list of key differences between Git and Fossil? I cannot because I have not spent enough time with Git to learn all the ends and outs.

I will try to start the list as follows:

• A repository and a check-out are separate entities in Fossil, whereas they are much more closely coupled in Git, to the point that many Git users do not distinguish between a repository and a check-out, merging them in their minds into a single object.

• "git status" shows unmanaged files, where as "fossil status" does not. To see unmanaged files in Fossil use the "fossil extras" command.

• Fossil does not support rebase. Instead, Fossil forces users to do the right thing and make proper use of branches and/or cherry-pick merges.

• Fossil actually keeps track of named branches, unlike Git which only keeps track of the tip check-in for each branch.

• Fossil does not require branch names or tag names to be unique.

Long-time Git users are encouraged to correct and/or extend the list above to include any other differences between Fossil and Git that they found to be surprising or that they struggled to understand upon first encountering Fossil.

• Fossil allows creation of a new branch on commit, switching to it automatically. Git's workflow usually begins with checkout -b to create a new branch and switch onto it. The closest alternative with Fossil is to branch new followed by update the-new-branch.
• Fossil forgoes the Git's index/staging concept, so add is direct, no need to commit -a. In fact sometimes I wish fossil supported commit -a option as no-op just to ease the git/ fossil intermix. But that's just me.
• Fossil's remote concept is much more simplified with only one "origin" (remote-url), while Git allows multiple remotes (origin, upstream, my-uncle, whatever)
• Fossil has no concept of Git's "tracking branches"; all branches in Fossil are tracking as they are literally the same in the cloned repo
• Fossil's pull is like Git's pull, there's no fetch then merge.
• Fossil's update does automatic pull (by default) from the clone's "origin"; Fossil's commit will attempt the automatic push to "origin". This is controlled by Fossil's autosync setting.
• Fossil settings are the equivalent of Git's config
• Fossil merge --cherrypick command is the Git's cherry-pick (it's a command)
• Fossil amend command is a superset of Git's commit --amend (only the tip of the branch)
• Fossil does not have Git's reset command to "delete" commits; The closest in effect could be Fossil's reparent (?).
• Fossil cache is much similar to Git's
• Fossil allows to use multiple check-outs (in separate work directories) without re-cloning/duplicating the common repo, unlike Git. This immediately lets one checkout different branches (like features/releases etc.) into separate directories thus saving space and also faster build times (as the checkout changes timestamps, triggering a rebuild). I find this a strong advantage when working on projects with large codebase.
• Fossil status does not show untracked files by default, unlike Git. I find this rather beneficial in my case when "tuning" large source-bases, as this allows me to selectively track only files being "tuned" without importing the whole project into Fossil. Again, that's just me.
• Fossil has some peculiar forking behavior, that is the forks will occur especially in mainline collaborative workflow. The fossil project own timeline is a good illustration for that. Somehow with Git this did not occur in my experiences, perhaps it's due to usual branch segregation in place.

Hey Richard,

"git status" shows unmanaged files, where as "fossil status" does not. To see unmanaged files in Fossil use the "fossil extras" command.

Is there a reason $(fossil status) doesn't show unmanaged files? It would help users transitioning from git (alternatively, there could be a "Fossil for Git users" wiki page that highlights these common questions).

A repository and a check-out are separate entities in Fossil

I like this approach; however, I found it slightly confusing that your Quick Start shows creating the repository and check-out in the same directory. That's why I placed them into separate directories intuitively in the draft.

Another surprising thing I found so far was that $(fossil mv) didn't actually do the move as $(git mv) would.

Finally, I still haven't fully figured out the equivalent of a .gitignore file, although I haven't had the time to fully investigate ignore-glob and how it works with a setting set in a check-out versus pushed to a repository versus .fossil-settings.

If I run into anything that I find particularly difficult or surprising, I'll let you all know.

Thanks.

Agree that repo in another directory may be less confusing, although that has been common practice since RCS became passe.

(And somewhat off-topic for this thread ...) Here is a short exploration regarding .gitignore functionality:

fo help settings
fo settings | grep ignore
fo help ignore-glob
fo settings ignore-glob *.obj,*.exe,*~
fo settings ignore-glob

You can guess what 'fo' means. Here is another useful alias which could obviate your desire for a 'git status' emulation:

> alias fowhat
echo === Changes: && fossil changes && echo === Extra: && fossil extra

Check out the --hard option to fossil mv

Fossil has quite useful and sufficient built-in help already, so this might be gilding the lily. Nevertheless ...

Looking at the Quick Start Guide, I see plenty of tips and links about doing this and that, but nothing on getting fossil itself to reveal more about doing things.

I think a section on using fossil's help in the Quick Start Guide, or

  See the Quick Start Guide for more detail, or enter 'fossil help help'.

in the intro page 'Quick Start' section would be helpful and encouraging to new or would-be new users. It is very discoverable, and that merits being learned early.

Thanks Larry!

Thanks Venks, that's useful.

Is there a reason $(fossil status) doesn't show unmanaged files?

Probably because it is considered too much clutter.

I prefer the "clutter", so an alias like Larry's.

I'd rather keep the ignore settings upto date than forgo a reminder in case I forget to add a file. (I hate when someone else's build fails because I forgot to add a file.)

Hi,

I use Fossil since 2011. Just now I found about extras and I never needed. If a minimal page is the purpose of the home page refactoring, I would follow Stephan's advice about avoiding this step.

Cheers,

An initial draft of the "Hints For Git Users" document is now available. Please provide suggestions and/or copy for improving it.

i'm reading from bed and can't commit from here, so here's a typo report:

"With Git, the repository and check-out are closely released..." (related)

Also, i don't recall having ever seen git spelled with a big G, but perhaps that's just selective blindness on my part.

Edit: "has been thoroughly, carefully, and throughtfully discussed,"

Hi Andy,

I think it's a common mistake by users of a DCVS to forget to check and push something in, thus the value of an explicit .gitignore file and showing extras in status for git; however, Fossil's philosophical difference is reasonable. But I think that further supports the idea of a "Fossil for Git users" wiki page. I'll keep this in mind as I play with Fossil more and I'll submit a draft at some point if it accumulates to more than a couple bullet points.

Edit: Nevermind, I see Richard just created such a page. Thanks Richard!

Looks great, thanks Richard!

As a proper noun, "Git" refers to a certain software system. (I say this from observable usage rather than any pretense to authority.)

As a plain noun, "git" refers to a foolish or worthless person.

As a command invocation, "git" is easier to type than "Git".

As a verb, "git" means "Get out of here!", which is often about right for a commit, but not so much for a "get".

'git cherry-pick' is 'fossil merge --cherrypick' (note the dash)

https://git-scm.com/docs/git-cherry-pick

'fossil set mv-rm-files 1' is equvalent to making --hard default, so that

'git mv' is 'fossil mv'

https://fossil-scm.org/home/help/mv

It'd be nice to hear from real Git converts here.

In general Git and Fossil use very much the same operational approach. Anyone coming from Git would just "get" it from a short example. Fossil is much easier to remember, actually internalize, than Git (like that commit -a case). Same goes for 'fossil help', it's usable, so no problem if one forgot some switch to timeline command. Maybe there should be 'fossil help -git' mode with only two entries: rebase and submodule...just kidding :) But this sort of brief command line help perhaps would be more accessible for real or occasional Git converts.

suggestion: quite a few of the differences with git can be resolved through settings or aliases, so listing them all together, perhaps even as a script, to "make fossil more like git" would eliminate having to unlearn old habits and being constantly bitten by them, creating a lot of unnecessary friction, enough to deter potential converts or even just casual users.

Can you seed such a list?

I wrote up a git amend equivalent in fossil here with an explanation/comparison with git.

I'd love to have it as a single command though. I hacked a small script which mostly works...

bin/fossil-oops:

#!/usr/bin/perl

my $tip;

if (`fossil time -n 1` =~ /.*\[(.*)\]/) {
        $tip = $1
}

die "Where's the tip?" unless defined $tip;

system "fossil amend $tip --branch oops --hide";
system "fossil update trunk";
system "fossil revert -r $tip *";

Git is so ubiquitous that one can have it anywhere, on any platform and IDE. Having Git requires almost no friction. If someone is very much accustomed to Git, there's not much practical advantage in switching to Fossil.

If indeed such conversion is a one-way choice, then what's the point in carrying over the clunky luggage of Git's interface instead of adopting a simpler one of Fossil?

It seems to me Git users are well served with Fossil already. Maybe we could make Fossil more appealing/accessible to users who are new to VCS or DVCS? Is there any user segment left which is underserved by VCS offerings?

I know, that Mercurial hosting is dwindling. Not sure if those users would consider Fossil.

If we want to make Fossil more attractive, maybe we could reassess what sort of advantage Fossil is truly offering (unrelated to Git)?

Git on Windows is a tremendous pain relative to *nixes, I strongly disagree about there being no friction there. And for a long time, until relatively recently, git on windows meant cygwin - with all the problems that brings.

Clunky luggage? Like the difference between fossil's mv behaviour vs git's? It's really a philosophical difference, not clunk, and neither is simpler than the other.

Additionally, seeing a comparison list of equivalent commands is a common, and very elucidating, thing on the net when comparing X with Y - you're not forced to adopt said aliases, but I prefer to see commands over lengthy texts describing them; it's usually shorter and clearer and easier to remember.

It seems to me Git users are well served with Fossil already.

You mean served with Git? Then they wouldn't be looking here in the first place. Those that do would like to know how it compares to their current tool, and how they can get going with the least amount of fumbling and (re/un)learning.

--------
gch: git cherry-pick
fch: fossil merge --cherrypick

--------
gmv|rm: git mv|rm
fmv|rm: fossil mv|rm --hard

fossil set mv-rm-files 1
fmv|rm: fossil mv|rm

--------
gdc: git diff "$1^..$1"
fdc: fossil diff --checkin $1

--------
gds: git diff --stat
fds: fossil diff --numstat

--------
gpl: git pull
fpl: fossil update

gps: git push
fps: fossil push

--------
gl: git log -n20
fl: fossil timeline

gl1: git log -n1
fl1: fossil timeline -n1

gll: git log
fll: fossil timeline -n0

--------
gbo: git revert
fbo: fossil merge --backout

--------
grv: git checkout .
frv: fossil revert

grvc: git checkout abcd1234 .
frvc: fossil revert -r abcd1234

--------
gs: git status --untracked-files=no
fs: fossil changes

gsu: git status
fsu: fossil changes --unchanged

--------
# git-like manual push/pull
foff: fossil settings autosync off
# auto-push/pull
fon: fossil settings autosync on

You mean served with Git?

I mean Fossil provides a lot of conveniences to Git users already. Starting with import/export/mirror, to workflow, to command naming. Well, now a dedicated Wiki page. Your nice list of aliases is yet another comfort added.

Those that do would like to know how it compares to their current tool, and how they can get going with the least amount of fumbling and (re/un)learning.

I still don't understand why would someone chose to abandon Git, yet insist on keeping the learned use of Git's command switches instead of simlply use Fossil commands (most of the time no switches needed other than -m, --branch, and occasional -r), or 'fossil help' when in need.

Git and Fossil are different, no matter the kludges we put to harmonize them.

Re

I still don't understand why would someone chose to abandon Git, yet insist on keeping the learned use of Git's command switches

I can imagine a why, having been in similar circumstances. Suppose you are using VCS brand X, which your employer insists is its standard VCS, if not the cat's meow. You use it frequently, enough that the everyday interactions with it are committed to "finger memory". Yet you wish to either try fossil or use it for real work, either separate little projects, checkpointing, or recourse when the brand X server is down yet again. In that circumstance, being able to use fossil for the common, simple VCS tasks, without having to abandon finger memory or give it much thought [a], would be a boon.

[a. I have long maintained that brain cycles can be a scarce resource, especially when one is deeply immersed in real software issues. So reducing the drain of administrative tasks, such as checkpointing, is worth something. ]

Very helpful cheat-sheet!

This reminded me of my attempts back in time to impart some of Fossil command goodness to Git's --hard --to -r -e member command line.

Some of Fossil commands can be just defined as Git aliases, others comprise multiple commands to produce something similar to Fossil's output. For example, "timeline" should rather be "timeline --all", but I liked to see only changes on current branch, as "git log" does. Ultimately, I went on learning to speak both Git and Fossil, but kept "timeline" alias -- this one is just critical for situational awarness:)

Anyways, here's "Git Fossilitator" in case anyone would find it interesting (gg.sh):

#!/bin/bash
GG_NAME="Git Fossilitator"
GG_VERSION=0.4

print_version() {
  echo "$GG_NAME $0 version $GG_VERSION"
}

print_usage() {
  print_version
  echo "Usage: $0 [command] [args]"
  cat <<EOF
Adds support for the following Fossil commands and behavior:
      status
      timeline
      update
      commit
      amend
      revert

Options:
      --help         show this help
      --version      show version

Usupported commands are passed on to Git verbatim.

Configuration variables:
      GG_DEBUG=1     enable Debug mode; print the resulting commands
                     without execution

EOF
}

print_cmd() {
  printf 'cmd: %s\n' $cmd
  [ -z "${args[0]}" ] || printf 'arg: %s\n' "${args[@]}"
}

has_func() { declare -F -- "$1" >/dev/null; }

run_git() {
  if [ "$GG_DEBUG" == "1" ]; then
    print_cmd
    return 0
  fi

  git "$@"
}


do_status() {
  run_git log -1
}


do_timeline() {
  cmd="log"
  args=( "--oneline" "--decorate" "--graph"  "${args[@]}" )
}


do_commit() {
  args=( "-a" "${args[@]}" )
}


do_amend() {
  cmd="commit"
  if [ -z "${args[0]}" ]; then
    args+="--no-edit"
  fi
  args=( "--amend" "${args[@]}" )
}


do_update() {
  branch="${args[0]}"
  if [ -z "$branch" ]; then
    cmd="rebase"
  else
    cmd="checkout"
  fi
}


do_revert() {
  cmd="checkout"
  args=( "--" "${args[@]}" )
}


[ "$1" == "--version" ] && print_version && exit
[ "$1" == "--help" ] && print_usage && exit

cmd=$1
[ -z "$cmd" ] && cmd="status"

shift
args=( "$@" )

has_func do_$cmd && do_$cmd

run_git $cmd "${args[@]}"