path: root/www/caps/ref.html

<div class='fossil-doc' data-title="User Capability Reference">

<style type="text/css">
  p#backlink {
    /* Make empty space below the table so hyperlinks to named anchors
       near the bottom of the table still scroll that row to the top of
       the user's browser, even on tall screens. */
    margin-bottom: 75em;
  }

  tr > th {
    background-color: #e8e8e8;
    vertical-align: top;
  }
  body.fossil-dark-style tr > th {
    color: #000;
    opacity: 0.85;
  }

  tr.cols th {
    white-space: nowrap;
  }

  td, th {
    padding: 0.4em;
  }
</style>

<p>Here we document each currently-defined user capability character in
more detail than the brief summary on the <a
href="/setup_ucap_list">“key” page</a> in the Fossil user editor. Each
row gives the capability letter used in the Fossil user editor followed
by the C code’s name for that cap within the <tt>FossilUserPerms</tt>
object, so you can use this reference both from the UI down and from the
C code up.</p>

<p>The <a href="https://en.wikipedia.org/wiki/Mnemonic">mnemonics</a>
given here vary from obviously-correct to <i>post facto</i>
rationalizations to the outright fanciful. To <a
href="./impl.md#choices">some extent</a>, this is unavoidable.</p>


<h2>Reference</h2>

<table>
  <tr class="cols">
    <th>?</th>
    <th>Name</th>
    <th style="text-align: left">Description</th>
  </tr>

  <tr id="a">
    <th>a</th>
    <th>Admin</th>
    <td>
      Admin users have <em>all</em> of the capabilities below except for
      <a href="#s">setup</a>, <a herf="#x">Private</a>, and <a href="#y">WrUnver</a>.
      See <a href="admin-v-setup.md">Admin vs.  Setup</a> for a more
      nuanced discussion.  Mnemonic: <b>a</b>dministrate.
    </td>
  </tr>

  <tr id="b">
    <th>b</th>
    <th>Attach</th>
    <td>
      Add attachments to wiki articles, technotes, or tickets.
      Mnemonics: <b>b</b>ind, <b>b</b>utton, <b>b</b>ond, or <b>b</b>olt.
      See also: <a href='#B'>B</a>.
    </td>
  </tr>

  <tr id="c">
    <th>c</th>
    <th>ApndTkt</th>
    <td>
      Append comments to existing tickets. Mnemonic: <b>c</b>omment.
    </td>
  </tr>

  <tr id="d">
    <th>d</th>
    <th>n/a</th>
    <td>
      Legacy capability letter from Fossil's forebear <a
      href="http://cvstrac.org/">CVSTrac</a>, which has no useful
      meaning in Fossil due to the nature of its durable Merkle tree design.
      We recommend that you remove it in case we
      ever reuse this letter for another purpose. See <a
      href="https://fossil-scm.org/forum/forumpost/43c78f4bef">this
      post</a> for details.
    </td>
  </tr>

  <tr id="e">
    <th>e</th>
    <th>RdAddr</th>
    <td>
      View <a
      href="https://en.wikipedia.org/wiki/Personal_data">personal
      identifying information</a> (PII) about other users such as email
      addresses. Mnemonics: show <b>e</b>mail addresses; or
      <b>E</b>urope, home of <a
      href="https://en.wikipedia.org/wiki/General_Data_Protection_Regulation">GDPR</a>.
    </td>
  </tr>

  <tr id="f">
    <th>f</th>
    <th>NewWiki</th>
    <td>
      Create new wiki articles. Mnemonic: <b>f</b>ast, English
      translation of the Hawaiian word <a
      href="https://en.wikipedia.org/wiki/History_of_wikis#WikiWikiWeb,_the_first_wiki"><i>wiki</i></a>.
    </td>
  </tr>

  <tr id="g">
    <th>g</th>
    <th>Clone</th>
    <td>
      Clone the repository. Note that this is distinct from <a
      href="#o">check-out capability, <b>o</b></a>; and that upon cloning
      not just files, but also tickets, wikis, technotes and forum posts
      are tranferred. Mnemonic: <b>g</b>et.
    </td>
  </tr>

  <tr id="h">
    <th>h</th>
    <th>Hyperlink</th>
    <td>
      Get hyperlinks in generated HTML which link you to other parts of
      the repository. This capability exists so we can deny it to the
      “nobody” category, to <a href="../antibot.wiki">prevent bots from
      wandering around aimlessly</a> in the site’s hyperlink web, <a
      href="../loadmgmt.md">chewing up server resources</a> to little
      good purpose. Mnemonic: <b>h</b>yperlink.
    </td>
  </tr>

  <tr id="i">
    <th>i</th>
    <th>Write</th>
    <td>
      Check changes into the repository. Note that a lack of this
      capability does not prevent you from checking changes into your
      local clone, only from syncing those changes up to the parent
      repo, and then <a href="./basics.md#webonly">only over HTTP</a>.
      Also note that not just files, but also tickets, wikis, technotes
      and forum posts will be accepted from clones upon syncronization.
      Granting this capability also grants <b>o (Read)</b>  Mnemonics:
      <b>i</b>nput, check <b>i</b>n changes.
    </td>
  </tr>

  <tr id="j">
    <th>j</th>
    <th>RdWiki</th>
    <td>
      View wiki articles. Mnemonic: in<b>j</b>est page content.  (All
      right, you critics, you do better, then.)
    </td>
  </tr>

  <tr id="k">
    <th>k</th>
    <th>WrWiki</th>
    <td>
      Edit wiki articles. Granting this capability also grants <a
      href="#j"><b>RdWiki</b></a> and <a href="#m"><b>ApndWiki</b></a>,
      but it does <em>not</em> grant <a href="#f"><b>NewWiki</b></a>!
      Mnemonic: <b>k</b>ontribute.
    </td>
  </tr>

  <tr id="l">
    <th>l</th>
    <th>ModWiki</th>
    <td>
      Moderate <a href="#m">wiki article appends</a>. Appends do not get
      saved permanently to the receiving repo’s block chain until <a
      href="#s">Setup</a> or someone with this cap approves it.
      Mnemonic: a<b>l</b>low.
    </td>
  </tr>

  <tr id="m">
    <th>m</th>
    <th>ApndWiki</th>
    <td>
      Append content to existing wiki articles.  Mnemonic: a<b>m</b>end
      wiki
    </td>
  </tr>

  <tr id="n">
    <th>n</th>
    <th>NewTkt</th>
    <td>
      File new tickets. Mnemonic: <b>n</b>ew ticket.
    </td>
  </tr>

  <tr id="o">
    <th>o</th>
    <th>Read</th>
    <td>
      Read content and history of files from a remote Fossil instance over
      HTTP. See <a href="index.md#read-v-clone">Reading vs.
      Cloning</a>. Mnemonic: check <b>o</b>ut remote repo contents.
    </td>
  </tr>

  <tr id="p">
    <th>p</th>
    <th>Password</th>
    <td>
      Change one’s own password. Mnemonic: <b>p</b>assword.
    </td>
  </tr>

  <tr id="q">
    <th>q</th>
    <th>ModTkt</th>
    <td>
      Moderate tickets: delete comments appended to tickets. Mnemonic:
      <b>q</b>uash noise commentary.
    </td>
  </tr>

  <tr id="r">
    <th>r</th>
    <th>RdTkt</th>
    <td>
      View existing tickets. Mnemonic: <b>r</b>ead tickets.
    </td>
  </tr>

  <tr id="s">
    <th>s</th>
    <th>Setup</th>
    <td>
      The <a href="./admin-v-setup.md#apsu">all-powerful Setup user</a>.
      Mnemonics: <b>s</b>etup or <b>s</b>uperuser.
    </td>
  </tr>

  <tr id="t">
    <th>t</th>
    <th>TktFmt</th>
    <td>
      Create new ticket report formats. Note that although this allows
      the user to provide SQL code to be run in the server’s context,
      and this capability is given to the untrusted “anonymous” user
      category by default, this is a safe capability to give to users
      because it is internally restricted to read-only queries on the
      tickets table only. (This restriction is done with an SQLite
      authorization hook, not by any method so weak as SQL text
      filtering.) Mnemonic: new <b>t</b>icket report.
    </td>
  </tr>

  <tr id="u">
    <th>u</th>
    <th>n/a</th>
    <td>
      Inherit all capabilities of the “reader” user category; does not
      have a dedicated flag internally within Fossil. Mnemonic:
      <a href="./index.md#ucat"><b>u</b>ser</a>
    </td>
  </tr>

  <tr id="v">
    <th>v</th>
    <th>n/a</th>
    <td>
      Inherit all capabilities of the “developer” user category; does
      not have a dedicated flag internally within Fossil.  Mnemonic:
      de<b>v</b>eloper.
    </td>
  </tr>

  <tr id="w">
    <th>w</th>
    <th>WrTkt</th>
    <td>
      Edit existing tickets. Granting this capability also grants <a
      href="#r"><b>RdTkt</b></a>, <a href="#c"><b>ApndTkt</b></a>, and
      <a href="#n"><b>NewTkt</b></a>. Mnemonic: <b>w</b>rite to ticket.
    </td>
  </tr>

  <tr id="x">
    <th>x</th>
    <th>Private</th>
    <td>
      Push or pull <a href="../private.wiki">private branches</a>.
      Mnemonic: e<b>x</b>clusivity; “x” connotes unknown material in
      many Western languages due to its <a
      href="https://en.wikipedia.org/wiki/La_Géométrie#The_text">traditional
      use in mathematics</a>.
    </td>
  </tr>

  <tr id="y">
    <th>y</th>
    <th>WrUnver</th>
    <td>
      Push <a href="../unvers.wiki">unversioned content</a>. Mnemonic:
      <b>y</b>ield, <a href="https://en.wiktionary.org/wiki/yield">sense
      4</a>: “hand over.”
    </td>
  </tr>

  <tr id="z">
    <th>z</th>
    <th>Zip</th>
    <td>
      Pull archives of particular repository versions via <a
      href="/help/www/zip"><tt>/zip</tt></a>, <a
      href="/help/www/tarball"><tt>/tarball</tt></a>, and <a
      href="/help/www/sqlar"><tt>/sqlar</tt></a> URLs. This is an
      expensive capability to grant, because creating such archives can
      put a large load on <a href="../server/">a Fossil server</a> which
      you may then need to <a href="../loadmgmt.md">manage</a>.
      Mnemonic: <b>z</b>ip file download.
    </td>
  </tr>

  <tr id="2">
    <th>2</th>
    <th>RdForum</th>
    <td>
      Read <a href="../forum.wiki">forum posts</a> by other users.
      Mnemonic: from thee <b>2</b> me.
    </td>
  </tr>

  <tr id="3">
    <th>3</th>
    <th>WrForum</th>
    <td>
      Create new forum threads, reply to threads created by others, and
      edit one’s own posts. New posts are <a
      href="../forum.wiki#moderation">held for moderation</a> and do
      not appear in repo clones or syncs. Granting this capability also
      grants <a href="#2"><b>RdForum</b></a>.   Mnemonic: post for
      <b>3</b> audiences: me, <a href="#5">the mods</a>, and <a
      href="https://en.wikipedia.org/wiki/The_Man">the Man</a>.
    </td>
  </tr>

  <tr id="4">
    <th>4</th>
    <th>WrTForum</th>
    <td>
      Extends <a href="#3"><b>WrForum</b></a>, bypassing the moderation
      and sync restrictions. Mnemonic: post <b>4</b> immediate release.
    </td>
  </tr>

  <tr id="5">
    <th>5</th>
    <th>ModForum</th>
    <td>
      <a href="../forum.wiki#moderation">Moderate forum posts</a>.
      Granting this capability also grants <a
      href="#4"><b>WrTForum</b></a> and <a href="#2"><b>RdForum</b></a>,
      so a user with this cap never has to moderate their own posts.
      Mnemonic: “May I have <b>5</b> seconds of your time, honored
      Gatekeeper?”
    </td>
  </tr>

  <tr id="6">
    <th>6</th>
    <th>AdminForum</th>
    <td>
      Users with this capability see a checkbox on unmoderated forum
      posts labeled “Trust user X so that future posts by user X do not
      require moderation.” Checking that box and then clicking the
      moderator-only “Approve” button on that post grants <a
      href="#4"><b>WrTForum</b></a> capability to that post’s author.
      There is currently no UI for a user with this cap to
      <em>revoke</em> trust from a user once it is granted; only <a
      href="#a"><b>Admin</b></a> and <a href="#s"><b>Setup</b></a> can
      currently revoke granted caps.  Granting this capability also
      grants <a href="#5"><b>ModForum</b></a> and those it in turn
      grants.  Mnemonic: “I’m <b>6</b> [sick] of hitting Approve on your
      posts!”
    </td>
  </tr>

  <tr id="7">
    <th>7</th>
    <th>EmailAlert</th>
    <td>
      User can sign up for <a href="../alerts.md">email alerts</a>.
      Mnemonic: <a href="https://en.wikipedia.org/wiki/Heaven_Can_Wait">Seven can
      wait</a>, I’ve got email to read now.
    </td>
  </tr>

  <tr id="A">
    <th>A</th>
    <th>Announce</th>
    <td>
      Send email announcements to users <a href="#7">signed up to
      receive them</a>. Mnemonic: <b>a</b>nnounce.
    </td>
  </tr>

  <tr id="B">
    <th>B</th>
    <th>Attach to Forum</th>
    <td>
      Add attachments to forum posts. See also: <a href='#b'>b</a>.
    </td>
  </tr>

  <tr id="C">
    <th>C</th>
    <th>Chat</th>
    <td>
      Allow access to the <tt>/chat</tt> room.
    </td>
  </tr>

  <tr id="D">
    <th>D</th>
    <th>Debug</th>
    <td>
      Enable debugging features. Mnemonic: <b>d</b>ebug.
    </td>
  </tr>

  <tr id="L">
    <th>L</th>
    <th>Is-logged-in</th>
    <td>
      This is not a real capability, but is used in certain capability
      checks, e.g. via <a href="../th1.md#capexpr">capexpr</a>. It
      resolves to true if the current user is logged in.
      Mnemonic: <b>L</b>ogged in.
    </td>
  </tr>

</table>

<hr/>

<p id="backlink"><a href="./"><em>Back to Administering User
Capabilities</em></a></p>