---
title: changelog init
description: Initialize changelog configuration and folder structure for a repository. If a docs folder that contains docset.yml exists (in the repository root or...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/cli/changelog/init
products:
  - Elastic Docs Builder
---

# changelog init
Initialize changelog configuration and folder structure for a repository.
If a docs folder that contains `docset.yml` exists (in the repository root or `docs/` directory), the command uses that folder.
If a `docs` folder exists without `docset.yml`, the command uses it.
If no docs folder exists, the command creates `{path}/docs` and places `changelog.yml` there.
The command creates a `changelog.yml` configuration file (from the built-in template) and `changelog` and `releases` subdirectories in the `docs` folder.
When `--changelog-dir` or `--bundles-dir` is specified, the corresponding `bundle.directory` and `bundle.output_directory` values in `changelog.yml` are set or updated (whether creating a new file or the file already exists).
When the template is written for the first time, the command can **seed** `bundle.owner`, `bundle.repo`, and `bundle.link_allow_repos` so PR and issue links resolve under the explicit link allowlist in [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) (there is no implicit allow for your own repository). Seeding runs when `git` remote `origin` points at **github.com** and/or when you pass `--owner` and/or `--repo`. CLI values override values inferred from `git`. If you pass `--repo` without `--owner` and `git` does not supply an owner, the owner defaults to `elastic`. If neither `git` nor CLI provides enough information, the placeholder line is removed from the template and you can set bundle fields manually.

## Usage

```sh
docs-builder changelog init [options...] [-h|--help]
```


## Options

<definitions>
  <definition term="--path <string?>">
    Optional: Repository root path.
  </definition>
  <definition term="Defaults to the output of pwd (current directory). The docs folder is {path}/docs, created if it does not exist.">
  </definition>
  <definition term="--changelog-dir <string?>">
    Optional: Path to the changelog directory.
  </definition>
  <definition term="Defaults to {docsFolder}/changelog.">
  </definition>
  <definition term="--bundles-dir <string?>">
    Optional: Path to the bundles output directory.
  </definition>
  <definition term="Defaults to {docsFolder}/releases.">
  </definition>
  <definition term="--owner <string?>">
    Optional: GitHub organization or user for `bundle.owner` and for seeding `bundle.link_allow_repos` when creating `changelog.yml`. Overrides the owner parsed from `git` remote `origin`.
  </definition>
  <definition term="--repo <string?>">
    Optional: GitHub repository name for `bundle.repo` and for seeding `bundle.link_allow_repos` when creating `changelog.yml`. Overrides the repository name parsed from `git` remote `origin`.
  </definition>
</definitions>


## Examples

Initialize changelog (creates or uses docs folder, places `changelog.yml` there, plus `changelog` and `releases` subdirectories):
```sh
docs-builder changelog init
```

Initialize when run from a subdirectory, specifying the root path:
```sh
docs-builder changelog init --path /path/to/my-repo
```

Use custom changelog and bundles directories.
Sets or updates `bundle.directory` and `bundle.output_directory` in `changelog.yml` (creating the file if it does not exist):
```sh
docs-builder changelog init \
  --changelog-dir ./my-changelogs \
  --bundles-dir ./my-releases
```

Initialize without relying on `git` (for example in a clean checkout or CI), setting the GitHub owner and repository used to seed bundle defaults and `link_allow_repos`:
```sh
docs-builder changelog init --owner elastic --repo kibana
```