Documentation Source Text

does not already exists, then appends entries that check the SHA3
hash of the content of all tables.  Subsequent runs of ".selftest"
will verify that the database has not been changed in any way.  To
generates tests to verify that a subset of the tables are unchanged,
simply run ".selftest --init" then [DELETE] the selftest rows that
refer to tables that are not constant.  

<tcl>hd_fragment sqlar</tcl>
<h1>SQLAR Archive Support</h1>

<p>The shell tool ".ar" dot-command provides built-in support for the 
[https://sqlite.org/sqlar|SQLite ARchive format]. The interface is similar to
that of the "tar" command on unix systems. Each invocation of the ".ar"
command must specify a single command option. The following commands
are available:

<table striped=1>
  <tr><th style="width:15ex">Option<th style="width:17ex">Long&nbsp;Option<th>Purpose
  <tr><td>-c<td>--create<td>Create a new archive containing specified files.
  <tr><td>-x<td>--extract<td>Extract specified files from archive.
  <tr><td>-t<td>--list<td>List the files in the archive.
  <tr><td>-u<td>--update<td>Add files to existing archive.
</table>

<p>As well as the command option, each invocation of ".ar" may specify
one or more modifier options. Some modifier options require an argument,
some do not. The following modifier options are available:

<table striped=1>
  <tr><th style="width:15ex">Option<th style="width:17ex">Long&nbsp;Option<th>Purpose
  <tr><td>-v<td>--verbose<td>List each file as it is processed.
  <tr><td>-f FILE<td>--file FILE<td>If specified, use file FILE as the
  archive. Otherwise, assume that the current "main" database is the 
  archive to be operated on.
  <tr><td>-C DIR<td>--directory DIR<td>If specified, interpret all relative
  paths as relative to DIR, instead of the current working directory.
  <tr><td>--<td>--<td>All subsequent command line words are command arguments,
  not options.
</table>

<p>
Long and short style options may be mixed. For example, the following are
equivalent:

<codeblock>
  <i>-- Two ways to create a new archive named "new_archive.db" containing</i>
  <i>-- files "file1", "file2" and "file3".</i>
  .ar -c --file new_archive.db file1 file2 file3
  .ar -f new_archive.db --create file1 file2 file3
</codeblock>

<p>Alternatively, the first argument following to ".ar" may be the concatenation
of the short form of all required options (without the "-" characters). In 
this case arguments for options requiring them are read from the command line
next, and any remaining words are considered command arguments. For example:

<codeblock>
  <i>-- Create a new archive "new_archive.db" containing files "file1" and</i>
  <i>-- "file2" from directory "dir1".</i>
  .ar cCf dir1 new_archive.db file1 file2 file3
</codeblock>

<h2> SQLAR Create Command </h2>

<p>Create a new archive, clobbering any existing archive (either in the current
"main" db or in the file specified by a --file option). Each argument following
the options is a file to add to the archive. Directories are imported
recursively. See above for examples.

<h2> SQLAR Extract Command </h2>

<p>Extract files from the archive (either to the current working directory or
to the directory specified by a --directory option). If there are no arguments
following the options all files are extracted from the archive. Or, if there
are arguments, they are the names of files to extract from the archive. Any
specified directories are extracted recursively. It is an error if any
specified files are not part of the archive.

<codeblock>
  <i>-- Extract all files from the archive in the current "main" db to the</i>
  <i>-- current working directory. List files as they are extracted. </i>
  .ar --extract --verbose

  <i>-- Extract file "file1" from archive "ar.db" to directory "dir1".</i>
  .ar fCx ar.db dir1 file1
</codeblock>

<h2> SQLAR List Command </h2>

<p>List the contents of the archive. If no arguments are specified, then all
files are listed. Otherwise, only those specified as arguments are. Currently,
the --verbose option does not change the behaviour of this command. That may
change in the future.

<codeblock>
  <i>-- List contents of archive in current "main" db.</i>.
  .ar --list
</codeblock>

<h2> SQLAR Update Command </h2>

<p> This command works the same way as the --create command, except that 
it does not delete the current archive before commencing. New versions of
files silently replace existing files with the same names, but otherwise
the initial contents of the archive (if any) remain intact.

<tcl>hd_fragment dotother</tcl>
<h1>Other Dot Commands</h1>

<p>There are many other dot-commands available in the command-line
shell.  See the ".help" command for a complete list for any particular
version and build of SQLite.