From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/private.wiki | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 www/private.wiki (limited to 'www/private.wiki') diff --git a/www/private.wiki b/www/private.wiki new file mode 100644 index 0000000..5bf5b07 --- /dev/null +++ b/www/private.wiki @@ -0,0 +1,121 @@ +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 [/help/merge | --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 [/doc/trunk/www/branching.wiki | 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. -- cgit v1.3.1