# Get started with code hosting

> A guided path from your first repository to signed, provable history: what code hosting is, how zev and Zaryn work, the everyday loop, branches and pull requests, finding and undoing things, and the advanced features. Pictures first, every step explained.

Source: https://zaryn.xyz/docs/en/get-started-code

This tutorial goes from "what is code hosting?" to signed, provable history. Completely new to version control? Read [Version control in pictures](/docs/en/version-control-in-pictures) first: it explains commits, branches and merges with pictures in ten minutes.

## 1. What code hosting is

```diagram
type: graph
title: One project, everyone's copy, one place in between
alt: Your computer and a teammate's each hold the full history; Zaryn holds the shared copy with pull requests, issues and CI around it
legend: path=Push and pull
height: 40
---
node you | your computer | 12 20 | laptop | accent | The full history, offline: commit, branch, look back without internet
node z | Zaryn | 50 20 | cloud | good | The shared copy, plus everything around it: pull requests, issues, CI, the website
node mate | a teammate | 88 20 | laptop | | Their own full copy
link you z | push, pull | path
link z mate | pull, push | path
```

**Version control** remembers every version of a project you save, so you can see what changed, go back, and work with others. **Code hosting** puts a shared copy online where your team, your CI and anyone you choose can reach it. **zev** is the version control tool on your computer; **Zaryn** is where the shared copy lives.

## 2. What makes zev different

```diagram
type: cards
---
#️⃣ | Content-addressed | Every file, folder and commit is named by the hash of its content: change one byte, and its name changes | accent
✍ | Signed | zev signs every new commit on your computer; Zaryn shows it as Verified once the key is on your account |
🧱 | Big files, small transfers | Large files are cut into chunks; an edit sends only the chunks that changed | good
🌐 | Open by design | Objects are IPFS objects: a published snapshot opens anywhere, not only on Zaryn |
🧠 | Understands code | A semantic diff says a function was renamed, not "20 lines changed" |
🤖 | Ready for agents | Every command has a JSON mode; AI agents work through `zev mcp` |
```

What it means for you: nobody, Zaryn included, can quietly change your history, and anyone can check that without trusting us.

## 3. What's free

```diagram
type: stats
title: The Free plan
---
∞ | public repositories | anyone can read them | |
5 | private repositories | only you and those you invite | | accent
2 GB | in total | across your repositories | |
250 MB | per file | bigger files are split into chunks anyway | |
```

Need more private repositories, space or Premium features later? See [Plans](/docs/en/billing-and-credits).

## 4. Install zev and sign in

```diagram
type: flow
title: Five minutes, once per computer
or: or
---
Install | One line on Linux or macOS; one on Windows | | ⬇
~ zev login
New to Zaryn | `--register you --email …`, then the emailed code | accent | ✉
? Have an account | `--device`: approve in your browser
~ done
Signed in | Every zev command now knows who you are | good | ✓
```

```bash
curl -fsSL https://zaryn.xyz/install.sh | sh            # Linux and macOS
zev login zaryn.xyz --register your-name --email you@example.com
```

On Windows: `irm https://zaryn.xyz/install.ps1 | iex`. Package managers and checking the download: [Installation](/docs/en/installation).

## 5. Your first repository

```diagram
type: flow
title: From a folder to a repository on Zaryn
---
zev init | Your folder starts keeping history | | 📁
~ zev add, zev commit
First commit | A save point with a message | accent | ✓
~ zev new
On Zaryn | Name, kind, public or private, licence; `origin` set | | ☁
~ zev push
Online | `zaryn.xyz/you/notes`, every version with it | good | 🌐
```

```bash
cd notes
zev init
zev add .
zev commit -m "Start my notes"
zev new          # asks for a name, public or private, a licence
zev push
```

No terminal? On [Repos](/repos), choose **New repository** and press **Upload** to add files from the browser. Every command above is explained in [Your first repository](/docs/en/first-repository).

## 6. The everyday loop

```diagram
type: flow
title: The loop you'll repeat every day
loop: pull, change, add, commit, push
---
zev pull | Get everyone's latest work first | | ⇣
~ edit files
zev add | Pick what goes in the next save point | | 📥
~ zev commit
Commit | A save point, with what you did and why | accent | ✓
~ zev pull, then zev push
Shared | Your work on top of everyone's | good | ⇡
```

`zev status` tells you where everything is at any moment, and `zev diff` shows the lines you changed. Pull before you push: if a teammate pushed meanwhile, your work goes on top of theirs. [Push and pull, with pictures](/docs/en/pushing-and-pulling#the-team-routine).

## 7. Branches: try things safely

```diagram
type: history
title: A branch for each piece of work
start: main
---
branch main | accent
branch login-fix | good | from B
commit A main | Start
commit B main | Add the menu
step zev checkout -b login-fix | A new line of work. main stays exactly as it was.
step Commit on the branch | Two commits, only on login-fix.
commit C login-fix | Fix the button
commit D login-fix | Add a test
step Meanwhile on main | Others keep working on main.
commit E main | Update the footer
```

```bash
zev checkout -b login-fix        # make a branch and switch to it
zev checkout main                # back to main
```

A branch is just a name pointing at a commit, so it costs nothing. One branch per change keeps `main` working. [Branches and merging](/docs/en/branches).

## 8. Pull requests and reviews

```diagram
type: flow
title: Ask before you merge
or: or
---
Push the branch | `zev push`: login-fix is on Zaryn | | ⑂
~ zev pr
Pull request | Title and description drafted from your commits | accent | 📬
~ review
Review | Comments on any line; approve, or ask for changes | warn | 👀
? Changes asked | Push more commits, the pull request updates itself
~ checks pass
Merged | On the website, or `zev pr merge 7` | good | ✓
```

```bash
zev pr                 # opens a pull request from the branch you're on
zev pr list            # what's open
zev pr merge 7         # merge it once it's approved
```

A pull request shows the diff, runs [CI](/docs/en/get-started-ci) and [evals](/docs/en/evals-and-lineage), and merges only when nobody's request for changes is outstanding. [Collaboration from the terminal](/docs/en/cli-collaboration).

## 9. Issues, collaborators and organizations

```diagram
type: cards
---
🐞 | Issues | Report a bug or suggest an idea: the Issues tab, or `zev issue` | accent
🤝 | Collaborators | Invite someone to a repository: open it, then Collaborators |
🏢 | Organizations | A team under one name, with its own repositories and roles | good
🍴 | Forks | Your own copy of someone else's project: `zev fork-repo`, then a pull request back |
```

## 10. When both changed the same lines

```diagram
type: diff
title: A conflict, as zev marks it
file: index.html
---
  <h1>
+ <<<<<<< main
+ Welcome to my site
+ =======
+ Welcome! Search below
+ >>>>>>> login-fix
> main's version above, the branch's below: keep one, the other or a mix, then delete the marker lines
  </h1>
```

Merging usually just works. When two people changed the same lines, zev changes nothing and asks you:

```bash
zev merge login-fix --resolve    # marks each place both sides changed
# edit the files, keep what you want, remove the marker lines
zev add index.html
zev merge --continue             # or zev merge --abort to go back
```

Step by step: [When both changed the same lines](/docs/en/branches#when-both-changed-the-same-lines).

## 11. Find anything in history

```diagram
type: cards
title: Six ways to look back
---
📜 | zev log | Every commit, newest first; `--oneline` for one line each |
🔍 | zev show | One commit and exactly what it changed | accent
🧑‍💻 | zev blame | Who last changed each line of a file, and in which commit |
⚖ | zev diff, zev compare | Any two versions side by side |
🔎 | zev search | Commits, experiments, metrics and snapshots |
🌐 | The Commits page | Filter the whole history by person, kind (feat, fix…) or words | good
```

```bash
zev log --oneline
zev blame src/login.js
zev show HEAD~1
```

## 12. Undo mistakes safely

```diagram
type: cards
title: The four undos you'll actually use
---
↩ | Throw away edits to a file | `zev restore file`: back to the last commit (those edits are gone) | warn
📤 | Take a file out of the next commit | `zev restore --staged file`: your edits stay |
🧺 | Put changes aside | `zev stash`, later `zev stash pop` | good
➕ | Undo a commit | Make a new commit that reverses it: history stays honest | accent
```

zev never rewrites commits you've made, so an undo can't destroy someone else's work. Every situation, answered: [How do I…?](/docs/en/how-do-i#undo).

## 13. Big files and models

```diagram
type: stats
title: An edit near the start of a 1.7 MB file
---
~1% | of its chunks sent again | the rest were already on both sides | 1 | good
2 | identical files | stored once: same content, same name | | accent
```

zev cuts large files into chunks by their content, so an edit only sends the chunks around it, on push and on pull. Data, model weights and media live next to the code, without a separate large-file tool. [Content-defined chunking](/docs/en/chunking).

## 14. Prove it: history anyone can check

```diagram
type: flow
title: Trust, but verify
---
Signed | every new commit, on your computer; `zev signing-key add` once and Zaryn shows them as Verified | | ✍
~ zev verify-storage
Stored | Cryptographic proof Zaryn really keeps everything you pushed | accent | 🧾
~ zev notarize
Anchored | A commit's hash on a public blockchain: proof it existed then | good | ⛓
```

```bash
zev signing-key add           # once: your signed commits show as Verified
zev verify-storage            # does Zaryn really hold my last push?
zev notarize commit <id>      # public proof this commit existed today
zev audit                     # the repository's full provenance report
```

[Signed commits](/docs/en/signed-commits) and [Verified storage](/docs/en/verified-storage) explain the proofs.

## 15. Private, and encrypted

```diagram
type: flow
title: Encrypted before it leaves your computer
---
Private repository | Only you and those you invite | | 🔒
~ zev encrypt on
Encrypted | File contents locked with a key only your devices hold | accent | 🔐
~ zev encrypt share
Teammates | Each of their devices gets the key | good | 🤝
```

For work that must stay private even from the host, turn on encryption before the first push. Zaryn then stores what it can't read. [Encrypted repositories](/docs/en/encrypted-repositories).

## 16. Automate it

```diagram
type: cards
---
▶ | CI | Every push built and tested in a locked-down container: `zev ci enable` | accent
📈 | Evals | A pull request that makes a benchmark or a bundle worse can't merge | good
🤖 | AI agents | Sign an agent in through you, and give it `zev mcp` | 
🧾 | Scripts | `--json` on every command, data on stdout, exit codes that mean something |
```

You've gone from your first repository to provable, automated history. Next: [Get started with CI](/docs/en/get-started-ci), [How do I…?](/docs/en/how-do-i) for quick answers, and [Scripting and AI agents](/docs/en/automation-and-agents).