Fossil SCM

Now covering the Fossil 2.14 "fossil clone URI" feature in the gitusers doc.

wyoung 2020-11-01 23:03 trunk

Commit 77541c8b29ca33f3547107c79d4bdc4150cf8a8a12704509c4ddd8019d23b0d4

Parent 26aa4eac2d62a5a…

1 file changed +53 -21

M www/gitusers.md

+53 -21

		--- www/gitusers.md
		+++ www/gitusers.md
		@@ -55,12 +55,12 @@
55	55	#### <a id="rname"></a> Naming Repositories
56	56
57	57	The Fossil repository database file can be named anything
58	58	you want, with a single exception: if you’re going to use the
59	59	[`fossil server DIRECTORY`][server] feature, the repositories you wish
60		-to serve need to be stored together in a flat directory and have a
61		-"`.fossil`" suffix. That aside, you can follow any other convention that
	60	+to serve need to be stored together in a flat directory and have
	61	+"`.fossil`" suffixes. That aside, you can follow any other convention that
62	62	makes sense to you.
63	63
64	64	This author uses a scheme like the following on mobile machines that
65	65	shuttle between home and the office:
66	66
		@@ -75,50 +75,82 @@
75	75
76	76	arrow down 50% from 2nd vertex of previous arrow then right 50%
77	77	box "other/" fit ; line dashed right until even with previous text.w ; "clones of Fossil itself, SQLite, etc."
78	78	```
79	79
80		-On a Windows box, you might choose "`C:\Fossils`" instead, for example.
	80	+On a Windows box, you might choose "`C:\Fossils`" instead
	81	+and do without the subdirectory scheme, for example.
81	82
82	83
83	84	#### <a id="scw"></a> Single-Checkout Workflows
84	85
85		-You can use Fossil in the typical Git way, switching between versions in a
86		-single check-out directory:
	86	+The most idiomatic way to use Fossil in the typical Git way — switching
	87	+between versions in a single check-out directory — is as follows:
87	88
88	89	fossil clone https://example.com/repo /path/to/repo.fossil
89	90	mkdir work-dir
90	91	cd work-dir
91	92	fossil open /path/to/repo.fossil
92	93	...work on trunk...
93	94	fossil update my-other-branch # like “git checkout”
94	95	...work on your other branch in the same directory...
95	96
96		-As of Fossil 2.12, you can ask it to clone-and-open into a single directory, as Git
97		-always has done:
	97	+In Fossil 2.12, we added a feature that allows you to get closer to
	98	+Git’s single-step clone-and-open behavior:
98	99
99	100	mkdir work-dir
100	101	cd work-dir
101	102	fossil open https://example.com/repo
102	103
103	104	Now you have “trunk” open in `work-dir`, with the repo file stored as
104	105	`repo.fossil` in that same directory.
105	106
106		-You may be expecting [`fossil clone`][clone] to create a directory for
107		-you like Git does, but because the repository is separate from the
108		-working directory, it does not do that, on purpose: you have to tell it
109		-where to store the repository file.
110		-
111		-The [`fossil open URI`][open] syntax is our compromise for users wanting
112		-a clone-and-open command. But, because Fossil’s `open` command
113		-historically opens into the current directory, and it won’t open a
114		-repository into a non-empty directory by default — as of Fossil 2.12,
115		-anyway — you have to create the directory manually and `cd` into it
116		-before opening it. If `fossil open URI` worked like `git clone`, that
117		-would mean `fossil open` has two different ways of working depending on
118		-the argument, which is a non-Fossil sort of thing to do. We strive for
119		-consistent behavior across commands and modes.
	107	+The use of [`fossil open`][open] here instead of [`fossil clone`][clone]
	108	+likely surprises you as a Git user. When we were [discussing][caod]
	109	+this, we considered following the Git command style, but we decided
	110	+against it because it goes against this core Fossil design principle:
	111	+given that the Fossil repo is separate from the check-out, why would you
	112	+expect asking for a repo clone to also create a check-out directory for
	113	+you? We view commingled repository + check-out as a design error in
	114	+Git, so why would we repeat the error?
	115	+
	116	+To see why we see this behavior is error-prone, consider that
	117	+`git clean` must have an exception to avoid nuking the `.git` directory.
	118	+We had to add that complication to `fossil clean` when we added the
	119	+`fossil open URI` feature: it won’t nuke the repo DB file.
	120	+
	121	+This feature didn’t placate many Git fans, though, so with Fossil 2.14 —
	122	+currently unreleased — we now allow this:
	123	+
	124	+ fossil clone https://fossil-scm.org/fossil
	125	+
	126	+This results in a `fossil.fossil` repo DB file and a `fossil/` working
	127	+directory.
	128	+
	129	+Note that our `clone URI` behavior does not commingle the repo and
	130	+check-out, solving our major problem with the Git design, though we
	131	+still believe it to be confusing to have “clone” be part of “open,” and
	132	+still more confusing to have “open” part of “clone.” We prefer keeping
	133	+these operations entirely separate, either as at the [top of this
	134	+section](#scw) or [as in the next one](#mcw). Still, please yourself.
	135	+
	136	+If you want the repo to be named something else, adjust the URL:
	137	+
	138	+ fossil clone https://fossil-scm.org/fossil/fsl
	139	+
	140	+That gets you `fsl.fossil` checked out into `fsl/`.
	141	+
	142	+For sites where the repo isn’t served from a subdirectory like this, you
	143	+might need another form of the URL. For example, you might have your
	144	+repo served from `dev.example.com` and want it cloned as `my-project`:
	145	+
	146	+ fossil clone https://dev.example.com/repo/my-project
	147	+
	148	+The `/repo` addition is the key: whatever comes after is used as the
	149	+repository name. [See the docs][clone] for more details.
	150	+
	151	+[caod]: https://fossil-scm.org/forum/forumpost/3f143cec74
120	152
121	153
122	154	#### <a id="mcw"></a> Multiple-Checkout Workflows
123	155
124	156	Because Fossil cleanly separates the repository from the check-out, it
125	157

	--- www/gitusers.md
	+++ www/gitusers.md
	@@ -55,12 +55,12 @@
55	#### <a id="rname"></a> Naming Repositories
56
57	The Fossil repository database file can be named anything
58	you want, with a single exception: if you’re going to use the
59	[`fossil server DIRECTORY`][server] feature, the repositories you wish
60	to serve need to be stored together in a flat directory and have a
61	"`.fossil`" suffix. That aside, you can follow any other convention that
62	makes sense to you.
63
64	This author uses a scheme like the following on mobile machines that
65	shuttle between home and the office:
66
	@@ -75,50 +75,82 @@
75
76	arrow down 50% from 2nd vertex of previous arrow then right 50%
77	box "other/" fit ; line dashed right until even with previous text.w ; "clones of Fossil itself, SQLite, etc."
78	```
79
80	On a Windows box, you might choose "`C:\Fossils`" instead, for example.

81
82
83	#### <a id="scw"></a> Single-Checkout Workflows
84
85	You can use Fossil in the typical Git way, switching between versions in a
86	single check-out directory:
87
88	fossil clone https://example.com/repo /path/to/repo.fossil
89	mkdir work-dir
90	cd work-dir
91	fossil open /path/to/repo.fossil
92	...work on trunk...
93	fossil update my-other-branch # like “git checkout”
94	...work on your other branch in the same directory...
95
96	As of Fossil 2.12, you can ask it to clone-and-open into a single directory, as Git
97	always has done:
98
99	mkdir work-dir
100	cd work-dir
101	fossil open https://example.com/repo
102
103	Now you have “trunk” open in `work-dir`, with the repo file stored as
104	`repo.fossil` in that same directory.
105
106	You may be expecting [`fossil clone`][clone] to create a directory for
107	you like Git does, but because the repository is separate from the
108	working directory, it does not do that, on purpose: you have to tell it
109	where to store the repository file.
110
111	The [`fossil open URI`][open] syntax is our compromise for users wanting
112	a clone-and-open command. But, because Fossil’s `open` command
113	historically opens into the current directory, and it won’t open a
114	repository into a non-empty directory by default — as of Fossil 2.12,
115	anyway — you have to create the directory manually and `cd` into it
116	before opening it. If `fossil open URI` worked like `git clone`, that
117	would mean `fossil open` has two different ways of working depending on
118	the argument, which is a non-Fossil sort of thing to do. We strive for
119	consistent behavior across commands and modes.































120
121
122	#### <a id="mcw"></a> Multiple-Checkout Workflows
123
124	Because Fossil cleanly separates the repository from the check-out, it
125

	--- www/gitusers.md
	+++ www/gitusers.md
	@@ -55,12 +55,12 @@
55	#### <a id="rname"></a> Naming Repositories
56
57	The Fossil repository database file can be named anything
58	you want, with a single exception: if you’re going to use the
59	[`fossil server DIRECTORY`][server] feature, the repositories you wish
60	to serve need to be stored together in a flat directory and have
61	"`.fossil`" suffixes. That aside, you can follow any other convention that
62	makes sense to you.
63
64	This author uses a scheme like the following on mobile machines that
65	shuttle between home and the office:
66
	@@ -75,50 +75,82 @@
75
76	arrow down 50% from 2nd vertex of previous arrow then right 50%
77	box "other/" fit ; line dashed right until even with previous text.w ; "clones of Fossil itself, SQLite, etc."
78	```
79
80	On a Windows box, you might choose "`C:\Fossils`" instead
81	and do without the subdirectory scheme, for example.
82
83
84	#### <a id="scw"></a> Single-Checkout Workflows
85
86	The most idiomatic way to use Fossil in the typical Git way — switching
87	between versions in a single check-out directory — is as follows:
88
89	fossil clone https://example.com/repo /path/to/repo.fossil
90	mkdir work-dir
91	cd work-dir
92	fossil open /path/to/repo.fossil
93	...work on trunk...
94	fossil update my-other-branch # like “git checkout”
95	...work on your other branch in the same directory...
96
97	In Fossil 2.12, we added a feature that allows you to get closer to
98	Git’s single-step clone-and-open behavior:
99
100	mkdir work-dir
101	cd work-dir
102	fossil open https://example.com/repo
103
104	Now you have “trunk” open in `work-dir`, with the repo file stored as
105	`repo.fossil` in that same directory.
106
107	The use of [`fossil open`][open] here instead of [`fossil clone`][clone]
108	likely surprises you as a Git user. When we were [discussing][caod]
109	this, we considered following the Git command style, but we decided
110	against it because it goes against this core Fossil design principle:
111	given that the Fossil repo is separate from the check-out, why would you
112	expect asking for a repo clone to also create a check-out directory for
113	you? We view commingled repository + check-out as a design error in
114	Git, so why would we repeat the error?
115
116	To see why we see this behavior is error-prone, consider that
117	`git clean` must have an exception to avoid nuking the `.git` directory.
118	We had to add that complication to `fossil clean` when we added the
119	`fossil open URI` feature: it won’t nuke the repo DB file.
120
121	This feature didn’t placate many Git fans, though, so with Fossil 2.14 —
122	currently unreleased — we now allow this:
123
124	fossil clone https://fossil-scm.org/fossil
125
126	This results in a `fossil.fossil` repo DB file and a `fossil/` working
127	directory.
128
129	Note that our `clone URI` behavior does not commingle the repo and
130	check-out, solving our major problem with the Git design, though we
131	still believe it to be confusing to have “clone” be part of “open,” and
132	still more confusing to have “open” part of “clone.” We prefer keeping
133	these operations entirely separate, either as at the [top of this
134	section](#scw) or [as in the next one](#mcw). Still, please yourself.
135
136	If you want the repo to be named something else, adjust the URL:
137
138	fossil clone https://fossil-scm.org/fossil/fsl
139
140	That gets you `fsl.fossil` checked out into `fsl/`.
141
142	For sites where the repo isn’t served from a subdirectory like this, you
143	might need another form of the URL. For example, you might have your
144	repo served from `dev.example.com` and want it cloned as `my-project`:
145
146	fossil clone https://dev.example.com/repo/my-project
147
148	The `/repo` addition is the key: whatever comes after is used as the
149	repository name. [See the docs][clone] for more details.
150
151	[caod]: https://fossil-scm.org/forum/forumpost/3f143cec74
152
153
154	#### <a id="mcw"></a> Multiple-Checkout Workflows
155
156	Because Fossil cleanly separates the repository from the check-out, it
157

Fossil SCM

Keyboard Shortcuts