|
1
|
# Check-Out Workflows |
|
2
|
|
|
3
|
Because Fossil separates the concept of “check-out directory” from |
|
4
|
“repository DB file,” it gives you the freedom to choose from several |
|
5
|
working styles. Contrast Git, where the two concepts are normally |
|
6
|
intermingled in a single working directory, which strongly encourages |
|
7
|
the “update in place” working style. |
|
8
|
|
|
9
|
|
|
10
|
## <a id="mcw"></a> Multiple-Checkout Workflow |
|
11
|
|
|
12
|
With Fossil, it is routine to have multiple check-outs from the same |
|
13
|
repository: |
|
14
|
|
|
15
|
fossil clone https://example.com/repo /path/to/repo.fossil |
|
16
|
|
|
17
|
mkdir -p ~/src/my-project/trunk |
|
18
|
cd ~/src/my-project/trunk |
|
19
|
fossil open /path/to/repo.fossil # implicitly opens “trunk” |
|
20
|
|
|
21
|
mkdir ../release |
|
22
|
cd ../release |
|
23
|
fossil open /path/to/repo.fossil release |
|
24
|
|
|
25
|
mkdir ../my-other-branch |
|
26
|
cd ../my-other-branch |
|
27
|
fossil open /path/to/repo.fossil my-other-branch |
|
28
|
|
|
29
|
mkdir ../scratch |
|
30
|
cd ../scratch |
|
31
|
fossil open /path/to/repo.fossil abcd1234 |
|
32
|
|
|
33
|
mkdir ../test |
|
34
|
cd ../test |
|
35
|
fossil open /path/to/repo.fossil 2019-04-01 |
|
36
|
|
|
37
|
Now you have five separate check-out directories: one each for: |
|
38
|
|
|
39
|
* trunk |
|
40
|
* the latest tagged public release |
|
41
|
* an alternate branch you’re working on |
|
42
|
* a “scratch” directory for experiments you don’t want to do in the |
|
43
|
other check-out directories; and |
|
44
|
* a “test” directory where you’re currently running a long-running |
|
45
|
test to evaluate a user bug report against the version as of last |
|
46
|
April Fool’s Day. |
|
47
|
|
|
48
|
Each check-out operates independently of the others. |
|
49
|
|
|
50
|
This multiple-checkouts working style is especially useful when Fossil stores source code in programming languages |
|
51
|
where there is a “build” step that transforms source files into files |
|
52
|
you actually run or distribute. Contrast a switch-in-place workflow, |
|
53
|
where you have to rebuild all outputs from the source files |
|
54
|
that differ between those versions whenever you switch versions. In the above model, |
|
55
|
you switch versions with a “`cd`” command instead, so that you only have |
|
56
|
to rebuild outputs from files you yourself change. |
|
57
|
|
|
58
|
This style is also useful when a check-out directory may be tied up with |
|
59
|
some long-running process, as with the “test” example above, where you |
|
60
|
might need to run an hours-long brute-force replication script to tickle |
|
61
|
a [Heisenbug][hb], forcing it to show itself. While that runs, you can |
|
62
|
open a new terminal tab, “`cd ../trunk`”, and get back |
|
63
|
to work. |
|
64
|
|
|
65
|
[hb]: https://en.wikipedia.org/wiki/Heisenbug |
|
66
|
|
|
67
|
|
|
68
|
|
|
69
|
## <a id="scw"></a> Single-Checkout Workflows |
|
70
|
|
|
71
|
Nevertheless, it is possible to work in a more typical Git sort of |
|
72
|
style, switching between versions in a single check-out directory. |
|
73
|
|
|
74
|
#### <a id="idiomatic"></a> The Idiomatic Fossil Way |
|
75
|
|
|
76
|
The most idiomatic way is as follows: |
|
77
|
|
|
78
|
fossil clone https://example.com/repo /path/to/repo.fossil |
|
79
|
mkdir work-dir |
|
80
|
cd work-dir |
|
81
|
fossil open /path/to/repo.fossil |
|
82
|
...work on trunk... |
|
83
|
|
|
84
|
fossil update my-other-branch |
|
85
|
...work on your other branch in the same directory... |
|
86
|
|
|
87
|
Basically, you replace the `cd` commands in the multiple checkouts |
|
88
|
workflow above with `fossil up` commands. |
|
89
|
|
|
90
|
|
|
91
|
#### <a id="open"></a> Opening a Repository by URI |
|
92
|
|
|
93
|
You can instead open the repo’s URI directly: |
|
94
|
|
|
95
|
mkdir work-dir |
|
96
|
cd work-dir |
|
97
|
fossil open https://example.com/repo |
|
98
|
|
|
99
|
Now you have “trunk” open in `work-dir`, with the repo file stored as |
|
100
|
`repo.fossil` in that same directory. |
|
101
|
|
|
102
|
Users of Git may be surprised that it doesn’t create a directory for you |
|
103
|
and that you `cd` into it *before* the clone-and-open step, not after. |
|
104
|
This is because we’re overloading the “open” command, which already had |
|
105
|
the behavior of opening into the current working directory. Changing it |
|
106
|
to behave like `git clone` would therefore make the behavior surprising |
|
107
|
to Fossil users. (See [our discussions][caod] if you want the full |
|
108
|
details.) |
|
109
|
|
|
110
|
|
|
111
|
#### <a id="clone"></a> Git-Like Clone-and-Open |
|
112
|
|
|
113
|
Fossil also supports a more Git-like alternative: |
|
114
|
|
|
115
|
fossil clone https://fossil-scm.org/fossil |
|
116
|
cd fossil |
|
117
|
|
|
118
|
This results in a `fossil.fossil` repo DB file and a `fossil/` working |
|
119
|
directory. |
|
120
|
|
|
121
|
Note that our `clone URI` behavior does not commingle the repo and |
|
122
|
check-out, solving our major problem with the Git design. |
|
123
|
|
|
124
|
If you want the repo to be named something else, adjust the URL: |
|
125
|
|
|
126
|
fossil clone https://fossil-scm.org/fossil/fsl |
|
127
|
|
|
128
|
That gets you `fsl.fossil` checked out into `fsl/`. |
|
129
|
|
|
130
|
For sites where the repo isn’t served from a subdirectory like this, you |
|
131
|
might need another form of the URL. For example, you might have your |
|
132
|
repo served from `dev.example.com` and want it cloned as `my-project`: |
|
133
|
|
|
134
|
fossil clone https://dev.example.com/repo/my-project |
|
135
|
|
|
136
|
The `/repo` addition is the key: whatever comes after is used as the |
|
137
|
repository name. [See the docs][clone] for more details. |
|
138
|
|
|
139
|
[caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 |
|
140
|
[clone]: /help/clone |
|
141
|
|
|
142
|
<div style="height:50em" id="this-space-intentionally-left-blank"></div> |
|
143
|
|