<template>
  <div>
    <div class="title">
      <h1>Quick-start guide</h1>   
      <p>Get going with Dotty using this guide.</p>
    </div>

    <div class="alert alert-info">
    <strong>Just in case...</strong><br>
    Whilst we're in beta we recommend that you make your own temporary backups of any files you store using Dotty.</div>

    <p>To get started, we recommend that most people directly use the official CLI tool documented on this page.</p>
    
    <p>Afterwards, check-out the <router-link :to="{name: 'DocumentationClient'}">reference documentation</router-link> to keep up-to-date.</p>

    <h3>Installation of <span class="code">dotty</span></h3>
    <p>Use of the CLI tool requires that you install the <span class="code">dotty</span> application on machines that you want to access your Dotty account from. Pre-compiled binaries are available for 64-bit Linux and MacOS systems:</p>
    <div class="code-block">
      curl https://dotty.cloud/static/install_dotty.sh -O<br />
      chmod +x install_dotty.sh<br />
      ./install_dotty.sh<br />
    </div>
    <div class="alert alert-info">You may need to use <span class="code">sudo</span> to run the third line. It tries to install to <span class="code">/usr/local/bin</span>.</div>
    <div class="alert alert-warning">We recommend <a href="https://www.seancassidy.me/dont-pipe-to-your-shell.html" target="_blank">not piping directly to your shell</a> for execution.</div>
    <p>After installation has completed, you can safely remove <code>install_dotty.sh</code>.</p>

    <h3>Registering a new account</h3>
    <div class="alert alert-info">
      By using the Dotty client or API you agree to Dotty's <a href="/privacy" target="_blank">Privacy Policy</a> and <a href="/terms" target="_blank">Terms of Use</a>.
    </div>
    <p>Create a new account directly using the CLI.</p>
    <div class="code-block">
      dotty register
    </div>
    <p><span class="code">dotty</span> will ask you for an email address and password to complete registration. If you don't see any errors then everything succeeded and you can continue.</p>
    <p>Email-based authentication is on the roadmap for password-less registration.</p>

    <h3>Logging-in to an existing account</h3>
    <p>If you already have an account, then login:</p>
    <div class="code-block">
      dotty login
    </div>
    <p>As with <span class="code">register</span>, you'll be asked for your email address and password and if you don't see any errors then the login succeeded.</p>

    <h3>Adding your first file</h3>
    <p>Now you are ready to add your first file!</p>
    <p>On Dotty, all of your files must have a unique <strong>key</strong> which should be memorable and relevant to the type of file you are storing.</p>
    <p>For example, a key for your <span class="code">.vimrc</span> file might be simply <span class="code">vimrc</span> (or, if you have multiple configs like this, something like <span class="code">home-vimrc</span>).</p>
    <p>Add a file to Dotty using:</p>
    <div class="code-block">
      dotty add -k vimrc -f ~/.vimrc
    </div>
    <p>This command will add <span class="code">vimrc</span> to your local configuration and also push it to your Dotty account in the cloud. If you don't see any errors, then everything happened successfully.</p>

    <h3>Listing your configs</h3>
    <p>To quickly see a list of all the configs you've added to Dotty, then run:</p>
    <div class="code-block">
      dotty ls<br><br>
      Configurations you've added to Dotty:<br><br>
      vimrc   (default: /home/jane/.vimrc local: /home/jane/.vimrc)<br>
    </div>
    <p>Here we can see one dotfile listed - the one we added earlier. <span class="code">dotty</span> displays the dotfile key, its default path, and the path on the local machine.</p>
    <p>The default path is taken from the first time you added this file. Since we added from this same machine, the default and local paths are the same. However, this may not always be the case (for example, on MacOS, Jane's home directory would be <span class="code">/Users/jane</span>).</p>
    <p>If there is no local record of the specified key (i.e. if this config has not yet been pulled down to a new computer, then the <span class="code">local</span> part will be omitted.</p>

    <h3>Pushing a config</h3>
    <p>If you make changes to a previously-<span class="code">add</span>ed config, then you will want to push it up to Dotty to ensure it's backed-up and ready to be pulled to your other machines:</p>
    <div class="code-block">
      dotty push -k vimrc
    </div>
    <p><span class="code">dotty</span> uses your local configuration to resolve the path for the specified file. If the file doesn't exist or if the file hasn't yet been added you will receive an error.</p>

    <h3>Pulling a config to a new machine</h3>
    <p>Now imagine you're getting your MacBook out in the evening to continue working in front of a movie and you want to update your <span class="code">~/.vimrc</span> file with the changes you made earlier. Assuming you've installed <span class="code">dotty</span> and logged-in on this new machine:</p>
    <div class="code-block">
      dotty pull -k vimrc<br><br>
      vimrc is new. Enter a local path (/home/jane/.vimrc): ~/.vimrc<br><br>
      Written vimrc to /Users/jane/.vimrc<br>
    </div>
    <p>Since <span class="code">vimrc</span> wasn't in the local configuration, <span class="code">dotty</span> prompted for a local path with which to track the dotfile. Although it recommended the default path set when we added the file from the Linux machine earlier, this path is not right for the Mac, and so we specified a new path.</p>
    <p>Now, whenever we push/pull from/to the Mac, it will use the correct path.</p>
    <div class="alert alert-info">Note that <span class="code">dotty</span> will automatically create any required directories when writing the file as the result of issuing the <span class="code">pull</span> command.</div>

    <h3>Updating local Dotty configuration</h3>
    <p>Now, imagine Jane has made some changes to her Tmux configuration on her Mac and adds it using the key <span class="code">tmux</span>.</p>
    <p>The next day, when Jane is working on her Linux workstation, she realises she actually made a mistake and wants to set-up a different Tmux configuration, which she does by writing to <span class="code">~/.tmux.conf</span> locally. She then wants to push this new configuration, but since she hasn't yet pulled the version she wrote on her Mac she has a problem:</p>
    <ul>
      <li>She can list the configs in Dotty using <span class="code">ls</span>, which shows the local Dotty configuration doesn't know the path for <span class="code">tmux</span>.</li>
      <li>Therefore she cannot <span class="code">push</span> the file unless she <span class="code">pull</span>s first, which would overwrite her changes.</li>
    </ul>
    <p>Luckily, Jane can update her local configuration without overwriting her changes by issuing the <span class="code">update</span> command:</p>
    <div class="code-block">
      dotty update<br><br>
      tmux is a new file. Enter a local path (/Users/jane/.tmux.conf): ~/.tmux.conf<br><br>
      Local configuration now up-to-date.<br>
    </div>
    <p><span class="code">dotty</span> is now configured to track the file with key <span class="code">tmux</span> and path <span class="code">/home/jane/.tmux.conf</span>. She can now push the file:</p>
    <div class="code-block">
      dotty push -k tmux
    </div>

    <h3>Local Dotty configuration</h3>
    <p><span class="code">dotty</span> maintains its local configuration on each machine using its own dotfile, <span class="code">~/.dotty.json</span>.</p>
    <p>This file is safe to edit by hand, if you prefer this to using the commands provided by the <span class="code">dotty</span> tool itself. However, if you write invalid JSON then the tool will break.</p>
    <p>The file itself is very simple, with a typical structure:</p>
    <pre class="code-block">
      {
        "accessToken": "xxx.yyy.zzz",
        "configs": [
          {
            "key": "vimrc",
            "path": "/Users/jane/.vimrc"
          },
          {
            "key": "tmux",
            "path": "/Users/jane/.tmux.conf"
          }
        ]
      }
    </pre>
    <p>The <span class="code">accessToken</span> field spcifies the token which authorises <span class="code">dotty</span> against your Dotty account in the cloud when making authenticated requests.</p>
    <p>The <span class="code">configs</span> array lists all files in the local configuration, along with the key and the path to the file locally.</p>
    <div class="alert alert-warning">We strongly recommend that you don't add <span class="code">~/.dotty.json</span> to Dotty as this may introduce race problems and removes the point in having a local configuration.</div>

    <h3>Next steps</h3>
    <p>To become an expert and stay on top of what Dotty can do as it grows, we recommend staying up-to-date with the <router-link :to="{name: 'DocumentationClient'}">CLI tool reference documentation</router-link>.</p>

  </div>
</template>

<script>
export default {
  name: 'documentationClient',
  data() {
    return {
    };
  },
};

</script>

<style scoped lang="scss">

</style>
