---
title: "Connect a Git Repository"
sidebarTitle: "Connect Project"
description: "Link your local Git repository to deeepSpace using deeep init. Detect your frontend framework, configure discovery globs, and generate deeep.json."
keywords: "deeep init, connect git repository, link deeepspace project, deeep.json setup"
icon: "plug"
---

After installing and authenticating the CLI, link your local Git repository to a deeepSpace project. This connection lets you sync your local components with your design system in deeepSpace.

## Prerequisites

Before connecting, make sure you have:

- [Installed](/guides/installation) the deeep CLI
- [Authenticated](/guides/authentication) with your deeepSpace account
- A Git repository whose remote matches the repository connected to the selected project
- A matching project in deeepSpace, or permission to create one

<Note>
**New to deeepSpace?** If you haven't created a project yet, visit [app.deeepspace.com](https://app.deeepspace.com) to create one, or use `deeep init --create` to create a project directly from the current repository.
</Note>

## Initialize the project

Navigate to your project's root directory and run:

<Tip>
**Run from the repository root:** the CLI reads and writes `deeep.json` in the current directory. Creating a project requires an `origin` remote on GitHub, GitLab, or Bitbucket and the corresponding Git-provider connection in deeepSpace.
</Tip>

```bash
deeep init
```

The command runs through four steps:

<Steps>
  <Step title="Choose a workspace">
    Select the deeepSpace workspace to use.
  </Step>
  <Step title="Choose or create a project">
    Link an existing project or create a new one from this repository.
  </Step>
  <Step title="Configure component discovery">
    Choose between CLI discovery and Storybook discovery.
  </Step>
  <Step title="Review and save">
    Confirm the configuration before `deeep.json` is written.
  </Step>
</Steps>

After confirmation, `init` records your chosen discovery method on deeepSpace and attempts the first component sync. Prepare committed component sources and a named branch as described in [Sync components](/guides/sync). It then detects your tech stack and asks whether to update project settings.

If indexing or syncing fails, the project configuration is saved so you can fix the issue and retry with `deeep sync`. Setup registration is separate from component sync: the Home tab can show the selected method even before a successful sync. If registration fails, local setup continues with a warning; use `deeep init --force` to retry setup for an initialized project.

### Create a new project

To skip only the create/link selection prompt and create a new deeepSpace project from the current repository:

```bash
deeep init --create
```

`--create` still asks for the workspace, project name, optional description, discovery settings, and confirmation. A blank project name defaults to the repository directory name. Supported remote forms include `https://github.com/owner/repo.git` and `git@github.com:owner/repo.git`, with equivalent GitLab and Bitbucket URLs. Nested GitLab subgroup paths and `ssh://` URLs are not supported by the current project-creation parser.

### Reconnect to a different project

To change the linked project or update discovery settings:

```bash
deeep init --force
```

---

## Component discovery

During initialization you choose how the CLI finds your components.

### deeep CLI discovery

The CLI scans directories that contain component source files, for example:

```text
src/components/**/*.{js,jsx,mjs,ts,tsx,vue}
packages/*/src/components/**/*.{js,jsx,mjs,ts,tsx,vue}
```

You can confirm, select, or manually enter the directories to scan.

### Storybook discovery

If Storybook is detected, you can choose to use your Storybook stories and `index.json` instead. The CLI will ask for:

- The `.storybook` configuration directory
- The path to the generated Storybook `index.json`
- The story file glob patterns
- An optional deployed Storybook URL
- Whether to host Storybook on deeep during sync

See [Storybook discovery and hosting](/guides/storybook) for monorepos, the required first build, and publishing behavior. Enabling hosting during `init` saves the preference; publishing runs on `deeep sync`.

---

## Configuration file

After linking, the CLI creates a `deeep.json` file in your repository root. This file contains the project link, project settings, and discovery configuration.

```json
{
  "project": {
    "name": "My Awesome Project",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "projectSettings": {
      "framework": "react",
      "language": "tsx",
      "styling": "tailwind",
      "styleMode": "external"
    },
    "gitRepoName": "my-org/my-awesome-project",
    "gitRepoUrl": "https://github.com/my-org/my-awesome-project",
    "version": 1
  },
  "discovery": {
    "type": "CLI",
    "componentIndexJsonPath": ".deeep.index.json",
    "components": [
      "src/components/**/*.{js,jsx,mjs,ts,tsx,vue}"
    ],
    "exclude": [
      "**/*.test.*",
      "**/*.spec.*",
      "**/*.stories.*",
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/coverage/**"
    ]
  }
}
```

For a full reference of all available options, visit the [Project Settings Reference](/reference/project-settings) page.

---

## Check connection status

Verify your project connection:

```bash
deeep status
```

Example output:

```text
Project Status
==================================================

Project Name: My Project
Workspace: Default Space

Project Settings
──────────────────────────────
Framework:   react
Styling:     tailwind
Language:    tsx
Style Mode:  external

Version Information
──────────────────────────────
Current Version: 1

==================================================
```

---

## Remove the local link

To detach this repository from its deeepSpace project — for example before archiving or handing off a codebase — run:

```bash
deeep unlink
```

The command asks for confirmation, then deletes `deeep.json` and the generated component index (`.deeep.index.json`, or your configured `componentIndexJsonPath`) from the repository. Everything in deeepSpace stays intact: the project, its synced components, and the connected repository are untouched. Add `--logout` to also clear the stored credentials from the machine, and `-y` to skip the confirmation prompt.

<Note>To permanently delete the project or disconnect its repository, use the deeepspace web app. `deeep unlink` only cleans the local codebase — you can link the repository again at any time with `deeep init`.</Note>

---

## Troubleshooting

### Project not found
- Verify you're in the correct directory.
- Check that you're logged in with the correct account (`deeep whoami`).
- Ensure the project exists in deeepSpace.

### Git repository required
- `deeep init` must be run from inside a Git repository.
- Creating a project requires a supported `origin` remote. Syncing an existing project requires a local remote matching its connected repository name.

### Git provider connection required
- Connect your Git provider account in deeepSpace before linking a repository.

### Configuration errors
- For valid configuration that needs changes, run `deeep init --force`.
- For malformed JSON, repair the file or back it up outside the repository before removing it and running `deeep init` again. Configuration is loaded before command handling, so `--force` cannot bypass invalid JSON. To remove the local link entirely, run `deeep unlink` instead of deleting the file by hand.
- If issues persist, contact [support@deeepspace.com](mailto:support@deeepspace.com) for help.

---

## Next steps

Now that your project is connected:

1. [Sync components](/guides/sync) with deeepSpace
2. Learn how to manage your [project settings](/reference/project-settings)