iv-notes.md

iv, the inlang versioner

Main Concepts

Everything Is a Branch

The iv tool is based around the concept of branches, just like Git. In this case however, there are only branches. Instead of a remote, the user creates a new branch that is synced with a remote. Instead of a workdir and index, there is a "workbranch" which is synced to the filesystem.

Commit Splitting

The larges change from git to iv is how committing is handled. Since the work branch is now synced to the filesystem, and there is no concept of an "index", the process of committing changes is simplified, although it is somewhat different then canonical Git.

Instead of manually committing changes as they are made, the user is prompted to "annotate" their commit before it is added to a branch. Different sections of the commit can be grouped and annotated to signify how the commit should be split.

Unlike in Git, we commit once, and commit for good. In canonical Git, a "clean" commit history is achieved by creating several incremental commits followed by a series of interactive rebases (which can then lead to rebase conflicts). In iv, committing is done once, and no rebasing is required.

Under the hood, this is done by generating a diff between the work branch and the active branch. This diff is then split into multiple diffs according to the user's annotations and each diff is applied to the tip of the active branch as a commit.

Based on these concepts, the iv tool provides a few commands to help version your code (or anything else really).

Commands

• iv init
  • Identical to git init, initializes a new repo
• `iv branch < new branch name > [ commit or url ]
  • Creates a new branch. If the second option is empty, the branch will begin at the branch you are currently on. If the second option is a commit, the branch will begin at that commit. If the second option is a url, the branch will sync to the branch with the same name at that remote.
• iv switch < branch name >
  • Changes the active branch to the specified branch
• iv log
  • Provides the history of the workbranch
• iv undo < number of changes to go back > [ file ]
  • If the second option is empty, reverts the specified number of changes on your workbranch. If the second option is not empty, reverts the specificed number of changes on a particular file. If both options are empty, reverts the last change on your workbranch.
• iv merge
  • Identical to git merge, merge a branch
• iv commit [-m <message>]
  • Commits the changes from your workbranch to the active branch. If the -m option is specified, all changes from the workbranch are added in a single commit. Otherwise the user is prompted to split, annotate and re-order commits as desired.
  • Note: on a lower level, commit does not merge the workbranch with the active branch as one may expect. Instead we generate a diff of the workbranch and active branch, then apply it on top of the active branch as one (or multiple) commits.
• iv resolve [ conflict # ] | [ all ]
  • Use the builtin mergetool to interactivly resolve one or more merge conflicts.

Basic examples

Getting started

iv init
iv branch main https://github.com/user/repo

Making changes and pushing them upstream

*edit some files*
iv commit

The end. This is the limit of what most people will be doing most of the time.

Creating a feature branch

iv branch feature
*edit some files*
iv commit

Merging the feature branch into main

iv merge feature main

Resolving merge conflicts:

iv resolve
[ They wanted these lines to be ]
- hello world
- hola mundo
[ You wanted these lines to be ]
- hello mudo
- hola world
[ Do you want to use: (m)ine, (t)heirs, (e)dit manually ]
... etc
*resolve conflicts using the interactive mergetool*
iv commit