1 files changed, 121 insertions, 0 deletions
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 @@
+<title>Private Branches</title>
+
+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:
+
+<pre>
+fossil commit --private
+</pre>
+
+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.
+
+<h2>Publishing Private Changes</h2>
+
+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:
+
+<pre>
+fossil update trunk
+fossil merge private
+fossil commit
+</pre>
+
+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 <code>fossil publish</code>
+command.  However, there is no way to convert a private branch created with
+older versions of Fossil into a public branch.
+
+<div class="sidebar">
+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.)
+</div>
+
+The <code>--integrate</code> option of <code>fossil merge</code> (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
+<code>+close</code> 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 <code>fossil amend --close</code>
+command.
+
+<h2>Syncing Private Branches</h2>
+
+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:
+
+<verbatim>
+fossil clone --private http://user@linux.localnetwork:8080/ mac-clone.fossil
+</verbatim>
+
+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.
+
+<h2>Purging Private Branches</h2>
+
+You can remove all private branches from a repository using this command:
+
+<pre>
+fossil scrub --private
+</pre>
+
+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.
+
+<h2>Additional Notes</h2>
+
+All of the features above apply to <u>all</u> 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.