dehub/docs/tut1.md

# Tutorial 1: Create Your Own Project

This tutorial will guide you through starting a dehub project of your own, as
well as introducing some basic concepts regarding how commit payloads work. You
will use an example hello world project to do this.

This tutorial assumes you have already completed [Tutorial 0](tut0.html).

## Step 0: Init the Project

A dehub project is initialized in the same way as a git project. An empty
directory is created, and `dehub init` is run within that directory.

```
mkdir hello-world
cd hello-world
dehub init
```

`dehub init` does nearly exactly the same thing as `git init`, with the primary
difference being that it sets the initial branch to be `main` instead of
`master`. dehub makes a distinction between `main` and `master` in order to help
prevent confusion between dehub and vanilla git projects, as well as to avoid
conflicts when migrating vanilla git projects to dehub.

## Step 1: Add the First Account

A dehub project is not fully initialized until it has an account defined for it.
dehub accounts refer to a specific user who has some kind of access to the
project. Each account can have specific permissions for it, as well as multiple
ways of signifying itself.

For now, you'll add a basic account `tut` with a pgp key signifier. First,
create the `.dehub` directory, which is where all dehub project configuration
goes, and put your pgp key there:

```
mkdir .dehub
gpg -a --export KEY_ID > .dehub/tut.asc
```

Next you'll create the `.dehub/config.yml` file, which is where accounts are
actually defined (amongst many other things). The file should have the following
contents:

```yaml
# contents of .dehub/config.yml
---
accounts:
  - id: tut
    signifiers:
      - type: pgp_public_key_file
        path: ".dehub/tut.asc"
```

Finally, you'll commit these changes and the project will have its first commit!
Committing changes works very similarly to committing comments (as you did in
[Tutorial 0](tut0.html)). Where a comment commit merely carries a user's
comment, a change commit describes a set of changes to the tracked files in the
git repo.

```
git add --all
dehub commit --as tut change
```

Like when you made a comment commit, this will pop up with your editor asking
for a description of the changes. Fill it in with something like `Initialize the
project` and save+close the editor. Depending on your pgp key settings you'll
likely be prompted for your pgp key password at this point. After that the
commit has been created!

## Step 2: Inspect the Payload

In this step you're going to look at the commit you just created and learn about
the contents of the payload. To view the commit do `git show`. Something similar
to the following should be output as the commit message:

```
commit 3cdcbc19546d4e6d817ebfba3e18afbc23283ec0
Author: username <>
Date:   Sat Apr 25 15:17:21 2020 -0600

    Initialize the project

    ---
    type: change
    description: Initialize the project
    fingerprint: AG0s3yILU+0uIZltVY7A9/cgxr/pXk2MzGwExsY/hbIc
    credentials:
    - type: pgp_signature
      pub_key_id: 95C46FA6A41148AC
      body: BIG LONG STRING
      account: tut
```

All commits in a dehub project will contain a similar looking message. The first
line (the head) is always a human readable description of the commit. In this
case our commit description itself, `Initialize the project`, was used.

After the head comes the payload, which is always a YAML encoded object. All
payloads have a `type` field indicating what type of payload they are. That type
will determine what other fields the payload is expected to have. The other
fields in this payload object are:

* `description`: This is the description which was input into the editor when
  creating the change commit.

* `fingerprint`: A unique descriptor for this set of changes. It is computed
  using both `description` and the files changed.

* `credentials`: A set of credentials for this commit, each one declaring
  that this commit has been given approval by a user. This commit has one
  `pgp_signature` credential, created by the `tut` account. The `body` is a
  signature of the `fingerprint` created by the `tut`'s pgp key.

## Step 3: Create Another Commit

Now that the initial commit is created, and configuration has been added to the
dehub project, you can continue on to use the project for what it was intended
for: greeting the world!

Add a simple "hello world" script to the project by doing:

```
echo 'echo "hello world"' > hello.sh
git add hello.sh
dehub commit --as tut change --descr 'add hello.sh'
```

You'll notice that this time around you used the `--descr` flag to declare the
change's description, rather than opening up the editor

Once again you can inspect the payload you just created using `git show`, if
you'd like, or continue on to the next step to learn about commit verification.

## Step 4: Verify Your Commits

All this work to create YAML encoded payloads has been done for one primary
purpose: to make commits verifiable. A verifiable commit is one which follows
the access controls defined by its parent.

Your dehub project doesn't have any explicitly defined access controls (that
will be covered in a future tutorial), and so the defaults are used. By default,
dehub requires that all commits in `main` are change commits which have been
signed by at least one account.

In order to verify the HEAD commit you can do:

```
dehub verify
```

This command looks at the project configuration defined in the parent of HEAD
and verifies that HEAD conforms to it. The HEAD of your project is a change
commit signed by the account `tut`, and so should be verifiable.

Arbitrary commits can be verified using the `--rev` flag. This command will
verify the parent of HEAD, i.e. the initial commit:

```
dehub verify --rev HEAD^
```

The initial commit doesn't have a parent, and so is a special case for
verification. The initial commit uses the configuration defined within itself in
order to verify itself. This creates an exploit opportunity: if you clone a
remote dehub project and an attacker intercepts that request they will be able
to send you back a project with a different initial commit than what you
expected. The whole project will still be verifiable, even though it's been
compromised. For this reason it's important to manually verify that the initial
commit of projects you clone are configured correctly, using the expected
signifiers for the expected accounts.

You are now able to initialize a project, configure accounts within it, commit
changes to its files, and verify those commits. Well done! Continue on to
[Tutorial 2](tut2.html), where you will learn how to configure dehub's access
controls.