How to chisel at chiselapp.com

Difference between version 11 and 12 - Previous - Next

<<inlinehtml>></div>
<style>
img {
  filter: drop-shadow(0 0 6px black);
    -webkit-border-radius: 4px;
    -moz-border-radius: 4px;
    border-radius: 4px;
}
ap {
    color: #0000FF;
    font-family: times;
}
</style>
<p>The excellent <a href="https://www.fossil-scm.org">Fossil SCM</a> is so distinguished against the general background (most often for the better) that it is incomprehensible why this system is still underestimated in the IT community.</p>
<p>In question is not the quality of Fossil - it is the highest - but the ways of presenting it. And it’s here the issues come.</p>
<p><em>The issue #0</em>.</p>
<p>The software behemoths can only support those VCS that can satisfy their behemothic appetites. As a result, those VCS are delivered to every home as “a must”. Though you need to be behemoth to use those VCS in full.</p>
<p>So, it’s a real issue for those tended to be behemothic.</p>
<p>If you are not a behemoth and have no desire to become him, you can easily do without those fat meals served for begemoths. It means less dependence, less ‘learning curve’, less headache. It means more mobility, more time, more health. It means you can do it with Fossil SCM.</p>
<p>So, it’s a zero value issue for those tended to be non-behemothic.</p>
<p><em>The issue #1</em>.</p>
<p>The originality of Fossil necessarily leads to the original terms and approaches, which is reflected in the documentation. Not to mention the fact that this documentation leaves much to be desired, because of:</p>
<ul>
<li>a lot of duplicates at the cluttered (permuted) <a href="https://www.fossil-scm.org/home/doc/trunk/www/permutedindex.html">Fossil Docs Index</a> that was obviously designed to make it easy, but resulted in making it hard</li>
<li>the <a href="#repocont">terms</a> are a bit duplicated as well</li>
<li>scarce, if any, manuals about samples of workflow with Fossil</li>
<li>no comprehensive all-inclusive guide in the public domain (the <a href="http://www.fossil-scm.org/schimpf-book/home">book by Jim Schimpf</a> is outdated and incomplete, alas)</li>
</ul>
<p><em>The issue #2</em>.</p>
<p>Many Fossil fans are looking for a place to apply their fossil skills and often find it at <a href="http://chiselapp.com">chiselapp.com</a> - a hosting service that is good in almost all respects - where, however, you don’t find a word about “how to chisel at chiselapp.com”.</p>
<p>Result: at <a href="http://chiselapp.com">chiselapp.com</a> there are a lot of started and abandoned projects (named test*), as well as a bunch of quite good, but not quite presentable projects. As a rule, projects have no home nor documentation nor download page. Illustrative stuff (pictures, videos) is missing or scarce.</p>
<p>There is nothing to say about <a href="http://chiselapp.com/repositories/">Public Repositories</a>. No sectioning, no structure, no filter by author. Although there is sorting by author but the project names go first at that. You must remember an exact name of author or resort to Ctrl+F. There are other shoals at <a href="http://chiselapp.com">chiselapp.com</a> that you need at least to know about.</p>
<p>These were the reasons of this document.</p>
<p><br><br></p>
<h2 id="contents">Contents</h2>
<p>Step by step, from registration to some customization, this document will discuss the creation of a site at <a href="http://chiselapp.com">chiselapp.com</a>.</p>
<blockquote>
<p><a href="#reg">0. Registration</a></p>
</blockquote>
<blockquote>
<p><a href="#create">1. Creating a repository</a></p>
</blockquote>
<blockquote>
<p><a href="#dash">2. Dashboard</a></p>
</blockquote>
<blockquote>
<p><a href="#config1">3. Initial configuration</a></p>
</blockquote>
<blockquote>
<p><a href="#home">4. Home page</a></p>
</blockquote>
<blockquote>
<p><a href="#repocont">5. Contents of a repository</a></p>
</blockquote>
<blockquote>
<p><a href="#skin">6. New skin</a></p>
</blockquote>
<blockquote>
<p><a href="#clone">7. Cloning a repository</a></p>
</blockquote>
<blockquote>
<p><a href="#dl">8. Pushing to chiselapp.com</a></p>
</blockquote>
<blockquote>
<p><a href="#crdoc">9. Documentation page</a></p>
</blockquote>
<blockquote>
<p><a href="#media">10. Pictures and videos</a></p>
</blockquote>
<blockquote>
<p><a href="#uvpage">11. Unversioned files and Download page</a></p>
</blockquote>
<blockquote>
<p><a href="#others">12. Customization</a></p>
</blockquote>
<blockquote>
<blockquote>
<p><a href="#chperm">12.1 Changing permissions</a></p>
</blockquote>
</blockquote>
<blockquote>
<blockquote>
<p><a href="#chskin">12.2 Changing a skin</a></p>
</blockquote>
</blockquote>
<blockquote>
<p><a href="#mirror">13. Mirrors</a></p>
</blockquote>
<blockquote>
<blockquote>
<p><a href="#mirror">13.1 Mirroring GitHub</a></p>
</blockquote>
</blockquote>
<blockquote>
<blockquote>
<p><a href="#mirror2">13.2 Mirroring Fossil</a></p>
</blockquote>
</blockquote>
<blockquote>
<blockquote>
<p><a href="#mirror3">13.3 Joining muscles of both</a></p>
</blockquote>
</blockquote>
<blockquote>
<p><a href="#iqh">14. Issues, Questions, Hints</a></p>
</blockquote>
<p><br></p>
<hr />
<p><br></p>
<p id="reg">
</p>
<h2 id="registration">0. Registration</h2>
<p>You should have <a href="https://www.fossil-scm.org">Fossil SCM</a> to be installed on your machine, in order to use <a href="http://chiselapp.com">chiselapp.com</a>.</p>
<p>It makes no sense to register at <a href="http://chiselapp.com">chiselapp.com</a>, if you don’t know <a href="https://www.fossil-scm.org/home/doc/trunk/www/">what is Fossil</a>, at any rate how to <a href="https://www.fossil-scm.org/home/doc/trunk/www/quickstart.wiki">quick start with it</a>.</p>
<p>At last, you probably would not be able to use Fossil (as Git, Mercurial etc.) without CLI terminal.</p>
<p>At <a href="http://chiselapp.com">chiselapp.com</a> you register as follows:</p>
<ul>
<li><em>Create Account</em> - create your account and register.</li>
</ul>
<p>or</p>
<ul>
<li><em>Log in</em> - register under your account.</li>
</ul>
<p>I would recommend to open a separate tab of browser at registering. Or create a favorite link to Chisel home. You have no one-click way to return to <a href="http://chiselapp.com">chiselapp.com</a> from your repository.</p>
<p>Why that? Sometimes you would have to repeate <em>Log in</em>. It’s <a href="http://chiselapp.com">Chisel</a>, no toys.</p>
<p>To work with two repositories, you can try to log-in twice in two different browser windows. For example, you can run <em>chromium</em> and try “Open link in incognito window” of popup menu.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="create">
</p>
<h2 id="creating-a-repository">1. Creating a repository</h2>
<p>Let’s say we are logged in with <strong><a href="http://chiselapp.com/user/aplsimple">aplsimple</a></strong> account to create <strong><a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a></strong> repository.</p>
<p>After <em>Log in</em>, click on <em>Create Repository</em> to create a new repository.</p>
<p>You get:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/create.png /></p>
<p>Enter:</p>
<p><em>Repository name</em> - repository name, <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/index">HOWTO_chisel</a>.</p>
<p><em>Repository password</em> - password to access the repository: although optional, it is better to enter your own.</p>
<blockquote>
<p>It is important to note that the user password and the password for administrative access to the site are different ones. I always set a hard password for registering at Chisel, a hard password for accessing <em>public</em> repositories and an easy password for accessing <em>private</em> repositories.</p>
</blockquote>
<p><em>Make this repository private</em> - I highly recommend enabling this option, because <strong>the site is not yet ready for publication</strong>. A private repository can be made public at any time. After all, our blunders will be visible only to us, and the public can wait.</p>
<blockquote>
<p>Moreover, it feels like disabling this option by default has spawned all those started and abandoned <a href="http://chiselapp.com/repositories/">Public Repositories</a>.</p>
</blockquote>
<p><em>Override project code</em> - leave this field blank, everything works without it.</p>
<p><em>Use SHA3 for initial commit</em> - you can enable it if the Fossil version (by <em>fossil version</em> command) is newer or equal to 2.0; it’s for more protection against hacking.</p>
<p>Let’s click on <em>Create repository</em> and get the repository with the address:</p>
<ul>
<li>http(s)://chiselapp.com/user/aplsimple/repository/HOWTO_chisel</li>
</ul>
<p>which means that our <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> repository will be available through the addresses:</p>
<ul>
<li><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">chiselapp.com/user/aplsimple/repository/HOWTO_chisel</a></li>
<li><a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel" class="uri">http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel</a></li>
<li><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel" class="uri">https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel</a></li>
</ul>
<p>Click <em>Return to dashboard</em>. It’s your own Chisel headquarters.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="dash">
</p>
<h2 id="dashboard">2. Dashboard</h2>
<p>See the <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> line in <em>Dashboard</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/dash.png /></p>
<p>where you have the options:</p>
<ul>
<li><p><em><a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a></em> - to enter the repository</p></li>
<li><p><em>Edit</em> - to publish the site and to set a new password for administrative access; useful if you did not set a password for the repository (then Fossil will create its own) or just forgot the password to access the site.</p></li>
<li><p><em>Remove</em> - to remove the repository</p></li>
<li><p><em>How to Clone</em> - for copy-paste of the cloning command</p></li>
</ul>
<p>For now, click on <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> to enter the repository .</p>
<p><br></p>
<hr />
<p><br></p>
<p id="config1">
</p>
<h2 id="initial-configuration">3. Initial configuration</h2>
<p>Having entered our repository, we are looking for the <em>Admin</em> tab. If it is not visible, then we need to log in the repository.</p>
<p>Click <em>Login</em> and enter your username (User ID) and password <em>for the site</em>. If you can’t log in, you need to return to <a href="#dash">Dashboard</a> and change the password for accessing the repository, through <em>Edit</em>.</p>
<p>It happens that when switching from one repository to another it is not possible to log in - then you need to <em>re-login</em> at <a href="https://chiselapp.com">chiselapp.com</a>, i.e. log out and log back in. This is <strong>a glitch of chiselapp.com</strong>.</p>
<p>When we first enter the repository, Fossil offers to set the initial configuration by clicking on <em>setup/config</em> - this is what we will do:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/config.png /></p>
<p>After clicking on <em>setup/config</em>, you have the following options:</p>
<ul>
<li><p><em>Project Name</em> - the name of the project (<a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a>).</p></li>
<li><p><em>Project Description</em> - a brief description of the project.</p></li>
<li><p><em>Tarball and ZIP-archive Prefix</em> - a file name for zip/tarball files; if left blank, <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> (project name) is used.</p></li>
<li><p><em>Download Tag</em> - leave <em>trunk</em> unchanged for now (the setting will come in handy in the future when <em>stable releases</em> would be downloaded).</p></li>
<li><p><em>Enable WYSIWYG Wiki Editing</em> - you may leave this option blank to edit <em>markdown</em> without fuss with html.</p></li>
<li><p><em>Index Page</em> - it is better to leave this option unchanged as <em>home</em>; generally, you can also specify <em>/doc/tip/index.wiki</em> or <em>/doc/tip/index.md</em>, as Fossil points out; but this will mean that the home page will coincide with the documentation page, which is not good, as home is home and docs are docs.</p></li>
<li><p>The following settings are important:</p>
<ul>
<li><em>Documentation Index</em> - link to the Documentation page</li>
<li><em>Download</em> - link to the Download page</li>
<li><em>License</em> - link to the License page</li>
<li><em>Contact</em> - link to the Contact page</li>
</ul></li>
</ul>
<blockquote>
<p>To publish or not your contacts is your own decision. The contacts can be in some README as well.</p>
</blockquote>
<blockquote>
<p>But <em>Documentation Index, Download</em> and <em>License</em> must be filled. Without docs and downloads, no one needs your software. And without a license, you lose potential users - those who have heard/faced enough of the EULA stories.</p>
</blockquote>
<p>I fill in the links like this:</p>
<ul>
<li><em>Documentation Index</em> - /doc/DOC/doc/index.md</li>
<li><em>Download</em> - /download</li>
<li><em>License</em> - https://www.gnu.org/licenses/gpl-3.0.txt</li>
</ul>
<p>The <em>Documentation</em> link uses a Fossil feature called <em>embedded documentation</em>. More about this <a href="#crdoc">below</a>.</p>
<p>The <em>/download</em> link at chiselapp.com will display the standard download and cloning page. For simple projects like <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a>, it makes no sense to invent anything else. But if you want, you can specify <em>/uv/download.html</em> and get <a href="#uvpage">your own Download page</a> at chiselapp.com.</p>
<p>The <em>License</em> link may be external to the project, as in this case. Or it can be set as <em>/doc/trunk/doc/LICENSE.md</em> - i.e. as part of the same <a href="#crdoc">embedded documentation</a>.</p>
<p>At last, a <em>License</em> link may look like this:</p>
<ul>
<li>https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/artifact/b4d7662bb6b0b804</li>
</ul>
<p>or like this:</p>
<ul>
<li>/artifact/b4d7662bb6b0b804</li>
</ul>
<p>This is a link to a specific version of LICENSE.txt from your project. It’s easy to get it from the <em>Files</em> tab: right-click on <em>Files</em>/LICENSE.txt and select <em>Copy link address</em>. If LICENSE.txt is updated, you will need to update this link using <em>Admin / Configuration</em>.</p>
<p>Done with settings.</p>
<p>Ignore the <em>Use HTML as wiki markup language</em>.</p>
<p>Save the changes by clicking on <em>Apply Changes</em>.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="home">
</p>
<h2 id="home-page">4. Home page</h2>
<p>It’s time to think about the look of our site at chiselapp.com.</p>
<p>Let’s log in our <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> repository to get administrator rights.</p>
<p>Then, open the <em>Wiki</em> tab and click on <em><a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> project home page</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/home.png /></p>
<blockquote>
<p><strong>Note</strong>: It happens you don’t see <em>YOUPROJECT project home page</em> in the Wiki page. In such case, you should choose <em>List of All Wiki Pages</em> either from Wiki tab or from the ☰ (hamburger button). Your Home page (in Wiki) has the same name as your project. If it is missing, create a <em>new wiki page</em> named as your project.</p>
</blockquote>
<p>In the upper panel, select <em>Edit</em> to enter the contents of Home page.</p>
<p>Fossil will stubbornly offer its own <em>Fossil Wiki</em> markup format. It is simple and convenient, but still it’s better to choose the standard <em>Markdown</em> from the <em>Markup style</em> drop-down list.</p>
<p>Markup rules are available right on the <em>Wiki</em> tab (Formatting rules for <em>Fossil Wiki</em> and for <em>Markdown Wiki</em>).</p>
<p>Enter your page. The <em>Preview Your Changes</em> will show it above your text.</p>
<p>When the page is ready, click on <em>Apply These Changes</em>. Check how it works using the <em>Home</em> tab. Repeat all over again if there are problems.</p>
<p>There are tons of great programs that you can use to create and preview markdown documents. For example, <a href="http://github.com/wereturtle/ghostwriter">ghostwriter</a>. But the final version must still be checked at <a href="http://chiselapp.com">chiselapp.com</a>.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="repocont">
</p>
<h2 id="contents-of-a-repository">5. Contents of a repository</h2>
<p>Now let’s look inside our repository.</p>
<p>Click on the <em>Timeline</em> tab. You will see something like:</p>
<pre><code>1 check-in
2019-09-01
     09:59  [9cf295d8d7] Leaf: initial empty check-in (user: aplsimple tags: trunk)</code></pre>
<p>The <ap><code>tags: trunk</code></ap> is important - it sets the name of the main branch. This is the main content of this initial commit.</p>
<p>There may be confusion in <a href="https://www.fossil-scm.org/home/doc/trunk/www/checkin_names.wiki">terms</a>. There are synonyms for some terms and different meanings (by context) for others.</p>
<p>The <strong>tip</strong> means the last commit made, while the <strong>trunk</strong> means not a commit, but the name of the main branch starting from the first commit created by <em>fossil init</em>. As a rule (but not always), <em>tip</em> is on <em>trunk</em> and as such in commands they mean the same. Hence the confusion. If the last commit is not made on the main branch, <em>tip</em> and <em>trunk</em> refer to different commits.</p>
<p>There are terms that are not used in commands, but are often used in the documentation:</p>
<ul>
<li><strong>check-in</strong> , <strong>checkin</strong>, <strong>version</strong> - a commit</li>
<li><strong>check-out</strong>, <strong>checkout</strong> - a commit that determines the state of the working directory</li>
<li><strong>leaf</strong> - a last commit of branch; if a branch is specified in a fossil command instead of a commit, it means <em>leaf of the branch</em></li>
<li><strong>source tree</strong> - a working directory of project</li>
</ul>
<p>The <strong>checkout</strong> (or <strong>co</strong>) is one of <em>fossil</em> commands as well. It’s a verb that means “go to a commit”, i.e. have the commit to be current and a working directory to match it. Been applied to a branch, <em>checkout</em> makes its leaf to be a current commit.</p>
<p>There is no <strong>checkin</strong> command.</p>
<p>The <strong>leaf</strong> is in other words a commit without a direct child. If a leaf is merged onto other branch, it becomes a <strong>closed leaf</strong>.</p>
<p>Special commit names:</p>
<ul>
<li><strong>current</strong> - current check-out or leaf of the current branch (in <em>update, checkout</em> commands )</li>
<li><strong>next</strong> - next commit (child of the current)</li>
<li><strong>prev</strong>, <strong>previous</strong> - previous commit (parent of the current)</li>
</ul>
<p>A <strong>fork</strong> is one of unintended branches created by two commits on the same parent check-out. The intended (proper) <strong>branch</strong> is created with recommended “<code>fossil commit –branch BRANCH</code>” or with “<code>fossil branch new BRANCH</code>”. Forks have to be merged / avoided as they are branches of the same name which on the long way can lead to confusions.</p>
<p>When we left the <em>trunk</em> value unchanged in <a href="#config1">Download Tag</a> setting, we indicated to Fossil that zip/tarball will be downloaded from the top (leaf) of this main branch.</p>
<p>If the main branch is under development and you want to publish the previous stable version, you can specify the tag of this version in the <em>Download Tag</em> setting (for example, <ap>v1.0</ap>).</p>
<p id="nodl">
</p>
<p>The repository having been started, now it remains to clone it. Do not waste time looking for the cloning command in the <em>default skin</em>. Of course, you will find it - either in the <a href="#dash">Dashboard</a> or in <em>Admin / Configuration</em>, but you must be an administrator to do this. Users will not see the Download page in the default skin. Another <strong>shoals of chiselapp.com</strong>.</p>
<p>So, we should set up a site skin where the Download page (and the cloning command) is easily accessible.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="skin">
</p>
<h2 id="new-skin">6. New skin</h2>
<p>The <strong>skin</strong> determines the appearance of site.</p>
<p>To change it, we select the <em>Admin</em> tab, then find and choose <em>Skins</em>.</p>
<p>In the <em>Skins</em>, we skip all initial words and go to the end of page, where we click on <em>Skin Admin</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/skin1.png /></p>
<p>In the open list of skins, select to install the first one, i.e. Default <em>Install</em>.</p>
<p>Now the Download page is easily accessible from the ☰ (hamburger button):</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/skin2.png /></p>
<p><br></p>
<hr />
<p><br></p>
<p id="clone">
</p>
<h2 id="cloning-a-repository">7. Cloning a repository</h2>
<p>Let’s click on the ☰ hamburger button, then find and click <em>Download</em> in the <em>Home Page</em> list . The Download page will open, where we copy our cloning command:</p>
<pre><code>fossil  clone  https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel  clone.fossil</code></pre>
<p>Instead of <code>clone.fossil</code> you can set your path to a future repository file. I prefer to store local Fossil repositories in the ~/FOSSIL directory, while the repository name is the same as the project name, i.e. my cloning command looks like this:</p>
<pre><code>fossil clone https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel ~/FOSSIL/HOWTO_chisel.fossil</code></pre>
<p>But before any actions with repositories on the local machine, you should take care of the very important option of Fossil.</p>
<p>This is <strong>autosync</strong>, meaning automatic synchronization with the remote repository when committing. By default, it is turned on, which means that our commits will be automatically pushed to our chiselapp.com repository and other commits will be pulled. It only works great when we’re always online.</p>
<p>If we are only sporadically connected to the Internet, then we should switch the auto-synchronization off. Also, the auto-synchronization may not be liked by those who do not want to push every small commit to the network. What if we want to do this or that commit without pushing? Then the automatic push is definitely not for us.</p>
<p>We disable the auto-synchronization with the command:</p>
<pre><code>fossil settings --global autosync 0</code></pre>
<p>Then we execute the cloning command:</p>
<pre><code>fossil  clone  https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel ~/FOSSIL/HOWTO_chisel.fossil</code></pre>
<p>getting the response from Fossil:</p>
<pre><code>admin-user: apl (password is &quot;123456&quot;)</code></pre>
<p>where the password for administrative access to the repository is indicated. We must replace it with the command:</p>
<pre><code>fossil user password apl -R ~/FOSSIL/HOWTO_chisel.fossil</code></pre>
<p>You should enter <strong>the same repository access password</strong> that you set at chiselapp.com. If the password changes in the future, you will simply repeat this command.</p>
<p>The password policy of Fossil is rather loyal. It doesn’t ask you a password excessively, though checks it very well, don’t doubt.</p>
<p>So, the repository has been cloned. Now we go to a local directory of <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a>. Let it be <em>~/projects/HOWTO_chisel</em>. Have we already some files made in this directory or not, our actions will be as follows:</p>
<pre><code>cd ~/projects/HOWTO_chisel
fossil open ~/FOSSIL/HOWTO_chisel.fossil
fossil addremove</code></pre>
<p>Thus, we initialized the Fossil workflow with our local repository <em>~/FOSSIL/HOWTO_chisel.fossil</em> in the project directory <em>~/projects/HOWTO_chisel</em>.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="dl">
</p>
<h2 id="pushing-to-chiselapp.com">8. Pushing to chiselapp.com</h2>
<p>Having worked a bit on our project, having accumulated a bunch of small commits in it, we decide to upload our stuff to chiselapp.com.</p>
<p>If the <a href="#clone">described above</a> <code>fossil settings autosync</code> is 1 (i.e. we always synchronize with the remote repository), then we have nothing to worry about. Our commits are already at chiselapp.com, we just go to Chisel and look at results.</p>
<p>However, if <code>fossil settings autosync</code> returns 0 (auto-synchronization is disabled), then periodically after committing it is necessary to download/upload commits from/to chiselapp.com, i.e. operate in an ordinary cycle: <em>pull / update / merge / commit / push / ..local changes</em>.</p>
<p>For example, the <code>push</code> command looks like this:</p>
<pre><code>cd ~/projects/PROJECT
fossil push https://USER:[email protected]/user/USER/repository/PROJECT</code></pre>
<p>where USER and PASS should be replaced with your username and password.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="crdoc">
</p>
<h2 id="documentation-page">9. Documentation page</h2>
<p>If our documentation is a simple README.md, we can easily create <em>Documentation</em> page.</p>
<p>We enter <em>Admin / Configuration</em> and fill in <em>Documentation</em> option like this:</p>
<pre><code>/doc/trunk/README.md</code></pre>
<p>This means that README.md of the root project directory would be taken from the main branch of the repository and displayed in the Documentation page. The Fossil feature called <a href="https://www.fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki">embedded documentation</a> comes in handy here.</p>
<p>So when we click the ☰ tab and then click on <em>Documentation</em>, we get our README.md converted to html.</p>
<p>But what if the documentation should be maintained this way:</p>
<ul>
<li>the documentation sources are not in zip/tarball, though are in the repository (with all their history)</li>
<li>only the generated documentation is in zip/tarball</li>
<li>the documentation is developed on a separate branch</li>
<li>the generated documentation is viewed with ☰ / <em>Documentation</em></li>
</ul>
<p>The solution would be rather wordy:</p>
<p>The initial commit’s artifact of our repository is <a href="#repocont">[9cf295d8d7]</a>. We will branch from it to the new DOC branch and check-out it:</p>
<pre><code>fossil branch new DOC 9cf295d8d7
fossil co DOC</code></pre>
<p>Then we create a bunch of <strong>source</strong> documentation files.</p>
<p>Usually, one makes a separate <code>embedded</code> subdirectory in the project root:</p>
<pre><code>embedded/www
embedded/man
embedded/man/files
embedded/man/...</code></pre>
<p>Then one runs a kind of documentation generator that compiles <code>embedded/man</code> sources to <code>embedded/www</code> html pages .</p>
<p>We will almost do the same. Additionally, we will use two Fossil branches for <em>man</em> and <em>www</em>.</p>
<p>We will also create the sources and generate documentation, then we will commit and return to the main branch. At the same time, we will sort the source and generated documentation files into <strong>different branches</strong> - DOC and trunk.</p>
<p>One of possible implementations is following:</p>
<blockquote>
<p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/2DOC">2DOC bash file</a> - prepares generated docs for transfer from DOC to trunk (generated docs are saved in a temporary directory, then source docs are committed onto DOC branch)</p>
</blockquote>
<blockquote>
<p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/2trunk">2trunk bash file</a> - transfers generated docs to trunk (fossil checkout trunk, then generated docs are restored from a temporary directory and committed onto trunk)</p>
</blockquote>
<blockquote>
<p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/4files">4files bash file</a> - docs generator (runs ‘pandoc’ to convert markdown to html)</p>
</blockquote>
<blockquote>
<p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/4files.tcl">4files.tcl</a> - a script for docs generator (applies a command to files)</p>
</blockquote>
<p>We will continue to operate on the main branch and commit - this is necessary so that our main trunk branch comes forward in the timeline. If you want to <em>push</em> right away, make an empty commit.</p>
<p>After <em>pushing</em> the commits to chiselapp.com, we make a change to the settings of <em>Admin/Configuration</em>:</p>
<ul>
<li><em>Documentation Index</em> - /doc/trunk/embedded/www/index.html</li>
</ul>
<p>or</p>
<ul>
<li><em>Documentation Index</em> - /doc/trunk/embedded/www/toc.html</li>
</ul>
<p>The <a href="https://www.fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki">embedded documentation</a> is good primarily for compiling docs before committing the result.</p>
<p>When we run <em>fossil ui</em> on the local machine and look at our documentation at:</p>
<blockquote>
<p>http://localhost:8080/doc/trunk/embedded/www/toc.html</p>
</blockquote>
<p>we will not see any changes in it until we commit, but committing what we have not seen is ridiculous. And here Fossil comes to the rescue: it is enough to replace <strong>trunk</strong> with <strong>ckout</strong>, i.e.</p>
<blockquote>
<p>http://localhost:8080/doc/<b>ckout</b>/embedded/www/toc.html</p>
</blockquote>
<p>and we will see the current uncommitted changes immediately (or after the generation of html).</p>
<p>This is how <a href="https://www.fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki">embedded documentation</a> works.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="media">
</p>
<h2 id="pictures-and-videos">10. Pictures and videos</h2>
<p>Adding a picture to Home page or Documentation page is as easy as adding a regular html link, because markdown files allow you to use most tags on static pages, in particular, the &lt;img&gt; tag.</p>
<p>Therefore, if <em>index.md</em> refers to certain image files, it is enough to copy all the images into a subdirectory under index.md (for example, <em>files</em>) and make all image links relative, for example:</p>
<blockquote>
<p>&lt;img src=“<ap>files/</ap>colorchooser1t.png” alt=“Tcl/Tk color picker changed” /&gt;</p>
</blockquote>
<p>The <a href="http://chiselapp.com/user/aplsimple/repository/pave/doc/DOC/doc/www/details.md">example of pave</a> was made this way.</p>
<p>The <a href="#home">Home page</a> is a bit more complicated, because it is created using regular chiselapp.com tools. If you need to include a picture in Home page, then where to find its address? Since the repository does not store files, but file artifacts, Home page should also link to image artifacts. For example:</p>
<blockquote>
<p>&lt;img src=“https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/raw/bb55ed2b9ca8d40f?m=image/png” /&gt;</p>
</blockquote>
<p>where bb55ed2b9ca8d40f - is the image artifact ID seen on the <em>Files</em> tab.</p>
<p>To find out the artifact of an image, you need to go to <em>Files</em> tab, find the image you need, click on it and go to the artifact page, then copy the artifact ID (for SHA3 it will be a rather long ID).</p>
<p>The same applies to other media resources stored in the repository.</p>
<p>But there is a preferred way to do this, when all binary resources are stored as one (non-historic) version in the repository and the links to them look, for example, like this:</p>
<blockquote>
<p>&lt;img src=“http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/picture.png” /&gt;</p>
</blockquote>
<p>This method of storing data in the repository is discussed below.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="uvpage">
</p>
<h2 id="unversioned-files-and-download-page">11. Unversioned files and Download page</h2>
<p>An extremely useful feature of Fossil is ‘unversioned files’ i.e. allowing some files to have no history in the repository.</p>
<p>In general, this feature is designed for storing binary files and, in particular, for creating download pages. The previous versions of binaries are most often not necessary in the repository. Moreover, they fatten the repository.</p>
<p>Once I tried to do <a href="https://aplsimple.github.io/en/tcl/e_menu/bin4hg.html">something similar</a> in Mercurial , as far as Mercurial allowed to do this. Then bitbucket.org <a href="https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket">decided to ‘sunset’ all Mercurial repos</a>, mine incl.</p>
<p>Then Fossil came to the rescue, and the problem was solved without crutches, elegantly and beautifully. For full information, see <a href="https://www.fossil-scm.org/home/doc/trunk/www/unvers.wiki">Unversioned Files</a>.</p>
<p>Unversioned files’ best location is a directory excluded by <em>ignore-glob</em>:</p>
<pre><code>fossil settings ignore-glob .*,*~,*.swp,*.tmp,*.BIN,*.log</code></pre>
<p>Due to this, subdirectories like .BIN are excluded from the repository. They are not visible to all <em>fossil</em> commands, except for <em>fossil uv</em>.</p>
<p>Having our binaries in the .BIN subdirectory, we execute the command <em>uv add</em>:</p>
<pre><code>cd .BIN
fossil uv add *</code></pre>
<p>The trick is that <code>fossil uv add</code> will ignore the <em>ignore-glob</em> setting and mark all .BIN/* as unversioned files that will be updated at chiselapp.com with the command:</p>
<pre><code>fossil uv sync</code></pre>
<p>These files will be available on all pages of the site using the links like:</p>
<pre><code>http://chiselapp.com/user/USER/repository/PROJECT/uv/FILENAME</code></pre>
<p>For example:</p>
<pre><code>http://chiselapp.com/user/aplsimple/repository/pave/uv/pave.zip
http://chiselapp.com/user/aplsimple/repository/pave/uv/test2pave.mp4</code></pre>
<p>The similar links can be used in <a href="#crdoc">Documentation</a> page(s).</p>
<p>Also, in the .BIN directory, we can create an “unofficial” download page.</p>
<p>If our “unofficial” download page is <em>.BIN/download.html</em>, then we can set its link in <em>Admin / Configuration</em> this way:</p>
<ul>
<li><em>Download</em> - /uv/download.html</li>
</ul>
<p>This <em>download.html</em> and all binaries it refers to are all unversioned files located in .BIN directory.</p>
<p>That said, do not forget to include the <a href="#clone">clone command</a> in your download page. It’s primarily a repository.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="others">
</p>
<h2 id="customization">12. Customization</h2>
<br>
<p id="chperm">
</p>
<h3 id="changing-permissions">12.1 Changing permissions</h3>
<p>User <em>anonymous</em> has the right to modify the <em>Wiki</em>. It seems to be a good feature, but the problem is that <em>anonymous</em> can go this way:</p>
<ul>
<li>Home / List / <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> / Append</li>
</ul>
<p>… to calmly write at the end of the <a href="#home">Home page</a> what he/she can only contrive. <strong>Another shouls of chiselapp.com</strong>.</p>
<p>In no way this should be allowed. Therefore, you must change the rights of <em>anonymous</em>.</p>
<p>We go to <em>Admin / Users</em>, select <em>anonymous</em> and cancel the <em>Append Wiki</em> right. After that, click on <em>Apply changes</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/user.png /></p>
<br>
<p id="chskin">
</p>
<h3 id="changing-a-skin">12.2 Changing a skin</h3>
<p>We can slightly change the <a href="#skin">standard skin</a>.</p>
<p>Our task:</p>
<ul>
<li><p>Remove <em>Timeline</em> and <em>Branches</em> from the tab list.</p></li>
<li><p>Add <em>Docs</em> and <em>Download</em>.</p></li>
</ul>
<p>To do this, enter <em>Admin / Skins</em>.</p>
<p>It’s necessary to change the settings:</p>
<ul>
<li>CSS</li>
<li>Header</li>
<li>Footer</li>
<li>Details</li>
<li>Javascript</li>
</ul>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/chskin1.png /></p>
<p>It is important to remember that these settings <strong>may not match</strong> the <em>Default</em> skin, even if you choose <em>Default (built-in)</em> in the <em>Initialize skin draft1 using</em>. There is <strong>some kind of glitch</strong> with this.</p>
<p>The proper settings can be taken from the Fossil website:</p>
<p><a href="https://fossil-scm.org/home/dir?ci=tip" class="uri">https://fossil-scm.org/home/dir?ci=tip</a></p>
<p>There you need to enter <em>skins/default</em> subdirectory, from where the contents of the files:</p>
<ul>
<li>css.txt</li>
<li>header.txt</li>
<li>footer.txt</li>
<li>details.txt</li>
<li>js.txt</li>
</ul>
<p>should be transferred to the mentioned settings, according to the names.</p>
<p>While making changes to these settings, you should pay attention that the <em>Edit SETTING for Draft1</em> form will open in a separate browser tab. After confirming the changes with the <em>Apply</em> button, you should close the tab to return to the <em>Skins</em> window.</p>
<p>In <em>Header</em>, changes should be made in two places:</p>
<p><ap> <strong>1)</strong> </ap></p>
<pre><code>menulink $index_page Home {}
if {[anycap jor]} {
    menulink /timeline Timeline {}
}</code></pre>
<p><ap>should be changed so:</ap></p>
<pre><code># (put your own Docs and Download links)

menulink $index_page Home {}
menulink /doc/trunk/doc/index.md Docs {}
menulink /download Download {}
if {[anycap s]} {
    # jor
    menulink /timeline Timeline {}
}</code></pre>
<p><ap> <strong>2)</strong> </ap></p>
<pre><code>if {[hascap o]} {
    menulink  /brlist Branches desktoponly</code></pre>
<p><ap>should be changed so:</ap></p>
<pre><code>if {[hascap s]} {
    # o
    menulink  /brlist Branches desktoponly</code></pre>
<p>Shortly, the <em>Docs</em> and <em>Download</em> items have been added, the access to <em>Timeline</em> and <em>Branches</em> has been changed so that these tabs are visible only to the administrator (they can still be accessed through the hamburger button ☰, but not through the tab bar).</p>
<p>After these changes made, turn on the options:</p>
<ul>
<li><em>Skin draft1 has been tested and found ready for production.</em></li>
<li><em>The current skin should be overwritten with draft1.</em></li>
</ul>
<p>and click on <em>Publish Draft1</em>.</p>
<p>Now, users (and you when not logged in) will see only the necessary:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/chskin2.png /></p>
<p>or:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/chskin3.png /></p>
<p>For more on skins, see <a href="https://www.fossil-scm.org/home/doc/trunk/www/customskin.md">Skinning the Fossil Web Interface</a>.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="mirror">
</p>
<h2 id="mirrors">13. Mirrors</h2>
<p><a href="https://www.fossil-scm.org">Fossil SCM</a> allows easily to mirror a repository.</p>
<p><br></p>
<h3 id="mirroring-github">13.1 Mirroring GitHub</h3>
<p>Suppose, we have a repository at <a href="https://github.com/">GitHub</a>. To make the task harder, let it be a static site named <a href="https://aplsimple.github.io">aplsimple.github.io</a>. We want to have it mirrored at <a href="http://chiselapp.com">chiselapp.com</a>.</p>
<p>Our actions would be as follows.</p>
<p><strong>1.</strong> We <a href="#create">create a repository</a> named <code>aplsimple_github_io</code> at <a href="http://chiselapp.com">chiselapp.com</a>.</p>
<p><strong>2.</strong> We <a href="#clone">clone</a> this repository, say, to <code>~/FOSSIL/aplsimple_github_io.fossil</code>.</p>
<p><strong>3.</strong> Then we go to a local directory with <strong>a clone of GitHub repository</strong> and open <code>~/FOSSIL/aplsimple_github_io.fossil</code> in it. Of course, <em>.gitignore</em> should ensure the newly created <em>.fslckout</em> file to be ignored by Git.</p>
<p><strong>4.</strong> To take into account the binary files, we</p>
<ul>
<li>include them to <em>ignore-glob</em> fossil setting</li>
<li>mark them as <a href="#uvpage">unversioned</a>.</li>
</ul>
<p><strong>5.</strong> Then we</p>
<ul>
<li>execute <em>fossil addremove</em></li>
<li>make a “populating” commit</li>
<li>push it to <a href="http://chiselapp.com">chiselapp.com</a></li>
<li>if necessary, sync <a href="#uvpage">unversioned files</a></li>
</ul>
<p id="noheadfoot">
</p>
<p><strong>6.</strong> At <a href="http://chiselapp.com">chiselapp.com</a> we go to <em>Admin / Configuration</em> and set <em>Index Page</em> (Home of repository) this way:</p>
<ul>
<li><em>Index Page</em> - /doc/trunk/index.html</li>
</ul>
<p><strong>7.</strong> Thus, the new mirror has been created and available through the link:</p>
<ul>
<li><a href="https://chiselapp.com/user/aplsimple/repository/aplsimple_github_io/doc/trunk/index.html" class="uri">https://chiselapp.com/user/aplsimple/repository/aplsimple_github_io/doc/trunk/index.html</a></li>
</ul>
<p><strong>8.</strong> If we need to access the <em>Admin</em> tab, we add <em>/setup_config</em> to the root of the above link, i.e.</p>
<ul>
<li>https://chiselapp.com/user/USER/repository/PROJECT/setup_config</li>
</ul>
<p><strong>9</strong>. A last stroke. We change all links to unversioned binaries to <em>chiselapp.com/../uv/…</em> which will work at both Chisel and GitHub after next push to them. Then we remove the binaries from GitHub to lighten Microsoft.</p>
<p>Here we leveraged a feature of Fossil allowing to display any static pages ‘as is’, without Fossil’s header and footer. To restore the Fossil skin, you should include the following lines to the top of your html pages:</p><pre><code>&lt;div class=&#39;'fossil-doc&#39;' data-title=&#39;'Title Text'&#39;&gt;
&lt;/div&gt;</code></pre>
<p>You can come across one trouble at that. The site links should be (and are) relative to a site root. However, the “Home” button cannot be relative, as it is the root by itself.</p>
<p>A bit of JavaScript can help here:</p>
<pre><code>function writeHome() {
  homeLINK = document.baseURI;
  ilen = 19; // ilen depends on the length of site name  ibase = homeLINK.indexOf(&#39;'aplsimple.github.io&#39;');
  if (ibase&lt;0) {    ibase = homeLINK.indexOf(&#39;'aplsimple_github&#39;');
    ilen += 10;  // Chisel adds /doc/trunk
  };
  homeLINK = homeLINK.substring(0,ibase+ilen);  document.write('&#39;&lt;a href=&#39;'+homeLINK+&#39;'/index.html&gt;Home&lt;/a&gt;&#39;');
}</code></pre>
<p><br></p>
<p id="mirror2">
</p>
<h3 id="mirroring-fossil">13.2 Mirroring Fossil</h3>
<p><a href="https://www.fossil-scm.org">Fossil SCM</a> decouples a working directory and a repository which is one of its coolest features.</p>
<p>This feature makes the mirroring Fossil repos to be a trivial task.</p>
<p>Suppose we have <em>tmp</em> repository at Chisel.</p>
<p>We clone it as <em>~/FOSSIL/tmp.fossil</em> and open this local repo in <em>~/projects/tmp</em> directory. Then we populate the directory, commit and push. We add unversioned files with “fossil uv add” and push them with “fossil uv sync”.</p>
<p>Now we want to make a mirror of this repository, e.g. <em>tmp2</em>.</p>
<p>What should be done is the following:</p>
<ul>
<li><p>create <em>tmp2</em> repository at Chisel, then clone it as <em>~/FOSSIL/tmp2.fossil</em></p></li>
<li><p>close the <em>~/FOSSIL/tmp.fossil</em> repo in <em>~/projects/tmp</em> directory</p></li>
<li><p>open <em>~/FOSSIL/tmp2.fossil</em> in the same <em>~/projects/tmp</em> directory</p></li>
<li><p>execute:</p>
<ul>
<li><em>fossil addremove</em></li>
<li><em>fossil commit</em></li>
<li><em>fossil push</em></li>
<li>for uv binaries, also <em>fossil uv add</em> and <em>fossil uv sync</em></li>
<li><em>fossil close</em></li>
</ul></li>
</ul>
<p>Voila! <a href="https://chiselapp.com/user/aplsimple/repository/tmp2/dir?ci=tip">tmp2</a> is a mirror of <a href="https://chiselapp.com/user/aplsimple/repository/tmp/dir?ci=tip">tmp</a>.</p>
<p>Of course, you should take care of Home pages of mirrors, not a great deal of care.</p>
<p><strong>Note</strong>: <a href="https://chiselapp.com/user/aplsimple/repository/tmp/dir?ci=tip">tmp</a> and <a href="https://chiselapp.com/user/aplsimple/repository/tmp2/dir?ci=tip">tmp2</a> are both <strong>private</strong> repositories of <a href="http://chiselapp.com/user/aplsimple">aplsimple</a> which doesn’t prevent them to be accessable from the outside.</p>
<p>The hardest problem still remains unsolved:</p>
<blockquote>
<p>To try and find this facility in Git or Mercurial.</p>
</blockquote>
<p><br></p>
<p id="mirror3">
</p>
<h3 id="joining-muscles-of-both">13.3 Joining muscles of both</h3>
<p>A slightly altered cliche sounds: <em>Don’t keep all bits in one bucket as your bucket of bits can <a href="https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket">go down</a></em>.</p>
<p>Git likes a linear history of changes. Fossil manages branches as well as you can only imagine. Though, Git is for public usage, Fossil mostly for private.</p>
<p>Can we have these horses going under one harness? Let’s try.</p>
<p>The main idea is to manage a project with Git and Fossil at once. In our project directory we should:</p>
<ul>
<li>create a Git repo (.git)</li>
<li>create <em>.gitignore</em> file containing as minimum a .* glob pattern</li>
<li>open a Fossil repo</li>
<li>set <em>ignore-glob</em> Fossil setting to contain as minimum a .* glob pattern</li>
<li>create .BIN subdirectory for unversioned files of Fossil</li>
</ul>
<p>We operate as follows:</p>
<ul>
<li><p>All commits are put in the Fossil repo.</p></li>
<li><p>All branches are managed in the Fossil repo.</p></li>
<li><p>Before Git committing, we run <em>fossil checkout</em> for an appropriate branch</p></li>
<li><p>Only <em>big</em> commits are put in the Git repo.</p></li>
<li><p><em>Small / intermediate</em> commits are not put in the Git repo.</p></li>
<li><p><em>Big</em> branches only are managed in the Git repo, e.g. <em>Main, Releases, Docs</em>.</p></li>
<li><p><em>Testing / probing / temporary</em> branches are not managed in the Git repo.</p></li>
<li><p>No <em>rebase</em>s are allowed in the Git repo.</p></li>
<li><p>Git <em>push</em> is performed after each Git commit.</p></li>
<li><p>Fossil <em>push</em> is performed immediately after the Git <em>push</em>.</p></li>
</ul>
<p>Thus, in the Fossil repo, we have a full history of all changes. In the Git repo, we have a linear (per branch) history of essential changes, which means <strong>an ideal of Git repository</strong>.</p>
<p>One of nice effects:</p>
<blockquote>
<p>If you use an editor / IDE with a Git monitoring, you can see the changes based on the last <em>big</em> Git commit. In other words, changes after last <em>push</em>.</p>
</blockquote>
<p>For example, using Geany IDE, you can view a previous version in a yellow box:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/gitgeany.png /></p>
<p>The described operations on repos can be easily automated, e.g. with <a href="https://aplsimple.github.io/en/tcl/e_menu/">e_menu</a>, as seen below:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/gitemenu.png /></p>
<hr />
<p><br></p>
<p id="iqh">
</p>
<h2 id="issues-questions-hints">14. Issues, Questions, Hints</h2>
<p><br></p>
<h3 id="list-of-issues-pointed-out-above">List of issues pointed out above</h3>
<ul>
<li><p>Sometimes at Chisel you would have to <a href="#reg">repeate Log in</a>.</p></li>
<li><p>When you create a repo at Chisel, <a href="#create">switch</a> <em>Make this repository private</em> <a href="#create">on</a>.</p></li>
<li><p>It happens you don’t see YOUPROJECT project <a href="#home">home page</a> in the Wiki page.</p></li>
<li><p>You don’t see the <a href="#nodl">Download page</a> in the default skin.</p></li>
<li><p>An <em>anonymous</em> can change <a href="#chperm">your home page</a>.</p></li>
<li><p><a href="#chskin">Skin settings</a> should be taken from the Fossil website.</p></li>
</ul>
<p><br></p>
<h3 id="why-so-much-of-git-in-fossil-docs">Why <a href="https://www.fossil-scm.org/home/doc/trunk/www/permutedindex.html">so much</a> of Git in Fossil docs?</h3>
<p>Indeed, what’s that? Jealousy? Envy? Boldness? Hopefully, none of these but a desire to compete.</p>
<p>Git is designed to be used by big teams. I.e. Git is for public usage mostly. It would be an overkill to use it privately. Being just opposite, Fossil is designed to be used by small teams and for private projects mostly.</p>
<p>The natural publicity of Git and the natural privateness of Fossil give rise to a false opinion that the former is better than the latter.</p>
<p>It is like comparing bread and gooseberries. Can one do without bread? Most probably, <a href="https://en.wikipedia.org/wiki/Bread">not</a>. Can one do without gooseberries? It happens, <a href="https://en.wikipedia.org/wiki/Gooseberries_(short_story)">not</a>.</p>
<p>Both are great tools. After all, one man likes and needs orchestras, other can’t live without quartets.</p>
<p>Still being such non-public, Fossil remains an unsung hero appreciated by those only who know.</p>
<p><br></p>
<h3 id="why-nothing-of-mercurial-in-fossil-docs">Why <a href="https://www.fossil-scm.org/home/doc/trunk/www/permutedindex.html">nothing</a> of Mercurial in Fossil docs?</h3>
<p>It’s puzzling too. A guess is that the design of Mercurial SCM is much inferior to Fossil’s.</p>
<p>And it feels like Mercurial’s main trouble is its tangled mechanics of branching.</p>
<p>Mercurial doesn’t distinguish <strong>fork</strong> and <strong>branch</strong> at creating them. The Mercurial branches of <em>multiple heads</em> are the same as Fossil’s forks - the only difference is that Mercurial heads are easy to make and hard to push, while Fossil forks just opposite.</p>
<p>You have <em>three</em> types of branches in Mercurial: bookmarked, named, anonymous. Don’t even hope for a repo to be orderly when you have all of them at once and in plenty.</p>
<p>You need to close Mercurial branches to avoid “branch cluttering”, while a simple <em>merge</em> suffices to end with a Fossil branch.</p>
<p>In Mercurial, you can clone a part of repo (up to a specified revision). You can push/pull a single branch. You can rebase a branch and push the result. At that you cannot have private branches in Mercurial, though local tags are available along with the notorious .hgtags file.</p>
<p>As a result, you can have “clones” of so varied contents as you can imagine. And at that, one of Mercurial practices is to clone a clone.</p>
<p>Add the incoming Python 2-3 conversion to the poor design and you would end up by <a href="https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket">“sunsetting” your Mercurial repo</a>.</p>
<p>These troubles are impossible or avoided in Fossil.</p>
<p><br></p>
<h3 id="is-there-a-limit-to-unversioned-files-size">Is there a limit to unversioned files’ size?</h3>
<p>There is. At any rate, I could not upload a 70 Mb uv file to Chisel.</p>
<p>Though, a <a href="https://chiselapp.com/user/aplsimple/repository/aplsimple_github_io/uv/e_menu.mp4">11 Mb file</a> was uploaded OK.</p>
<p>With bisecting the file sizes, you can find the limit. I suppose it’s about 50 Mb.</p>
<p><br></p>
<h3 id="when-would-the-md-to-html-conversion-come-in-handy">When would the md to html conversion come in handy?</h3>
<p>Indeed, any site powered by Fossil can have a markdown page to be displayed naturally as a static html. So, basically there is no need to convert markdown pages at Fossil repository.</p>
<p>However, in specific cases the conversion is necessary. For example this <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> repository uses the <em>md to html</em> conversion in order:</p>
<ul>
<li><p>to set an example of <a href="#crdoc">DOC branch</a></p></li>
<li><p>to update the <a href="https://wiki.tcl-lang.org/page/How+to+chisel+at+chiselapp.com">wiki page</a> using &lt;&lt;inlinehtml&gt;&gt; to insert a html (<a href="https://wiki.tcl-lang.org">wiki.tcl-lang.org</a>’s markdown isn’t compatible with Fossil’s)</p></li>
</ul>
<p><br></p>
<h3 id="why-my-unversioned-files-not-updated-remotely">Why my unversioned files not updated remotely?</h3>
<p>Fossil provides three basic commands to upload uv files:</p>
<ul>
<li><p><em>fossil uv add</em> - this one adds new or changed file(s) to a local repository</p></li>
<li><p><em>fossil uv rm</em> - this one removes file(s) from a local repository</p></li>
<li><p><em>fossil uv sync</em> - this one synchronizes a local repo with a remote repo as for uv file(s)</p></li>
</ul>
<p>The <em>fossil uv sync</em> command takes uv files from a local repo, not from a working directory.</p>
<p>So, if an unversioned file changes, repeat <em>fossil uv add</em> for it and upload it with <em>fossil uv sync</em>.</p>
<p><br></p>
<h3 id="how-to-get-rid-of-fossils-header-and-footer">How to get rid of Fossil’s header and footer?</h3>
<p>One of solutions was considered <a href="#noheadfoot">here</a>, at mirroring <a href="#mirror">GitHub site</a>.</p>
<p><br></p>
<h3 id="how-to-refer-to-an-external-link-in-documentation-page">How to refer to an external link in Documentation page?</h3>
<p>Suppose instead of <a href="#crdoc">embedded documentation</a>, you should refer to an external link of docs.</p>
<p>Then your actions might be as follows:</p>
<ul>
<li><p>in <a href="#config1">Admin / Configuration</a>, set <em>Documentation Index = /doc/trunk/docs.html</em></p></li>
<li><p>in <a href="#chskin">Admin / Skins</a>, write in <em>Header</em> the following line:</p>
<p>menulink /doc/trunk/docs.html Docs {}</p></li>
<li><p>on <em>trunk</em> branch, in the working directory, create <em>docs.html</em> of the following contents:</p>
<p>&lt;!DOCTYPE html&gt; &lt;html&gt; &lt;head&gt; &lt;meta charset=“UTF-8”&gt; &lt;meta http-equiv=“refresh” content=“0; URL=‘<b>https://EXTERNALSITE/index.html</b>’” /&gt; &lt;/head&gt; &lt;body&gt; &lt;/body&gt; &lt;/html&gt;</p></li>
<li><p>commit and push your changes</p></li>
</ul>
<p>This <em>docs.html</em> would redirect the Docs to your site. An example is <a href="http://chiselapp.com/user/aplsimple/repository/e_menu">e_menu</a>’s Docs.</p>
<hr />
<h3 id="to-be-continued">to be continued</h3>

<<inlinehtml>>

<<categories>> Application | Dev. Tools