fossil: add files to existing repo, do I need to open first?

Question

I wish to control versions of a directory, let's call it "project", and keep the fossil files inside another directory named "fossils." I have successfuly created the "project.fsl" repository, added my project files, committed, and closed. My problem is understanding how to take the next step.

Here is what I do, following the fossilbook suggestions.

$ cd project
$ fossil new ../fossils/project.fsl
$ fossil open ../fossils/project.fsl
$ fossil add .
$ fossil ci -m "first commit"
$ fossil close project.fsl

Now I have worked on my project, edited some files, deleted some files, created some files, renamed some files. I'd like to add the current state of the project to the repository. How do I do that?

Based on what I read in the doc, I was under the impression I had to first open the repository, then add files, then commit. If I don't open the repository, I get the Not within an open checkout. message. But if I open fossil wants to overwrite my directory with the older files. (And if I open from within the fossils directory, I get an "unpacked" version of my project copied into the fossils directory, not what I want either)

$ cd project
$ fossil open ../fossils/project.fsl

Here fossil wants to overwrite my project with the older version. I say no to every suggestion. I suspect open was not the correct approach, but then if not what is?

I want to add my changes to the repository, so now that project.fsl is open, I try this:

$ fossil add .
 ADDED  Slides/tmp.tex

$ fossil commit -m "no idea what I'm doing, this will not end well"
 would fork.  "update" first or use --allow-fork.

$ fossil close
 there are unsaved changes in the current checkout

At this point I delete all the hidden files named .fslckout .fossil and try again, with similarly disappointing results.

To be quite frank, my only interest in fossil is keeping a history of my project. I have no co-authors and don't plan to do fossil diff or fossil ui or anything like that until such a time, which I hope will never happen, when I need to dig into the history of my project.

Edit. I am a total newbie. I not sure I understand the meanings of checkout, manifest, leaf, etc. so it's making it very hard for me to get anything out of the manual, notwithstanding the countless hours spent trying. I don't understand much of this page on fossil open: http://fossil-scm.org/fossil/help/open

Answer 1

Low Ceremony and Easy Beginnings

For a single developer, the life-cycle of a fossil repository can be very simple:

1. fossil new to create the repository file itself.
2. fossil open to create the first (or possibly only) active workspace
3. fossil add, fossil remove, fossil rename and fossil addremove to keep fossil informed about what files to track.
4. fossil commit to commit changes to the repository

where steps 3 and 4 are repeated as needed through the lifetime of the project.

This is one of fossil's strongest advantages: it is very low ceremony by design. You can maintain a very elaborate project alone and really only use fossil commit on a regular basis.

Next Steps

The next stage of sophistication can move in several directions. If you want to share work on a project with a second developer, you will want to learn more about cloning a repository and synchronizing updates. If you want to allow for independent work on a feature without breaking your trunk builds, you can learn more about branching and merging. If you want to take advantage of the wiki and ticket tracker features, you will want to learn about fossil ui, fossil server or configure your web server to launch fossil.

But none of those use cases will require the use of the fossil close command. In fact, the output of fossil help recently got split into a shorter list of commands that are needed by most users, and a longer list of all the commands. In that division fossil close did not make the short list. The only functions it performs that can't be easily done by simple deletion of files is to verify that their aren't unsaved changes and to remove the open checkout from your personal list of checkouts available to the fossil all command.

Fossil-specific Vocabulary

Even a single developer will want to learn some of the vocabulary used by fossil's documentation.

• "checkin": A specific set of revisions of files, identified by a UUID and possibly by one or more tags.
• "checkout": A folder tree associated (by fossil open) with a specific repository. Most fossil commands require that the current directory be within an open checkout.
• "UUID": A unique identifier for any specific thing stored in the fossil repository. In practice, the UUID is the SHA-1 has of the thing expressed in hex. In most cases, the UUID can be shortened to just enough leading digits of the full hash to uniquely identify it. It will usually be written as 8 or 10 digits in square brackets.
• "artifact": A file or or other content (a wiki page, a ticket, a manifest, etc.) stored in the repository. Every file you check in becomes an artifact. So does all of the metadata (commentary, time stamps, etc.) about each checkin.
• "branch": A line of successive checkins that branches from some root checkin. Branches are used to hold changes aside until they are ready to be merged, or simply to contain changes that are mistakes.
• "leaf": The checkin at the end of a branch.
• "trunk": The first branch in any repository is named "trunk". Most other branches will be branches from some checkin along the trunk.
• "manifest": The list of files modified in a particular checkin along with metadata describing that checkin (the user, the time, the description, the UUID of its parent checkin, and any tags it might carry) makes up the manifest. Most users don't really need to worry about manifests, they are created by fossil commit and can be viewed from the web interface.

Web Interface

Any user will want to learn about the web interface to fossil. An easy first step is to say fossil ui within an open checkout. The Timeline shows the development history with a node for each checkin, and lines drawn to show branching and merging. The web interface is highly configurable, provides a wiki and ticket tracker, and also provides a gui from which most settings related to the project and repository can be adjusted.

Fossil itself is an efficient web server for the content of the repository. In fact, most of the pages at fossil's official web site are served by fossil itself from the repository for the source code to fossil.

Sources for More Help

Aside from the web site and the individual command help available from fossil help, there are several other resources that many users should be aware of.

There is the fossil-users list with consistently high signal to noise ratio. The key developers pay attention to it, as do many helpful and knowledgeable users. The list has at least one archive, as well as a separate list for the developers to discuss new features and plans, but fossil-dev won't be interesting unless you want to work on the internals of fossil itself.

Jim Schimpf has a book that attempts to be both a tutorial and complete reference, and includes some advice on best practices. It is well worth a read.

The built-in command line help along with documentation for all the page URLs understood by the web interface is also available from fossil's web interface at the /help URL within any repository's site. That help text includes documentation of every command, including the unsupported internal test commands.

And finally, the [fossil tag][tag] here at StackOverflow can't be ignored as a resource.

Answer 2

fossil open is the right thing to do. In your case, it's the fossil close that wasn't necessary.

At this point, you should do fossil open ../fossils/project.fsl --keep to open your repo while keeping all the changes.

The open command marks the current directory as a work directory (in Fossil terms, a checkout). I recommend you do not close it until you need to move either your repo or the working directory itself. Personally, that only happens when I move to a different computer.

To have fossil identify all changes, just do fossil addremove; fossil will then add all new files, and remove all deleted files, so that the repository once more matches the working directory. Of course, you still have to commit the changes afterward.

Note that addremove does not automatically recognise file renames! If you've renamed files, you should let Fossil know this for each file using the fossil rename command, before you perform the addremove command. Of course, if you don’t mind breaking the edit history of specific files, you're free to skip that, and let fossil think one file was deleted and another added instead.