Documentation Source Text

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Added pages/whynotgit.in.

            1  +<title>Why SQLite Does Not Use Git?</title>
            2  +
            3  +<table_of_contents>
            4  +
            5  +<h1>Introduction</h1>
            6  +
            7  +<p>
            8  +SQLite does not use the
            9  +[https://git-scm.org|Git] version control system.
           10  +SQLite uses
           11  +[https://fossil-scm.org/|Fossil] instead.
           12  +Fossil and Git are both block-chain version-control systems.
           13  +They are both "distributed".  They both store content has a 
           14  +sequence of immutable check-ins identified by a cryptographic
           15  +hash.  Git is wildly popular, to the point that many younger
           16  +developers are familiar with nothing else.  And yet, the developers
           17  +of SQLite prefer Fossil.  This article tries to explain why.
           18  +
           19  +<h1>A Few Reasons Why SQLite Does Not Use Git</h1>
           20  +
           21  +<ol>
           22  +<li><p>
           23  +With Git, it is very difficult to find the successors (decendents) of
           24  +a check-in.
           25  +
           26  +<p>
           27  +Git allows you to go backwards in time.  Given the latest
           28  +check-in on a branch, Git lets you see all the ancestors of that
           29  +check-in.  But Git makes it very difficult to move in the other
           30  +direction.  Given some historical check-in, it is quite challenging
           31  +in Git to find out what came next.  It can be done, but it is sufficiently
           32  +difficult and slow that nobody ever does it.  There is no button in
           33  +GitHub that shows the descendents of a check-in.
           34  +
           35  +<p>
           36  +This is a deal-breaker, a show-stopper.  The principle maintainer
           37  +of SQLite cannot function effectively without being able to view
           38  +the successors of a check-in.  This one issue is sufficient reason
           39  +to not use Git, in the view of the designer of SQLite.
           40  +
           41  +<li><p>
           42  +The mental model for Git is needlessly complex and consequently
           43  +distracts attention from software under development.  A user of Git
           44  +needs to keep all of the following in mind:
           45  +<ol type='a'>
           46  +<li> The working directory
           47  +<li> The "index" or staging area
           48  +<li> The local head
           49  +<li> The local copy of the remote head
           50  +<li> The actual remote head
           51  +</ol>
           52  +<p>
           53  +Git contains commands (or options on commands) for moving and
           54  +comparing content between all of these locations. 
           55  +
           56  +<p>In contrast,
           57  +Fossil users only need to think about their working directory and
           58  +the check-in they are working on.  That is 60% less distraction.
           59  +Every developer has a finite number of brain-cycles.  Fossil
           60  +requires fewer brain-cycles to operate, thus freeing up 
           61  +intellectual resources to focus on the software under development.
           62  +
           63  +<li><p>
           64  +Git does not track branch history.  This makes review of historical
           65  +branches tedious.
           66  +
           67  +<p>
           68  +As an example, consider display of a single historical
           69  +branch of SQLite as rendered by GitHub and by Fossil:
           70  +
           71  +<ul>
           72  +<li><b>GitHub:</b> [https://github.com/mackyle/sqlite/commits/prefer-coroutine-sort-subquery]
           73  +<li><b>Fossil:</b> [https://sqlite.org/src/timeline?r=prefer-coroutine-sort-subquery]
           74  +</ul>
           75  +
           76  +<p>
           77  +The Fossil view clearly shows that the branch was eventually merged back into
           78  +trunk.  It shows where the branch started, and it shows two occasions where changes
           79  +on trunk were merged into the branch.  GitHub shows none of this.  In fact, the
           80  +GitHub display is mostly useless in trying to figure out what happened.
           81  +
           82  +<li><p>
           83  +Git lacks native wiki and bug tracking.
           84  +If you want these essential features, you have to install additional software
           85  +such as GitLab, or else use a third-party service such as GitHub.  And even
           86  +then, the wiki and bug reports are centralized, not distributed.
           87  +
           88  +<li><p>
           89  +Git requires more administrative support.
           90  +Setting up a website for a project to use Git requires a lot more software,
           91  +and a lot more work, than setting up a similar site with an integrated package
           92  +like Fossil.
           93  +
           94  +<li><p>Nobody really understands Git.
           95  +<img src="https://www.fossil-scm.org/fossil/doc/trunk/www/xkcd-git.gif"><br>
           96  +(credit: [https://xkcd.com/1597/])
           97  +</ol>
           98  +
           99  +<h2>See Also</h2>
          100  +
          101  +<p>Other pages that talk about Fossil and Git include:
          102  +<ul>
          103  +<li><p>[https://fossil-scm.org/fossil/doc/trunk/www/fossil-v-git.wiki|Fossil vs. Git]
          104  +<li><p>[https://www.fossil-scm.org/fossil/doc/trunk/www/quotes.wiki|What others say about Fossil and Git]
          105  +</ul>
          106  +
          107  +<h1>A Git-User's Guide To Accessing SQLite Source Code</h1>
          108  +
          109  +<p>
          110  +If you are a devoted Git user and have no intention of changing,
          111  +you can still easily access SQLite.  This section gives some hints
          112  +on how to do so.
          113  +
          114  +<h2>GitHub Mirrors</h2>
          115  +
          116  +<p>
          117  +There is a mirror of the SQLite source tree on GitHub at
          118  +[https://github.com/mackyle/sqlite].  This mirror is maintained
          119  +by user "mackyle" who is unaffiliated with, and unknown to,
          120  +the official SQLite development team.  We do not know mackyle,
          121  +but we observe that he does a terrific job of keeping his mirror
          122  +current, and so if you want to access the SQLite source code on
          123  +GitHub, his mirror is the recommended source.
          124  +
          125  +<h2>Web Access</h2>
          126  +
          127  +<p>
          128  +The [https://sqlite.org/src/timeline|SQLite Fossil Repository] contains links
          129  +for downloading  a Tarball, ZIP Archive, or [SQLite Archive] for any
          130  +historical version of SQLite.  The URLs for these downloads are
          131  +simple and can be incorporated easily into automated tools.  The format is:
          132  +
          133  +<center>
          134  +<tt>https://sqlite.org/src/tarball/</tt><i>VERSION</i><tt>/sqlite.tar.gz</tt>
          135  +</center>
          136  +
          137  +<p>
          138  +Simply replace <i>VERSION</i> with some description of the version to be
          139  +downloaded.  The <i>VERSION</i> can be a prefix of the cryptographic hash
          140  +name of a specific check-in, or the name of a branch (in which case the
          141  +most recent version of the branch is fetched) or a tag for a specific
          142  +check-in like "version-3.23.0".
          143  +
          144  +<h2>Fossil Access</h2>
          145  +
          146  +<p>
          147  +Fossil is really easy to install and use.  Here are the steps for unix.
          148  +(Windows is similar.)
          149  +
          150  +<ol>
          151  +<li>
          152  +Download the self-contained Fossil executable from
          153  +[https://fossil-scm.org/fossil/uv/download.html] and put the executable
          154  +somewhere on your $PATH.
          155  +<li><tt>mkdir ~/fossils</tt>
          156  +<li><tt>fossil clone https://fossil-scm.org/fossil ~/fossils/sqlite.fossil</tt>
          157  +<li><tt>mkdir ~/sqlite; cd ~/sqlite</tt>
          158  +<li><tt>fossil open ~/sqlite.fossil .</tt>
          159  +</ol>
          160  +
          161  +<p>
          162  +Subsequently, to update your check-out, simply type:
          163  +
          164  +<blockquote>
          165  +<tt>fossil up </tt><i>VERSION</i>
          166  +</blockquote>
          167  +
          168  +<p>
          169  +Use "trunk" for version to get the latest trunk version of SQLite.
          170  +Or use a prefix of a cryptographic hash name, or the name of some branch
          171  +or tag.
          172  +
          173  +<p>
          174  +Use the "<tt>fossil ui</tt>" command from within the ~/sqlite checkout to
          175  +bring up a local copy of the website.