1#!/usr/bin/tclsh
2#
3# Run this to generate the FAQ
4#
5set cnt 1
6proc faq {question answer} {
7  set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
8  incr ::cnt
9}
10
11faq {
12  What GUIs are available for fossil?
13} {
14  The fossil executable comes with a [./webui.wiki | web-based GUI] built in.
15  Just run:
16
17  <blockquote>
18  <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i>
19  </blockquote>
20
21  And your default web browser should pop up and automatically point to
22  the fossil interface.  (Hint:  You can omit the <i>REPOSITORY-FILENAME</i>
23  if you are within an open check-out.)
24}
25
26faq {
27  What is the difference between a "branch" and a "fork"?
28} {
29  This is a big question - too big to answer in a FAQ.  Please
30  read the <a href="branching.wiki">Branching, Forking, Merging,
31  and Tagging</a> document.
32}
33
34
35faq {
36  How do I create a new branch?
37} {
38  There are lots of ways:
39
40  When you are checking in a new change using the <b>[/help/commit|commit]</b>
41  command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
42  make the new check-in be the first check-in for a new branch.
43
44  If you want to create a new branch whose initial content is the
45  same as an existing check-in, use this command:
46
47  <blockquote>
48  <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i>
49  </blockquote>
50
51  The <i>BRANCH-NAME</i> argument is the name of the new branch and the
52  <i>BASIS</i> argument is the name of the check-in that the branch splits
53  off from.
54
55  If you already have a fork in your check-in tree and you want to convert
56  that fork to a branch, you can do this from the web interface.
57  First locate the check-in that you want to be
58  the initial check-in of your branch on the timeline and click on its
59  link so that you are on the <b>ci</b> page.  Then find the "<b>edit</b>"
60  link (near the "Commands:" label) and click on that.  On the
61  "Edit Check-in" page, check the box beside "Branching:" and fill in
62  the name of your new branch to the right and press the "Apply Changes"
63  button.
64}
65
66faq {
67  How do I tag a check-in?
68} {
69  There are several ways:
70
71  When you are checking in a new change using the <b>[/help/commit|commit]</b>
72  command, you can add a tag to that check-in using the
73  "--tag <i>TAGNAME</i>" command-line option.  You can repeat the --tag
74  option to give a check-in multiple tags.  Tags need not be unique.  So,
75  for example, it is common to give every released version a "release" tag.
76
77  If you want add a tag to an existing check-in, you can use the
78  <b>[/help/tag|tag]</b> command.  For example:
79
80  <blockquote>
81  <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i>
82  </blockquote>
83
84  The CHECK-IN in the previous line can be any
85  [./checkin_names.wiki | valid check-in name format].
86
87  You can also add (and remove) tags from a check-in using the
88  [./webui.wiki | web interface].  First locate the check-in that you
89  what to tag on the timeline, then click on the link to go the detailed
90  information page for that check-in.  Then find the "<b>edit</b>"
91  link (near the "Commands:" label) and click on that.  There are
92  controls on the edit page that allow new tags to be added and existing
93  tags to be removed.
94}
95
96faq {
97  How do I create a private branch that won't get pushed back to the
98  main repository.
99} {
100  Use the <b>--private</b> command-line option on the
101  <b>commit</b> command.  The result will be a check-in which exists on
102  your local repository only and is never pushed to other repositories.
103  All descendants of a private check-in are also private.
104
105  Unless you specify something different using the <b>--branch</b> and/or
106  <b>--bgcolor</b> options, the new private check-in will be put on a branch
107  named "private" with an orange background color.
108
109  You can merge from the trunk into your private branch in order to keep
110  your private branch in sync with the latest changes on the trunk.  Once
111  you have everything in your private branch the way you want it, you can
112  then merge your private branch back into the trunk and push.  Only the
113  final merge operation will appear in other repositories.  It will seem
114  as if all the changes that occurred on your private branch occurred in
115  a single check-in.
116  Of course, you can also keep your branch private forever simply
117  by not merging the changes in the private branch back into the trunk.
118
119  [./private.wiki | Additional information]
120}
121
122faq {
123  How can I delete inappropriate content from my fossil repository?
124} {
125  See the article on [./shunning.wiki | "shunning"] for details.
126}
127
128faq {
129  How do I make a clone of the fossil self-hosting repository?
130} {
131  Any of the following commands should work:
132  <blockquote><pre>
133  fossil [/help/clone|clone]  http://fossil-scm.org/  fossil.fossil
134  fossil [/help/clone|clone]  http://www2.fossil-scm.org/  fossil.fossil
135  fossil [/help/clone|clone]  http://www3.fossil-scm.org/site.cgi  fossil.fossil
136  </pre></blockquote>
137  Once you have the repository cloned, you can open a local check-out
138  as follows:
139  <blockquote><pre>
140  mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil
141  </pre></blockquote>
142  Thereafter you should be able to keep your local check-out up to date
143  with the latest code in the public repository by typing:
144  <blockquote><pre>
145  fossil [/help/update|update]
146  </pre></blockquote>
147}
148
149faq {
150  How do I import or export content from and to other version control systems?
151} {
152  Please see [./inout.wiki | Import And Export]
153}
154
155
156
157#############################################################################
158# Code to actually generate the FAQ
159#
160puts "<title>Fossil FAQ</title>"
161puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n"
162puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n"
163
164puts {<ol>}
165for {set i 1} {$i<$cnt} {incr i} {
166  puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
167}
168puts {</ol>}
169puts {<hr>}
170
171for {set i 1} {$i<$cnt} {incr i} {
172  puts "<p id=\"q$i\"><b>($i) [lindex $faq($i) 0]</b></p>\n"
173  set body [lindex $faq($i) 1]
174  regsub -all "\n *" [string trim $body] "\n" body
175  puts "<blockquote>$body</blockquote></li>\n"
176}
177puts {</ol>}
178