I've installed Veracity. How do I get started using it?

This is a command-line focused guide. If you'd like to see how to get started using a GUI on Windows, try this instead.

Creating a repository

Choose your favorite projects folder, or temp, or whatever. Let's say you've chosen ~/projects. Now create a vvtest working copy under that:

cd ~/projects
mkdir vvtest
cd vvtest
vv init vvtestrepo .

Two things happened: a vvtestrepo repository was created, and your current directory (~/projects/vvtest) became a working copy of that repository. The repository, and the folder, are empty right now.

Who am I?

We should tell Veracity who you are. Run

vv whoami --create myemail@example.com

The --create flag will try to create the user first, so you will only need to use that flag the first time you run whoami.

Adding some stuff

Let's give Veracity something to do. Create a file:

echo Hello, world > file.txt

Then say

vv status

and you should see

Found: @/file.txt

"Found" means Veracity sees a file it doesn't yet know about. "@/" is the root of the repository. To tell Veracity to keep track of this file:

vv add file.txt

vv status will now say:

Added: @/file.txt

Let's commit that to the repository, so we can play with it a bit.

vv commit -m "I added a file"

Where -m "..." is the comment that will be associated with this checkin. If you leave out that parameter, you'll be greeted by a text editor, where you should enter your comment.

Things we can now do:

vv rename file.txt somethingelse.txt
vv move file.txt someotherdir/
vv remove file.txt

All of which must be followed by a vv commit to be recorded. Prior to that, vv revert can undo your changes.

If you change the file on disk, e.g.

echo Another line >> file.txt

vv status will list it as "Modified". You can see the changes by saying vv diff file.txt for one file, or just vv diff to see all uncommitted file changes.

Running the server

So far, this is all local. To share your code and changes with others, you'll need to run a server, or connect to someone else's. For now, you'll be the server.

Still in your vvtest directory, run:

vv serve

Veracity's internal web server is up and running on Port 8080. Open a browser (not IE, just yet, but Chrome, Safari, Firefox should work nicely) and you can see your history, add work items, and so on.

Playing with Others

What you can also do is push and pull code through this server.

Assuming the machine you've been using is vvhost, move over to vvclient.

On the client, to get a working copy of that same code:

cd ~/projects/
vv clone http://vvhost:8080/repos/vvtestrepo vvtestrepo
vv checkout vvtestrepo vvtest
cd vvtest

And you're in a working copy of a clone of the original repo.

Make your own local changes, commit them, then:

vv push

to send them back to the host. If you see an error complaining that this would create multiple heads, that means there are changes on the host side that you haven't pulled yet. Get those, merge them locally, then push. Actually, it's a better idea to always pull, merge, run unit tests, and commit the merge before pushing.

vv pull
vv merge
# test, test, test
vv commit -m "merged changes from host"
vv push