# Configuration

DevKeepr works out of the box using [Stack Detection](/docs/general/features/stack-detection) to determine sensible defaults for each project. When you need to customize behavior, you can start with global defaults that apply everywhere, then override specific projects through the app or a sharable YAML file.

## Global Hibernation Defaults

Open the **Hibernation** panel in the sidebar to configure defaults that apply to all your projects at once. From here you can enable automatic hibernation, set a default schedule, and toggle automatic wake globally.

Global defaults cover `autoWake` and `hibernateSchedule` only. Hibernate and wake commands are always determined per project from [Stack Detection](/docs/general/features/stack-detection), since every project has a different stack.

![Global hibernation defaults in the Hibernation panel](/screenshots/docs/global-hibernation-settings.webp)

See [Smart Hibernation](/docs/general/features/hibernation) for more on how automatic hibernation works.

## Per-Project Configuration

When a project needs different settings, you can override the global defaults from its detail panel or through a config file. Per-project settings always take precedence.

### Hibernation

Open any project in DevKeepr and you'll find its configuration in the detail panel. From here you can toggle automatic wake, set a hibernation schedule, and edit hibernate and wake commands. Changes are saved to the project's `devkeepr.yaml` file automatically.

![Project configuration in the detail panel](/screenshots/docs/project-hibernation-settings.webp)

The hibernate and wake command lists are prefilled with defaults from the detected stack. Click the options button in the Hibernation Settings panel to view and edit them. You can customize the commands to fit your project's needs, for example adding build output directories, extra cache locations, or project-specific cleanup steps. If you want to start over, you can reset either list back to the stack defaults at any time.

### Git Sync

The `syncUpstream` and `mergeBase` options keep your branches up to date automatically. Both are triggered by editor activity or git pull events and only run when the working directory is clean.

**Sync upstream** pulls changes from the remote branch your current branch follows. It prefers a fast-forward merge and falls back to a merge commit when branches have diverged.

**Merge base** merges the base branch (typically `main`) into your current working branch. This keeps long-running feature branches up to date without manual rebasing.

Both options send a desktop notification on success or when a conflict needs manual resolution. Git sync settings are only available for projects where the Git stack is detected.

<p style="text-align: center;">
  <img src="/screenshots/docs/git-sync.webp" alt="Git sync settings in the project detail panel" style="max-width: 500px; width: 100%; margin: 1.5rem auto 0; border-radius: 8px;">
</p>

## The `devkeepr.yaml` File

Every project can have a `devkeepr.yaml` (or `devkeepr.yml`) file in its root directory. This file is meant to be committed to version control so your team shares the same configuration.

The file supports a `$schema` reference for autocompletion and validation in your editor:

```yaml
$schema: https://devkeepr.app/schema.json
```

### Configuration Reference

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `autoWake` | `boolean` | `false` | Wake the project automatically when editor activity or a git operation is detected |
| `hibernateSchedule` | `string\|null` | `null` | Automatic hibernation schedule: `weekly`, `monthly`, `quarterly`, or `null` to disable |
| `hibernateCommands` | `string[]\|null` | stack defaults | Commands to run when the project hibernates |
| `wakeCommands` | `string[]\|null` | stack defaults | Commands to run when the project wakes |
| `syncUpstream` | `boolean` | `false` | Auto-merge the tracking branch into the current branch when activity is detected |
| `mergeBase` | `boolean` | `false` | Auto-merge the base branch (e.g. main) into the current working branch when activity is detected |

When `hibernateCommands` or `wakeCommands` are `null`, DevKeepr uses the defaults generated by [Stack Detection](/docs/general/features/stack-detection). Setting them explicitly overrides those defaults. You can reset to the detected defaults from the project detail panel at any time.

### Full Example

```yaml
$schema: https://devkeepr.app/schema.json

# Hibernation
autoWake: true
hibernateSchedule: monthly
hibernateCommands:
  - php artisan optimize:clear
  - rm -rf ./vendor
  - rm -rf ./node_modules
wakeCommands:
  - composer install
  - npm install
  - php artisan view:cache

# Git sync
syncUpstream: true
mergeBase: false
```