|
1
|
<title>Private Branches</title> |
|
2
|
|
|
3
|
By default, everything you check into a Fossil repository is shared |
|
4
|
to all clones of that repository. In Fossil, you don't push and pull |
|
5
|
individual branches; you push and pull everything all at once. |
|
6
|
|
|
7
|
But sometimes users want to keep some private work that is not |
|
8
|
shared with others. This might be a preliminary or experimental change |
|
9
|
that needs further refinement before it is shared and which might never |
|
10
|
be shared at all. To do this in Fossil, simply commit the change with |
|
11
|
the --private command-line option: |
|
12
|
|
|
13
|
<pre> |
|
14
|
fossil commit --private |
|
15
|
</pre> |
|
16
|
|
|
17
|
The --private option causes Fossil to put the check-in in a new branch |
|
18
|
named "private". That branch will not participate in subsequent clone, |
|
19
|
sync, push, or pull operations. The branch will remain on the one local |
|
20
|
repository where it was created. Note that you only use the --private |
|
21
|
option for the first check-in that creates the private branch. |
|
22
|
Additional checkins into the private branch remain private automatically. |
|
23
|
|
|
24
|
<h2>Publishing Private Changes</h2> |
|
25
|
|
|
26
|
After additional work, one might desire to publish the changes associated |
|
27
|
with a private branch. The usual way to do this is to merge those |
|
28
|
changes into a public branch. For example: |
|
29
|
|
|
30
|
<pre> |
|
31
|
fossil update trunk |
|
32
|
fossil merge private |
|
33
|
fossil commit |
|
34
|
</pre> |
|
35
|
|
|
36
|
The private branch remains private and is not recorded as a parent |
|
37
|
in the merge manifest's P-card, but all of the changes associated with |
|
38
|
the private branch are now folded into the public branch and are hence |
|
39
|
visible to other users of the project. |
|
40
|
|
|
41
|
A private branch created with Fossil version 1.30 or newer can also be |
|
42
|
converted into a public branch using the <code>fossil publish</code> |
|
43
|
command. However, there is no way to convert a private branch created with |
|
44
|
older versions of Fossil into a public branch. |
|
45
|
|
|
46
|
<div class="sidebar"> |
|
47
|
To avoid generating a missing artifact |
|
48
|
reference on peer repositories without the private branch, the merge parent |
|
49
|
is not recorded when merging the private branch into a public branch. As a |
|
50
|
consequence, the web UI timeline does not draw a merge line from the private |
|
51
|
merge parent to the public merge child. Moreover, repeat private-to-public |
|
52
|
merge operations (without the [/help/merge | --force option]) with files |
|
53
|
added on the private branch may only work once, but later abort with |
|
54
|
"WARNING: no common ancestor for FILE", as the parent-child relationship is |
|
55
|
not recorded. (See the [/doc/trunk/www/branching.wiki | Branching, Forking, |
|
56
|
Merging, and Tagging] document for more information.) |
|
57
|
</div> |
|
58
|
|
|
59
|
The <code>--integrate</code> option of <code>fossil merge</code> (to close |
|
60
|
the merged branch when committing) is ignored for a private branch -- or the |
|
61
|
check-in manifest of the resulting merge child would include a |
|
62
|
<code>+close</code> tag referring to the leaf check-in on the private branch, |
|
63
|
and generate a missing artifact reference on repository clones without that |
|
64
|
private branch. It's still possible to close the leaf of the private branch |
|
65
|
(after committing the merge child) with the <code>fossil amend --close</code> |
|
66
|
command. |
|
67
|
|
|
68
|
<h2>Syncing Private Branches</h2> |
|
69
|
|
|
70
|
A private branch normally stays on the one repository where it was |
|
71
|
originally created. But sometimes you want to share private branches |
|
72
|
with another repository. For example, you might be building a cross-platform |
|
73
|
application and have separate repositories on your Windows laptop, |
|
74
|
your Linux desktop, and your iMac. You can transfer private branches |
|
75
|
between these machines by using the --private option on the "sync", |
|
76
|
"push", "pull", and "clone" commands. For example, if you are running |
|
77
|
"fossil server" on your Linux box and you want to clone that repository |
|
78
|
to your Mac, including all private branches, use: |
|
79
|
|
|
80
|
<verbatim> |
|
81
|
fossil clone --private http://[email protected]:8080/ mac-clone.fossil |
|
82
|
</verbatim> |
|
83
|
|
|
84
|
You'll have to supply a username and password in order for this to work. |
|
85
|
Fossil will not clone (or sync) private branches anonymously. |
|
86
|
|
|
87
|
By default, there are no users that can do private branch syncing. You |
|
88
|
will have to give a user |
|
89
|
the "Private" capability ("x") if you want them to be able to do this. |
|
90
|
We deny such capability for normal users by default to add a barrier to |
|
91
|
accidental syncing of a private branch to a public server. It is highly recommended that |
|
92
|
you leave the "x" capability turned off on all repositories used for |
|
93
|
collaboration (repositories to which many people push and pull) and |
|
94
|
only enable "x" for local repositories when you need to share private |
|
95
|
branches. |
|
96
|
|
|
97
|
Private branch sync only works if you use the --private command-line option. |
|
98
|
Private branches are never synced via the auto-sync mechanism. Once |
|
99
|
again, this restriction is designed to make it hard to accidentally |
|
100
|
push private branches beyond their intended audience. |
|
101
|
|
|
102
|
<h2>Purging Private Branches</h2> |
|
103
|
|
|
104
|
You can remove all private branches from a repository using this command: |
|
105
|
|
|
106
|
<pre> |
|
107
|
fossil scrub --private |
|
108
|
</pre> |
|
109
|
|
|
110
|
Note that the above is a permanent and irreversible change. You will |
|
111
|
be asked to confirm before continuing. Once the private branches are |
|
112
|
removed, they cannot be retrieved (unless you have synced them to another |
|
113
|
repository.) So be careful with the command. |
|
114
|
|
|
115
|
<h2>Additional Notes</h2> |
|
116
|
|
|
117
|
All of the features above apply to <u>all</u> private branches in a |
|
118
|
single repository at once. There is no mechanism in Fossil (currently) |
|
119
|
that allows you to push, pull, clone, sync, or scrub an individual |
|
120
|
private branch within a repository that contains multiple private |
|
121
|
branches. |
|
122
|
|