Single user

Introduction

If you have read this far and are at least persuaded to try, you will want to put one of your projects under software control using Fossil. This chapter is set up to lead you through that task and show you how to adapt your development to using this tool. The assumption is made in this section that you will be the only person using the repository, you are the designer, developer, and maintainer of this project. After you are comfortable using the tool, the next section will show how you use it when you have multiple people working on a project.

Using the Fossil command line application

Fossil is a command line application. This means, it must be started from a command line interface, typically called a "Terminal" or "Console". However, this does not mean that Fossil has no GUI. Read on in the section [Set up user interface] to see how the GU is launched. The fossil command has many subcommands. You can get a list of them with

::: Shell $ fossil help # if you want a list of all commands and not only the most frequently used: $ fossil help -a :::

There is a bunch of options that are supported for all Fossil commands. You can see these options with

::: Shell $ fossil help -o :::

Try calling fossil help help to see what else is possible with the "help" command!

Creating a repository

Introduction

In the spirit of "eating one's own dog food" we will use this book as the project we are going to manage with Fossil. The book is a directory of Markdown text files and the current working area looks like this, i.e. these are the files I already created:

fossilbook3
- content
  - book.md
  - image
    - book
      - fossil.png
  - index.md
  - introduction.md
- makefile
- outline.txt
- pandoc
  - metadata-general.yaml

<!-- the above should be redrawn in pikchr and updated to the new directory structure -->

It took just an hour or so to start preliminary research and build the framework. Since that's about all I'm going to do today I want to build a repository and put all these files under Fossil control.

Create repository

I have a directory called FOSSIL in which I keep all my repositories, Fossil doesn't care but it helps me to keep them all in one place so I can back them up. First I need to create a new repository for the book. This is done using the command line after I move into the Fossil book directory called fossilbook3. (Here I have the fossilbook3 directory side by side with the FOSSIL directory).

::: Shell $ cd fossilbook3 $ fossil new ../FOSSIL/FossilBook.fossil :::

I create my repositories with the extension .fossil, this will be useful later with the server command (see section [Remote server]). When the repository is createed, an initial password is assigned with an admin user of "jim" (the original writer of this book).

Connect repository

The repository is created but is empty and has no connection to the fossilbook3 directory. The next step is to open the repository to the fossilbook3 directory with the open command.

::: Shell $ fossil open --force ../FOSSIL/fossilbook3.fossil :::

This will register a connection to the repository and do an initial check-out into the current directory (which is fossilbook3 in my case).

::: Note I checked the repository out into the current directory but this directory is not empty (it contains my initial directories with the working files created above). If there are other files in the check-out directory that Fossil doesn't manage (the fossil file itself doesn't count), the command will abort with a message saying that the directory is not empty. In this case, you need to use the --force (or -f) option as I did above. :::

The open command seemingly did nothing, as if no files were created. However, checking with the status command shows the repository, the directory it's linked to and that we are hooked to the trunk of the store.

::: Shell $ fossil status

repository: /home/jim/FOSSIL/fossilbook3.fossil local-root: /home/jim/fossilbook3/ config-db: /home/jim/.config/fossil.db checkout: 21e43f604387da163ea84f0d2f73cbaefff0f681 2020-11-23 18:46:21 UTC parent: 2baae1d5fb4865028ba9f4b104f8fed2f9b44094 2020-11-23 12:45:17 UTC tags: trunk comment: initial empty check-in (user: jim) :::

The extra command shows all the files in the directory that I had originally created and that are not (yet) under control of Fossil. In this case that's all of them since we have not checked in anything.

::: Shell $ fossil extra

content/introduction.md content/book.md content/ image/book/fossil.png content/index.md content/introduction.md makefile outline.txt pandoc/metadata-general.yaml :::

Note, the status message says initial empty check-in. So, Fossil provides us with some basis check-in that is empty. It is the root of your own later check-ins. Note also, you can open the repository more than once. You just need to do this in different working directories. For example, this can be used to work on different branches (see section [Forks and branches]) at the same time.

Add and initial commit

I must now add all the relevant files into the repository with the add command. The Fossil add is recursive so if I add the top level files it will automatically recurse into the subdirectories and get those files too. Before you do an add it pays to tidy up your directory so you don't accidentally add a bunch of transient files (like object files from a compile). It's easy to remove them later but a little tidying before hand can save you some work.

::: Shell $ fossil add . :::

I simply told fossil to do an add of the current directory (.) so it got all those files and all the files in the subdirectories. Note the file named _FOSSIL_ or .fslckout (depending on your operating system) that wasn't added to the repository but is located among your working files on disk. This is the tag file that fossil keeps in a directory so it knows what repository it belongs to. Fossil won't add this file since it manages it separately, but everything else is fair game.

One final thing before I can quit for the day, these files have been added or rather they will be added to the repository when I commit them. That must be done and then we can relax and let Fossil manage things.

::: Shell $ fossil commit -m "Initial Commit" :::

I added a comment text to the commit ("Initial Commit") and it's a good idea to always do this. When later we see the timeline of the commits you will have notes to tell you what was done.

Fossil start up summary

fossil new <name> : Creates a new fossil repository.

fossil open <repository> : While in a source directory connects this directory to the fossil repository.

fossil add . : Will add (recursively) all the files in the current directory and all subdirectories to the repository.

fossil commit -m "Initial Commit" : Will put all the currently added files into the repository.

Set up user interface

One of the surprising features of Fossil is the webserver. This allows it to have a GUI type user interface with no operating system specific code, the GUI is the web browser supplied by your OS. In the previous steps I checked in my project to a Fossil repository, next I have to prepare the web interface for production use.

::: Note The Fossil web server uses the first available port starting at 8080 instead of the standard port 80 for all HTTP access. When run it will automatically start your Web browser and open the repository home page.

Fossil automatically finds an open port and will give a message on the command line telling you what port number is used. You can still use the -port option if you want to control the port number. :::

::: Shell $ fossil ui :::

This command shows how it's started. When I do this my browser starts if it is not running already and I am presented with the following home page:

Note, that the fossil ui command only gives you this home page when you are using it in a directory with an open check-out. The UI can not operate without a repository (but you can ask it to show a specific repository when you are not in a directory with an open check-out by supplying the file name of the repository ... and it doesn't even have to be "open").

Following the advice on the page I go to setup/config. I am going to do the minimum setup that you should do on all projects. As you get familiar with Fossil you will probably have many more things that you will customize for your taste but what follows are the only things you have to do.

I have entered in a project name and put in a description, the project name will be the name of the initial Wiki page (see section [Wiki]) and the description is useful for others to see what you are doing here. Then I go to the bottom of the page and pick the Apply Changes button.

Next I pick the Admin tab (you can see it in the header bar) and then pick Users from that page. I am presented with the users and will use this to set the password of the project. See section [Fossil configuration] for details on what else you can customize from the Admin page.

As you can see, Fossil automatically configures a number of users beyond just the creator. The anonymous user you have already seen if you went to the Fossil web site to download the code. This user can view and get code but cannot commit code. On the right side of the page are the many options you can give to a user, it's worth reading it all when you set up your repository. The important one is me (jim) which has "s" or "Super User Capabilities". This means I can do anything with the repository.

I will now edit the user "Jim" to make sure it has the settings I want. In this case you must set the password. Remember way back where Fossil set it during the creation of the repositroy (Figure[fig:Create-Repository]), it's a very good idea to change this to something you can remember rather than the original random one.

I have put in my contact information (e-mail address) and while you cannot see it I have typed in a password that I will remember. Then I applied the changes.

Now the repository is ready for further work, it's rather bare bones at this point but the most important things are set up.

User interface summary

fossil ui : Run in the source directory will start a browser based user interface to fossil.

fossil ui -port <IP port #> : Can be used if port 8080 if already in use on your system.

On the first run it is important to configure your project with a name and set the password for yourself.

Update repository

After writing the above section of the book I now have created a some new files and changed some of the existing files in the repository. Before quitting for the day I should add these new files into the repository and commit the changes saving this milestone in the project.

::: Shell $ fossil extra :::

<!-- should the command output above list something? -->

I run fossil extra to see these new files. Choose the ones to add and note if there are perhaps any temporary files that should not be stored in the repository. I also ran fossil status. This shows changes to files that are already in the repository. The only files changed are content/introduction.md and content/single-user.md.

All I have to do now is add in the directory content/image which will add in the image files I want in the repository. Then I commit the changes to the repository and we can move on to other tasks of the day.

::: Shell $ fossil add content/image :::

After doing this commit I can bring up the Fossil ui (see section [Remote server]) and view the project Timeline by picking that tab on the Fossil header. We get this:

 Timeline placeholder

You can see all my check-ins thus far and you can see after the check-in from Figure [fig:Update-for-new] I did another check-in because I missed some changes in the outline. The check-ins are labeled with the first 10 digits of their hash value and these are active links which you can click to view in detail what was changed in that version.

I clicked on the very last check-in (the LEAF) and the display is shown above. There are many things you can do at this point. From the list of changed files you can pick the diff link and it will show in text form the changes made in that particular file. The Other Links section has a very useful ZIP Archive. Clicking this will download a ZIP of this version to your browser. You will find this useful if you want to get a particular version, in fact this is normally how you get a new version of Fossil from https://fossil-scm.org/. The edit link will be used later to modify a leaf.

Update summary

fossil status : will tell you the updated files before you commit.

fossil extra : will list files not in the repository.

fossil commit - m "Commit comment" : Commits a change (or changes). It is very important to have a descriptive comment on your commit.

Tickets

Besides managing your code Fossil has a trouble ticket system. This means you can create a ticket for a problem or feature you are going to add to your system then track your progress. Also you can tie the tickets to specific check-ins of your files. For software this is very useful for bug fixes and feature additions. For example you can look for a bug in the ticket list then have it take you to the change that fixed the problem. Then you know exactly what you did and not have to be confused by other changes you might have made.

When you click on Tickets in the menu it will bring up this window. You can create a new ticket, look at the list, or generate a new report. Keeping things simple I will just use the All Tickets list for now.

 Initial Ticket Window placeholder

Picking New Ticket I get a form that I fill out like so:

 Ticket Form placeholder

Pretty simple actually. You can put as much or as little detail in here as you wish, but remember this stuff might be really vital six weeks or six months from now so think of what you would want to know then.

Note, there is no Submit button now. I need to click on Preview in order to check how the ticket will be formatted before I can submit (and there are four different ways of formatting tickets). When everything is OK, I press Submit. I get this showing what I entered.

 Viewing a Ticket placeholder

Finally picking Tickets then All Tickets I can see my new ticket in the list marked as "Open" and in a distinctive color.

 Ticket List with open ticket placeholder

I try, in handling tickets, to have links from ticket to the commit that addressed the problem and a link from the commit back to the offending ticket. This way looking at the ticket I can get to the changes made and from the timeline I can get to the ticket and its resolution. To do this I will make sure and put the 10 digit hash label from the ticket into the check-in comment and put a link in the resolved ticket to the check-in.

Since I have now written the chapter and put in all these images of what to do I can now add in all the new images to the repository and check this in as another completed operation. And I do that like this:

::: Shell $ fossil add Images/single-user :::

First I added in all the new image files. I am lazy and just told it to add in all the files in the single-user directory. I have previously added some of those like config-initial.png but Fossil is smart and knows this and won't add that one twice. Even though it shows it "ADDED", it really didn't.

The commit line is very important, as you can see I put the 10 digit hash code for the ticket in brackets in the comment. As we will see in the Wiki section (section [Wiki]) this is a link to the ticket, so when viewing the comment in the timeline or elsewhere you can click the bracketed item and you would go to the ticket.

Now that I have the items checked in I have to close the ticket. I do that by clicking on its link in the ticket list, that will go the the View Ticket window as shown in Figure [fig:viewticket]. From there I pick edit and fill it in as shown:

figure placeholder

I mark it as "Closed". If you have code you can mark this as fixed, tested, or a number of other choices. Another very important step, I brought up the timeline and copied the link for the commit I had just done in Figure [fig:checkin]. By doing this my ticket is now cross linked with the commit and the commit has a link back to the ticket.

Ticket summary

• Tickets are a useful way of reminding you what needs done or bugs fixed
• When you commit a change that affects a ticket, put the 10 digit hash label of the ticket into the commit comment surrounded by brackets, e.g. [<10 digit hash>] so you can link to the ticket
• When you close the ticket put in the hash label of the commit that fixed it.

::: Note The ticket system is widely customizable. See section [Ticket configuration]. :::

Wiki

As we saw in Figure [fig:Starting-Webserver] Fossil has a browser based user interface. In addition to the pages that are built in you can add pages to that web site via a wiki. This allows you to add code descriptions, user manuals or other documentation. Fossil keeps all that stuff in one place under version control. A wiki is a web site where you can add pages and links from within your browser. Clicking on New in the submenu on the Wiki web page will create a new page for you where you can start editing right away. You just need to provide a page name and specify the markup language you want o use for that page (yes, it can be different for each page!).

The page shown in the web when clicking on Home in the menu is also just a Wiki page. By default (when not changed in the setup), this page is called 'home'. Initially it is a stub, meaning there is no specific Wiki page with that name. In order to create you custom home page, you need to create it. Just create a Wiki page as described above and give it a name that you want to have for it (it can be "home" but also any other name). When you pick the project name that you may have specified in the Admin > Confuration menu as the name for your home page, Fossil will show that page automatically as the home page. When you choose another name for the page, tell Fossil that this page is your home page by also going to the Admin menu and clicking on Configuration in the list that appears. Here, you can specify the Wiki page that should serve as the home page in the entry called "Index Page". There, you want to enter: /wiki?name=myPageName when the name "myPageName" was the name of the page you chose.

The Wiki pages are automatically managed by Fossil's version control system. You don't have to add or commit.

Since I did the setup on the repository (see Figure [fig:Initial-Configuration]) the home page has changed to this:

Home page placeholder

Not very helpful, so in the rest of this chapter I will use the Wiki functions of Fossil to make this more useful. If I pick the Wiki item from the menu bar I get:

Wiki page placeholder

These are the controls that let you manage and modify the wiki. In essence, this is the 'Help' page of the wiki. Most important for now is the Formatting rules link. This link takes you to a page that describes what you can do to format a wiki page. If you just type text on a page it will appear but be formatted by your browser. You can type HTML commands to control this formatting. It's worth your time to carefully read this page and note what you can and cannot do. The page just lists the valid HTML commands, and if you don't know what they mean, I would suggest you find a page like this https://web.stanford.edu/group/csp/cs21/htmlcheatsheet.pdf and keep it handy.

::: Note The wiki is customizable. E.g. you may want to show the list of wiki pages instead of the help page when picking the wiki from Fossil's menu. See section [Wiki configuration] for this and for other details. :::

Wiki formatting

I now begin work. What I want to do is change the home page to be non-empty and also put a link on the home page to the PDF of this book. In Figure [fig:Wiki-controls] I click on the first item, the FossilBook home page. This takes me to the home page again but now I have an "Edit" option. We also have a "History" option so I could look at older versions of the page.

This shows my initial edit and a preview:

The page shows an edit window where I type things I want displayed and at the top is a row of tabs inclusing a "Preview" tab showing how the page will look like. As you can see I typed some simple HTML to make a large and centered title. The body of the text I just typed and as you see the browser fits the text to the screen. You can have multiple paragraphs by just putting blank lines between your text. Next I wanted a bulleted list and this is done by typing two spaces, a '*' then two more spaces. On each of these lines I have a link to a new (not yet created page). If you look I put these in the form [<new page> | <title> ]. This way I can have a long string that describes the link but have a nice short (no embedded spaces) page name.

OK, I will save my changes and then go to the new pages. I am doing some complicated things here. The first link is to the book PDF. This will be a file I create in the repository. The Pandoc program I'm using creates the PDF. I will do that, save it, and add it to the repository. But I don't want to link to a static file, that is I want the most current version of the PDF, the one I save each time I quit for the day. To do this we have to put in a link that looks like this:

[http:doc/tip/FossilBook.pdf | Book (pdf) ]

This is a special link the Fossil wiki understands, doc says this is documentation. tip says use the most current version (you could also put a version hash here instead). And finally since I am going to put the book PDF at the top level I only need the file name. If it was in a subdirectory I would have to say doc/tip/subdir/filename.

The second link is just to a regular page and I can just edit that one just like I did this the main page.

Wiki summary

• Format your text using HTML commands such as <h1>Title</h1> for page headings
• Create and link pages using [<page> | <Link text>]
• The page designation http:doc/tip/\<document path relative to repository> will display any document in the repository that your browser can handle (i.e. pdf, http etc)
• Never click on a link till after you have saved the page