Map your first project

A project is a git repository on your computer. Graphide reads its code into a graph of its parts and how they join, and draws the map and the Architecture diagram from that graph. Your agents find their way by it too.

Open a project

In a terminal, from the project’s folder:

gr app open .

Or, in the app, click Open a folder… on the Welcome tab, choose Add or open a project in the command palette, or click the + beside Projects in the sidebar. The same place can clone a repository for you.

Open the top of the repository, the folder that holds .git. Graphide finds the repository’s top from any folder inside it.

Build the map

A project without a map shows This project has no graph yet on the right. Click Build the graph.

The map is built on Graphide’s servers. Before it builds anything, Graphide asks you to accept its terms and privacy policy, because the build keeps a copy of the project’s code on its servers. Choose Accept and build on that card, or run gr terms accept. Until you accept, none of your code is kept, and everything else in the app works as before. Your code and data says what is kept and how to delete it.

While it builds, the card says Building the graph and the map fills in as it goes. It takes from under a minute to a few minutes on a large repository. You do not have to wait: start an agent now, and it works while the map is built.

Once it is built, the map keeps itself current as the code changes, including changes your agents make and branches you switch to.

Cards you may see instead

The card says	Why
Waiting: you’re using N of your M builds	Your account builds a set number of maps at once. This one starts when another finishes.
Graphide’s servers are full	Every build slot is busy. Yours starts by itself.
Waiting for another init	A build of the same project is already running.
Waiting for the internet	Building needs the internet. The map already on this computer stays readable, and the build starts when the connection returns.
Waiting for approval	Your account is not activated yet. The map appears by itself once it is.
Join	The project’s map already exists in the cloud, for example because a teammate built it. Joining copies it down instead of building it again.

From the terminal

You can build and check maps without the app:

gr init          # build this project's map, with progress
gr map           # is the map of main and each worktree up to date?
gr status        # is the daemon serving this project?
gr doctor        # what is wrong, in plain words

gr init climbs to the repository’s top, like the app. It asks before it maps a very large folder, your home folder, or a folder that holds several repositories, since those are rarely what you meant. gr project new <name> makes a new, empty project in ~/Projects/<name> and runs git init in it.

gr sync brings a map back in step with the code by hand, and gr clear deletes a project’s map so gr init can build it afresh. Neither is part of normal use.

Leave parts of a project out

Graphide maps what git tracks and skips what .gitignore leaves out. To skip folders that are committed but are not your code, such as fixtures, vendored libraries or sample apps, list them in the project’s own .graphide/config.toml:

[init]
exclude = ["testdata/fixtures", "third_party", "examples"]

Paths are relative to the repository’s top, with forward slashes. A change applies at the next build.

Very large repositories

A first build of a very large repository (tens of thousands of files, or millions of lines) can use a lot of memory on your computer. If it does, exclude the folders you do not work in, as above, and build again. Your plan also caps how large a codebase it maps; see pricing.