Background

The default behavior of Fossil is to share everything (all check-ins, tickets, wiki, etc) between all clients and all servers. Such a policy helps to promote a cohesive design for a cathedral-style project run by a small cliche of developers - the sort of project for which Fossil was designed.

But sometimes it is desirable to branch off a side project that does not sync back to the master but does continue to track changes in the master. For example, the master project might be an open-source project like SQLite and a team might want to do a proprietary closed-source enhancement to that master project in a separate repository. All changes in the master project should flow forward into the derived project, but care must be taken to prevent proprietary content from the derived project from leaking back into the master.

Child Projects

A scenario such as the above can be accomplished in Fossil by creating a child project. The child project is able to freely pull from the parent, but the parent cannot push or pull from the child nor is the child able to push to the parent. Content flows from parent to child only, and then only at the request of the child.

Creating a Child Project

To create a new child project, first clone the parent. Then make manual SQL changes to the child repository as follows:

UPDATE config SET name='parent-project-code' WHERE name='project-code';
UPDATE config SET name='parent-project-name' WHERE name='project-name';
INSERT INTO config(name,value)
   VALUES('project-code',lower(hex(randomblob(20))));
INSERT INTO config(name,value)
   VALUES('project-name','CHILD-PROJECT-NAME');

Modify the CHILD-PROJECT-NAME in the last statement to be the name of the child project, of course.

The repository is now a separate project, independent from its parent. Clone the new project to the developers as needed.

The child project and the parent project will not normally be able to sync with one another, since they are now separate projects with distinct project codes. However, if the "--from-parent-project" command-line option is provided to the "fossil pull" command in the child, and the URL of parent repository is also provided on the command-line, then updates to the parent project that occurred after the child was created will be added to the child repository. Thus, by periodically doing a pull --from-parent-project, the child project is able to stay up to date with all the latest changes in the parent.