Some ideas for page: Hints For Users With Prior Git Experience

I would've found a small section describing fossil timeline as the fossil version of git log very helpful. I've been around the computing block for a while and i'm not proud of how long it took me to work that one out. (Which is why i'll keep that bit of info to myself..)

Actually, i can't think of a (D)VCS that doesn't have a log command, so this might be relevant to a page outside of a git specific one.

As a side question: Was a log alias left out on purpose?

The section Syncing Is All-Or-Nothing has a minor error in that it says everything is synced, but sync doesn't apply to config changes. Or at least, in my case using 2.12.1, i needed to run a fossil config push all to get my config changes synced.

I would've found a small section describing fossil timeline as the fossil version of git log very helpful.

That's covered now. I think it wants a list of common examples, though, which you can help with. Please? :)

Was a log alias left out on purpose?

I'm not sure they're semantically equivalent, only functionally equivalent in an incomplete Venn diagram sort of way.

That said, if you wanted to contribute a fossil log command that emulated git log, I don't see why it'd be rejected.

The section Syncing Is All-Or-Nothing has a minor error

That section is trying to make a distinction between Fossil and Git that doesn't have much to do with the problem you ran into, but I tweaked the language and added a link to the new backup doc to address this concern, hopefully without derailing the primary discussion point. Thanks.

Got more?

That's covered now.

Wow that was quick! Hopefully it'll be of use to others apart from me :)

Just a small bit of feedback: i'm not sure how accurate that first paragraph is. git log seems pretty efficient for looking back through history for the current branch. The bit about grovelling commits and weak data models is probably not necessary.

Instead, i'd replace that paragraph and emphasize where fossil timeline shines, ie, That fossil timeline is fossil's analogue to git log, but more powerful in that it supports going both backwards or forwards through history and that it shows changes across all branches by default.

It could then show how timeline could behave like git and limit history going back in time from the current commit and from the current branch:

$ fossil timeline parents current

I think it wants a list of common examples, though, which you can help with. Please? :)

Hmmm other examples.. well i can't claim to being that knowledgable with git - I kind of just fumble around till i get it to do what i want. :)

But my other common git log action is to list commits along with their changes. ie, the equivalent to fossil timeline --verbose.

The recommended way to do this in git is: git log --raw.

I say recommended because the original way was git whatchanged. That's been deprecated for a long while but left in there for the muscle memory of the old-guard. I find it nicer to type so i still use it.

Kind of related to logs is the git commit message format. Git has a convention (almost standard) of having a summary line, followed by a blank line, concluded by details.

A small discussion on any fossil convention or lack-thereof or support for this git-style formatting may be insightful.

Got more?

I'll throw out a bunch of ideas in case you like any of them. But, the existing documentation is quite thorough so i'm not sure i've got much more to contribute. At least nothing too important.

Actually, most of these will be how to do things in git. Hopefully you can fill in the fossil commands.

Creating a repository in-place is common in git. eg,

$ cd my-new-project
$ git init
$ git add *
$ git ci -m "Initial commit of project."

Cloning in-place with fossil is documented, but is it possible to init in-place too? Is there anything special about repo.fossil?

I confess that i haven't init'd a repository yet in fossil. I'm a new fossil user and my experience so far has been via converted git repositories.

Show the diff of a commit:

• git show -p <id>
• fossil diff --checkin <id>

Show the log message of a commit:

• git show -s <id>
• fossil timeline -n 1 <id>???

Show the git commits that have not been pushed to upstream:

• git whatchanged @{u}..

Fetch changes from upstream but view them before applying to a working copy:

$ git fetch
$ git whatchanged ..@{u}

git status will also display the number of outstanding or incoming commits.

Ignore files and filetypes:

• in git, create, edit and commit a .gitignore file
• in fossil set the ignore-glob variable

Lastly, fossil close was a complete surprise to me. So something that gives a heads-up like a link to existing or new docs on how necessary running this is. Effects of moving a repository without closing, or/and deleting etc.

My impression is that fossil is quite resilient about it.

I'll add more comments if anything else comes to mind.

Fetch changes from upstream but view them before applying to a working copy:

$ git fetch
$ git whatchanged ..@{u}

I am not sure if the git command gives log entries or actual code changes, but running this from the working directory:

fossil pull
fossil time -n 0 descendants current

gives you all log entries after the version in your working directory on the same branch. The -n 0 makes length unlimited otherwise you only get 20 lines.

fossil pull
fossil diff -from current -to trunk

gives the code changes that would be applied if you are on trunk and were to fossil up. If you are on some other branch, I don't know if there is a generic term that is the branch name for current. I hoped that -to latest would work but latest is interpreted as a (non-existing) branch name.

Also you can run update in nochange mode to get:

% fossil pull
% fossil  up -n
UPDATE VERSION
UPDATE src/alerts.c
UPDATE src/main.c
UPDATE src/pikchr.c
UPDATE src/setupuser.c
UPDATE src/shell.c
UPDATE src/sqlite3.c
UPDATE src/sqlite3.h
ADD tools/fossil-autocomplete.zsh
UPDATE www/caps/admin-v-setup.md
UPDATE www/changes.wiki
UPDATE www/gitusers.md
UPDATE www/index.wiki
UPDATE www/quickstart.wiki
UPDATE www/whyusefossil.wiki
-------------------------------------------------------------------------------
updated-to:   e9b5a983cc8014939af1722451be96e5a009bd9d 2020-11-01 00:30:39 UTC
tags:         trunk
comment:      Increase the version number to 2.14 to begin the next release
              cycle. Update the built-in SQLite to the latest 3.34.0 alpha for
              testing. (user: drh)
changes:      15 files modified.

which may be useful.

I've applied some of this to the doc here. Let me know if I've missed something important. I've been in this doc for 7 hours now, so I'm getting a bit fried. :)

Only issue I see is an unneeded quote (or unclosed quote) in:

   the “update command,

Thanks for the update.

Thanks for all that info. I've got a lot to process today, what between this and the (many!!) new updates to the gitusers doc. :)

I am not sure if the git command gives log entries or actual code changes, ...

Just as an FYI, git whatchanged is a wrapper for git log --raw (or so i've read) so the outputs are commit logs.

Sample output from a private scripts repo i have with one local (unpushed) commit:

$ git whatchanged @{u}..
commit 5cb5a8e3d3822da8867ad491d9ff76bb72819a65 (HEAD -> master)
Author: J <>
Date:   Mon Nov 2 10:57:17 2020 +1100

    a quick change.

:100755 100755 b743303 a370c8f M	xmutt

git log seems pretty efficient

It's O(n), which is not great. Furthermore, it has large constants: filesystem hits per node visit. Fossil's equivalent is O(log n) within a single DB file so that desired info is more likely in the kernel's RAM cache, making it far more efficient.

drh goes into more detail in this video. I recall a measurement on this showing a 30x improvement in one test.

Beware that the video's over 5 years old now, so some of it is outdated and better covered in up-to-date docs like our Fossil vs Git doc. He doesn't talk about git-worktree, for example, because it was added to Git a month after the talk. (Because of the talk?)

a summary line, followed by a blank line, concluded by details.

Now addressed.

Creating a repository in-place is common in git.

Added.

Show the diff of a commit:

Added, with a diffstat bonus.

Fetch changes from upstream but view them before applying to a working copy:

Added.

git status will also display the number of outstanding or incoming commits.

Isn't that essentially already covered by "There Is No Staging Area"? There is no such thing as "outstanding commits" in Fossil.

fossil close was a complete surprise to me.

The section on .git vs .fslckout covered that, but I've recast it to cover fossil close more broadly.

Thanks for all of this! The docs are better for it.

Thanks for all of this! The docs are better for it.

And thanks to you too. I'm learning so much from this discussion and the fossil docs.

That's an amazing amount of work, you must be very passionate about this project.

BTW, i'm so glad you caught my git ci error in the init bare repository example. I have an alias in git that translates ci to commit. It's just one of those things that i've been so used to from prior years of CVS and svn use that i had to put in my git config.

git status will also display the number of outstanding or incoming commits.

Isn't that essentially already covered by "There Is No Staging Area"? There is no such thing as "outstanding commits" in Fossil.

Not quite. Sorry, this is bad/imprecise phrasing on my part.

git status will summarise the number of unpushed commits.

eg, status output from a fully synced git repo:

$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

And now after one checkin has been made and committed, but not pushed upstream.

$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

git status is a nice way to get an overview of how the workarea is travelling as compared to the remote as well as the usual locally changed and unknown files listings.

As a side note: I was the one who asked in another post about commands for artifact/config status, mainly because i'm used to seeing in git whether i could or should push anything.

I thought of some more things i do in git that have a small chance of being useful to this doc. But really this is scraping the bottom of the barrel.

Selecting portions of changes to commit via git add -p [file]. ie, if there's modifications for 2 or more distinct changesets in a working copy (even within a file), this command allows for interactively selecting which hunks to add to the index and to subsequently commit.

I'm pretty sure that the fossil way is to make those changes in separate workareas, but that's a different mindset to the common git single-checkout habit.

And in the other direction, interactive revert via git checkout -p [file] has also been useful to me at times.

I know fossil can revert at the file level, but i'd love to learn if there's a fossil technique to revert individual hunks from a file. Maybe via an exteral app?

And last one (i promise), is from the sales/marketing perspective.

Most git commands have colour output options. You've already mentioned colordiff in the doc, but any other tips to add colour to fossil might be handy.

Actually i'd be interested in a separate wiki page on enhancing fossil with external apps like vimdiff or meld or any other advanced workflow the experts use, but that's out of the scope of this topic.

Your branch is ahead of 'origin/master' by 1 commit.

I'm not aware of a way to get Fossil to show an equivalent. I'd expect it to be fossil push --dry-run/-n, but that option doesn't currently exist.

I suppose no one's added it because most of us run with autosync enabled, so a command like you're asking for would rarely tell us anything useful.

Selecting portions of changes to commit via git add -p [file]

Doesn't exist in Fossil. There have been requests to add it, but no one's done it yet. We welcome your contribution!

Beware, however, that Git's implementation depends on the separation of "staging" from "committed". You'd want to implement the feature differently for Fossil, given its differing design philosophies.

As I recall, my suggestion the last time this came up was to make it an extension of fossil stash: you stash a large bolus of hackage, then say something like fossil apply pop -p, which diffs the current check-out against the top of the stash and asks you whether to apply each patch hunk in turn. That modifies the local checkout only, allowing you to test and modify the result before committing. You can then give another fossil apply pop -p command to get the same series of questions only with the already-applied hunks skipped, so that over the course of multiple iterations, you work your way through the bolus until there's nothing left, so you can fossil stash pop it.

any other tips to add colour to fossil might be handy.

I'm not really aware of any more things of that sort. That's one of the sort of things you get from Git's huge ecosystem.

Anyone who knows differently, let me know, and I'll add it to the doc.

Show the diff of a commit:

Added, with a diffstat bonus.

We could also mention the fully internal fossil diff -i --from 2020-04-01 --numstat. (By the way, apart from the not-so-important ASCII-art, our --numstat misses a possibly important thing: summing up the stats.)

There's a small difference though: this considers by default newly added and deleted files, so in your version the equivalent would be fossil diff -i -N --from 2020-04-01 | diffstat.

(By the way, apart from the not-so-important ASCII-art, our --numstat misses a possibly important thing: summing up the stats.)

Adding this proved to be easy. In the process, I've also fixed --numstat so that it does not print stats for files that have not been modified (instead of showing "0 0").

Here is the patch against the current tip [f6ab24fd26]:

Index: src/diff.c
==================================================================
--- src/diff.c
+++ src/diff.c
@@ -1958,5 +1958,10 @@
         nIns += c.aEdit[i+2];
       }
-      blob_appendf(pOut, "%10d %10d", nIns, nDel);
+      g.diffCnt[1] += nIns;
+      g.diffCnt[2] += nDel;
+      if( nIns+nDel ){
+        g.diffCnt[0]++;
+        blob_appendf(pOut, "%10d %10d", nIns, nDel);
+      }
     }else if( diffFlags & DIFF_SIDEBYSIDE ){
       sbsDiff(&c, pOut, pRe, diffFlags);

Index: src/diffcmd.c
==================================================================
--- src/diffcmd.c
+++ src/diffcmd.c
@@ -858,4 +858,5 @@
   u64 diffFlags = 0;         /* Flags to control the DIFF */
   FileDirList *pFileDir = 0; /* Restrict the diff to these files */
+  g.diffCnt[0] = g.diffCnt[1] = g.diffCnt[2] = 0;
 
   if( find_option("tk",0,0)!=0 || has_option("tclsh") ){
@@ -948,4 +949,7 @@
                       diffFlags, pFileDir);
   }
+  if ( diffFlags & DIFF_NUMSTAT )
+    fossil_print("%d files changed, %d insertions, %d deletions\n", 
+                 g.diffCnt[0], g.diffCnt[1], g.diffCnt[2]);
   if( pFileDir ){
     int i;

Index: src/main.c
==================================================================
--- src/main.c
+++ src/main.c
@@ -323,4 +323,5 @@
   } json;
 #endif /* FOSSIL_ENABLE_JSON */
+  int diffCnt[3];         /* Counts for DIFF_NUMSTAT: files, ins, del */
 };

The Fossil project doesn't accept non-trivial drive-by patches like this. You need to go through the CLA process first, so everything's properly licensed.

I've been on the wagon for quite some time now, so I was well aware of it. The snail needs probably longer to cross the ocean.

Sorry; I don't have the ability to see the list of users on the Fossil repo.

I do see that there are no commits by user danield yet…

No problem. The CLA has been mailed but lingers somewhere on the road/water. I posted the patch for testing/discussion - just like that for timeline - at Richard's suggestion.

Now that the CLA is in the fireproof safe, I have committed the changes on a branch.

It appears that Daniel set the branch color manually, perhaps using the --branchcolor command-line option:

Danial: For future reference, we prefer to leave branches uncolored and let Fossil choose the color for itself, at least on the Fossil self-hosting repos and on the SQLite repo.

Is there a way to cancel the color setting?

That can be changed in the web UI:

Change background color
Propagate color to descendants

I guess I wasn't clear. I want to change it so that fossil takes over the color choice. The gui only lets me set a new color AFAICT, not pass color control back to fossil.

drh indicates that cancelling the bgcolor tag on the checkin should do that and propagate to all descendants on the branch.

You can put a cancel tag on the tag that sets the branch color. But there is no need to do so in this case. I don't mind that these two branches have user-defined colors. I just don't want people to make a habit of doing that.

The funny thing is, I haven't set the color manually - in fact, I cannot remember ever having set a branch color manually in Fossil. (And had I chosen them, they would have been different and better looking anyway ;-) )

Yet the mystery is quickly unveiled. Both branches had started their lives as private branches, and according to this line all private branches are bestowed the nice color of #fec084, probably in order to stand out.

The question is, should this be mandatory? Apart from the problem on hand (same color on adjacent branches), this does "leak" information about the private past of the branch. In my opinion this color distinction can be dropped altogether.

And I agree with John: we should offer an option for "Change background color" (and amend) to let Fossil choose the color.

I clicked the "Cancel special tag bgcolor" on both branches, thus restoring the Fossil-chosen colors.

also mention the fully internal fossil diff -i --from 2020-04-01 --numstat

Done.