Your first repository, step by step

This guide builds a small project from scratch. Along the way you'll learn the four ideas everything else in zev is built on: the **working folder**, the **staging area**, **commits**, and **history**. If you haven't installed zev yet, start with [Installation](/docs/en/installation). ## Create the repository ```bash mkdir notes cd notes zev init ``` ```text Initialized empty Zev repository in ./.zev/ ``` A *repository* (or *repo*) is a folder whose history zev keeps. All of that history lives in the hidden `.zev` folder. Don't edit it by hand; if you delete it, the folder becomes a normal folder again and the history is gone. Set your name and email once per project. They go on every commit you make: ```bash zev config set user.name "Sara Ahmadi" zev config set user.email "sara@example.com" ``` ## The three places your work lives It helps to picture three places: | Place | What it is | How things get there | |---|---|---| | **Working folder** | Your files, as you see them in your editor | You edit them | | **Staging area** | The changes you've picked for the next commit | `zev add` | | **History** | Every commit you've made, saved for good | `zev commit` | Nothing reaches history by accident. You choose what to stage, and then you commit it. ## Make your first commit Create two files: ```bash echo "Buy milk" > todo.txt echo "Ideas for the project" > ideas.txt ``` Ask zev what it sees: ```bash zev status ``` ```text On branch main Untracked files: (zev add <file> to start tracking; list in .zevignore to hide) ideas.txt todo.txt ``` *Untracked* means zev sees the files but isn't keeping their history yet. Stage both and commit: ```bash zev add . zev commit -m "Start my notes" ``` ```text added ideas.txt added todo.txt Staged 2 change(s). Next: zev commit -m "what you changed" Created commit: 5f7f5e226bb19014179575681efba0f8be95eb6a8e64c1fc7dbc6f4d68224d01 Committed 2 file(s) ``` That long string is the commit's **ID**. It is a fingerprint (a hash) of everything in the commit, so it can never be confused with another commit. You only ever need to type its first few characters, for example `5f7f5e22`. **Good commit messages** say what changed and why, in a few words: "Fix login when the password has spaces" is much more useful later than "fix". ## Look at what changed Change one file and add a new one: ```bash echo "Buy bread" >> todo.txt echo "Call Ali" > calls.txt zev status ``` ```text On branch main Changes not staged for commit: (zev add <file> to include them; zev restore <file> to throw them away) modified: todo.txt Untracked files: (zev add <file> to start tracking; list in .zevignore to hide) calls.txt ``` See the changed lines: ```bash zev diff ``` ```text modified: todo.txt @@ -1,1 +1,2 @@ Buy milk +Buy bread ``` `+` is a line that was added and `-` a line that was removed. The `@@ -1,1 +1,2 @@` line tells you where in the file the change is: old file from line 1 (1 line), new file from line 1 (2 lines). You can ignore it at first. Now commit only `todo.txt`, and leave `calls.txt` for later: ```bash zev add todo.txt zev diff --staged zev commit -m "Add bread to the list" ``` `zev diff --staged` shows exactly what the next commit will contain. It's a good habit to check it before committing. ## Read the history ```bash zev log ``` ```text commit 8a41c2d0… Author: Sara Ahmadi <sara@example.com> Date: 2026-10-04 09:25 UTC Add bread to the list commit 5f7f5e22… Author: Sara Ahmadi <sara@example.com> Date: 2026-10-04 09:20 UTC Start my notes ``` The newest commit is on top. A shorter view, one line per commit: ```bash zev log --oneline ``` To see one commit and exactly what it changed: ```bash zev show 5f7f5e22 # by the start of its ID zev show HEAD # the newest commit zev show HEAD~1 # the one before it ``` `HEAD` means "the commit you're on now". `HEAD~1` is one before it, `HEAD~2` two before, and so on. ## Undo things Everyone makes mistakes. Here's how to get out of the common ones. **Throw away changes you haven't staged** (go back to the last commit's version of a file): ```bash zev restore todo.txt ``` Be careful: the changes you throw away are gone for good, because they were never committed. **Unstage a file** (keep your edits, but take the file out of the next commit): ```bash zev restore --staged todo.txt ``` **Put changes aside for a moment** (for example, to look at something else with a clean folder): ```bash zev stash zev stash pop # bring them back ``` **Bring back a file you deleted by mistake** (if it was committed before): ```bash zev restore calls.txt ``` More situations, such as deleting and renaming files, are in [How do I…?](/docs/en/how-do-i). ## Delete or rename a file To delete a file and record that in the next commit: ```bash zev rm ideas.txt zev commit -m "Remove ideas" ``` Deleting the file any other way works too. Then `zev add ideas.txt` (or `zev add .`) stages the deletion. To rename, rename the file normally and stage both names: ```bash mv calls.txt phone.txt zev add calls.txt phone.txt zev commit -m "Rename calls to phone" ``` ## Keep some files out Build output, logs and secrets don't belong in history. List them in a file called `.zevignore` in the top folder of the project: ```text # .zevignore node_modules/ build/ *.log .env ``` Ignored files don't show up in `zev status`, and `zev add .` skips them. Commit `.zevignore` itself so everyone working on the project ignores the same files. ## What's next - [Branches and merging](/docs/en/branches): try ideas without touching your main work. - [Share your work on Zaryn](/docs/en/pushing-and-pulling): push, pull and clone. - [All commands](/docs/en/commands): the full reference.