Fossil: Private Branches

By default, everything you check into a Fossil repository is shared to all clones of that repository. In Fossil, you don't push and pull individual branches; you push and pull everything all at once.

But sometimes users want to keep some private work that is not shared with others. This might be a preliminary or experimental change that needs further refinement before it is shared and which might never be shared at all. To do this in Fossil, simply commit the change with the --private command-line option:

fossil commit --private

The --private option causes Fossil to put the check-in in a new branch named "private". That branch will not participate in subsequent clone, sync, push, or pull operations. The branch will remain on the one local repository where it was created. Note that you only use the --private option for the first check-in that creates the private branch. Additional checkins into the private branch remain private automatically.

Publishing Private Changes

After additional work, one might desire to publish the changes associated with a private branch. The usual way to do this is to merge those changes into a public branch. For example:

fossil update trunk
fossil merge private
fossil commit

The private branch remains private and is not recorded as a parent in the merge manifest's P-card, but all of the changes associated with the private branch are now folded into the public branch and are hence visible to other users of the project.

A private branch created with Fossil version 1.30 or newer can also be converted into a public branch using the fossil publish command. However, there is no way to convert a private branch created with older versions of Fossil into a public branch.

To avoid generating a missing artifact reference on peer repositories without the private branch, the merge parent is not recorded when merging the private branch into a public branch. As a consequence, the web UI timeline does not draw a merge line from the private merge parent to the public merge child. Moreover, repeat private-to-public merge operations (without the --force option) with files added on the private branch may only work once, but later abort with "WARNING: no common ancestor for FILE", as the parent-child relationship is not recorded. (See the Branching, Forking, Merging, and Tagging document for more information.)

The --integrate option of fossil merge (to close the merged branch when committing) is ignored for a private branch -- or the check-in manifest of the resulting merge child would include a +close tag referring to the leaf check-in on the private branch, and generate a missing artifact reference on repository clones without that private branch. It's still possible to close the leaf of the private branch (after committing the merge child) with the fossil amend --close command.

Syncing Private Branches

A private branch normally stays on the one repository where it was originally created. But sometimes you want to share private branches with another repository. For example, you might be building a cross-platform application and have separate repositories on your Windows laptop, your Linux desktop, and your iMac. You can transfer private branches between these machines by using the --private option on the "sync", "push", "pull", and "clone" commands. For example, if you are running "fossil server" on your Linux box and you want to clone that repository to your Mac, including all private branches, use:

fossil clone --private http://user@linux.localnetwork:8080/ mac-clone.fossil

You'll have to supply a username and password in order for this to work. Fossil will not clone (or sync) private branches anonymously.

By default, there are no users that can do private branch syncing. You will have to give a user the "Private" capability ("x") if you want them to be able to do this. We deny such capability for normal users by default to add a barrier to accidental syncing of a private branch to a public server. It is highly recommended that you leave the "x" capability turned off on all repositories used for collaboration (repositories to which many people push and pull) and only enable "x" for local repositories when you need to share private branches.

Private branch sync only works if you use the --private command-line option. Private branches are never synced via the auto-sync mechanism. Once again, this restriction is designed to make it hard to accidentally push private branches beyond their intended audience.

Purging Private Branches

You can remove all private branches from a repository using this command:

fossil scrub --private

Note that the above is a permanent and irreversible change. You will be asked to confirm before continuing. Once the private branches are removed, they cannot be retrieved (unless you have synced them to another repository.) So be careful with the command.

Additional Notes

All of the features above apply to all private branches in a single repository at once. There is no mechanism in Fossil (currently) that allows you to push, pull, clone, sync, or scrub an individual private branch within a repository that contains multiple private branches.