On Oct 24, 2016, at 11:33 AM, Scott Doctor <sc...@scottdoctor.com> wrote: > > The issues I initially had with fossil were due to a misunderstanding about > how fossil works. An issue is that clicking the help button in the fossil UI > gives a wall of commands.
If the repository’s /help URL is where you started to learn about how Fossil works, no wonder you’re confused. :) Have you read the Schimpf book, at least through chapter 3? https://www.fossil-scm.org/schimpf-book/doc/2ndEdition/fossilbook.pdf Your issue comes up on page 31, which might seem late in the discussion for something so fundamental, but if you look at the table of contents, you can see that it’s just because the author wanted to cover other more fundamental things first. The equivalent to the repo’s /help URL doesn’t appear until two chapters later in the Schimpf book, because /help is a command reference, not a tutorial. > I think the documentation should group the most commonly used commands from > the master list. I don’t think trying to contort the command reference into a tutorial will solve the base problem. Prose works better than command lists for bringing new users on board. Thus the Schimpf book. And if you say, “Why didn’t I see this before?” then I’ll point out that it’s the fifth link on the Docs page at fossil-scm.org. :) The first link on that page takes you to a Quick Start guide, and in the Making Changes section, it *does* talk about autosync, which is how local changes update the remote repository that you cloned from. > It seemed as though fossil was basically a ticket/wiki database that had a > fancy way of zipping groups of files together. You’re going to get into a lot of trouble trying to think of Fossil as a fancy sort of zip file. That’s a wholly unhelpful abstraction. What is Fossil like? Hmmmm. I feel like a zen master being asked about the nature of butterflies. Every analogy I can think of either breaks down too quickly to be useful or it gets into details too quickly to be helpful. I mean, I can’t exactly just point you at this: https://www.fossil-scm.org/index.html/doc/trunk/www/fileformat.wiki and expect you to go, “Oh, of course that’s how it works!” :) I don’t know that Fossil is all that close to any other software system you’ve likely used before. It isn’t even all that much like its close competitors, Git, Mercurial and such. You sound like you might be a research scientist, or IT support for research scientists, so how about this for an analogy: Fossil vs Git is like Mathematica vs Maple, or Origin vs. Gnuplot. And Fossil vs Zip is like Mathematica vs. Python, or Origin vs. Excel. You can draw parallels between each of these pairs, but to call them interchangeable is to misunderstand at least one of the alternatives. It’s best to just take Fossil on its own terms, and not to try to think of it as like anything else you’ve ever used. Fossil is Fossil. > I derived that clone basically sent a zipped package of files Better to say that clone retrieves the complete history of the project, not just files, but also wiki pages, checkin comments, branch and tagging info, tickets, etc. The only overlap between the way Fossil artifact data are stored and how zip files work is that the zlib compression library used by Fossil to do lossless compression of data at rest and on the wire is more or less the same thing as the compression algorithms used in Zip files. But unlike zip files, Fossil doesn’t model a hierarchical filesystem at its core, and zlib vs zip totally ignores delta compression, which has far more practical effect on the final size of a typical Fossil repository. And even that aside, that view of Fossil ignores many other things like tags, branches, tickets, artifact IDs, etc. > then someone manually has to conditionally decide what to merge back into the > main repository. In a normal software development project, manual merges are rare. However, your earlier description makes me believe you might be storing binary data, and on top of that, the data itself might be totally different each time. That is, unlike with software source code, your use doesn’t amount to evolving text files by relatively small amounts on each checkin. That will prevent Fossil’s automatic conflict resolution from working, which means you’ll have to resort to social means to work out such conflicts. > The documentation seems to imply that only the local copy is modified Which documentation, specifically? There’s a lot of it. I’m still not sure if you just started in the wrong place or if one of the sane newbie entry points really does need to be improved. > The documentation seems to read as though to get the local copy back into the > main repository requires a bunch of commands need to be executed on the > server command line. This is an example where I need a specific URL to understand your problem. > A problem with most manuals for many software products is that an assumption > is made that the reader already understands the concept of operation. Yes. Because Fossil is such a late arrival to the world of DVCSes and DVCSes are such a recent contribution to the wider world of VCSes that there is going to be an assumption that you’ve used one of Fossil’s competitors or predecessors. That’s just statistics; relatively few people will come to Fossil completely clueless. It’s kind of like how Google Docs’ Help doesn’t explain how word processors work. They expect that Docs is not your first word processor. (Which makes me wonder how all these kids coming up on Chromebooks are figuring this stuff out?) _______________________________________________ fossil-users mailing list fossil-users@lists.fossil-scm.org http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users