Get started with code hosting

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).