Fossil: Documentation

ls

The ls* command is informational, it doesn't do anything to a checked-out project, but it tells you something about it.

A project consists of a "source tree" of "artifacts" (see Fossil concepts.) From a practical standpoint this is a set of files and directories rooted at a main project directory. The files that are under source control aren't particularly distinguishable from those that aren't. The ls and extra commands provide this information.

fossil ls produces a listing of the files which are under source control and their status within the repository. The output is a simple list of STATUS/filepath pairs on separate lines. The status of a file will likely be one of ADDED, UNCHANGED, UPDATED, or DELETED. *

It's important to realize that this is the status relative to the repository, it's the status as fossil sees it and has nothing to do with filesystem status. If you're new to source-management/version-control systems, you'll probably get bit by this concept-bug at least once.

To really see the difference, issue an ls before and after doing a commit. Before, the status of files may be any of the three, but after committing changes the status will be UNCHANGED "across the board."

By way of example, here's what I see if I fossil ls in the directory where I have checked out my testing repository:

    $ fossil ls
    ADDED     feegboing
    UNCHANGED fossil_docs.txt
    DELETED   nibcrod

But if I do a simple ls, what I get is

    $ ls
    feegboing  fossil_docs.txt  manifest.uuid  noodle.txt
    _FOSSIL_   manifest         nibcrod

The ls command is almost, but not quite entirely, the exact opposite of the extra command.

Notes:

If you come from the Windows world, it will help to know that 'ls' is the usual unix command for listing a directory.
There are more states for a file to be in than those listed, including MISSING, EDITED, RENAMED and a couple of others.