# Extracting an extension to dedicated repo

These are some notes of how to extract an extension from the main zed repository and generate a new repository which preserves the history as best as possible. In the this example we will be extracting the `ruby` extension, substitute as appropriate.

## Pre-requisites

Install [git-filter-repo](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md):

```
brew install git-filter-repo
```

## Process

We are going to use a `$LANGNAME` variable for all these steps. Make sure it is set correctly.

> **Note**
> If you get `zsh: command not found: #` errors, run:
> `setopt interactive_comments && echo "setopt interactive_comments" >> ~/.zshrc`

1. Create a clean clone the zed repository, delete tags and delete branches.

```sh
LANGNAME=your_language_name_here

rm -rf $LANGNAME
git clone --single-branch --no-tags git@github.com:zed-industries/zed.git $LANGNAME
cd $LANGNAME
```

2. Create an expressions.txt file somewhere (e.g. `~/projects/$LANGNAME.txt`)

This file takes the form of `patern==>replacement`, where the replacement is optional.
Note whitespace matters so `ruby: ==>` is removing the `ruby:` prefix from a commit messages and adding a space after `==> ` means the replacement begins with a space. Regex capture groups are numbered `\1`, `\2`, etc.

See: [Git Filter Repo Docs](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html) for more.

```sh
# Create regex mapping for rewriting commit messages (edit as appropriate)
mkdir -p ~/projects
echo "${LANGNAME}: ==>
extension: ==>
chore: ==>
zed_extension_api: ==>
"'regex:(?<![\[a-zA-Z0-9])(#[0-9]{3,5})==>zed-industries/zed\1' \
  > ~/projects/${LANGNAME}.txt

# This removes the LICENSE symlink
git filter-repo --invert-paths --path extensions/$LANGNAME/LICENSE-APACHE

# This does the work
git filter-repo \
    --use-mailmap \
    --subdirectory-filter extensions/$LANGNAME/ \
    --path LICENSE-APACHE \
    --replace-message ~/projects/${LANGNAME}.txt
```

3. Review the commits.

This is your last chance to make any modifications.
If you don't fix it now, it'll be wrong forever.

For example, a previous commit message was `php/ruby: bump version to 0.0.5`
which was replaced with `php/bump version to 0.0.5`
so I added a new line to expressions.txt with `php/==>`
and next run it became `bump version to 0.0.5`.

4. [Optional] Generate tags

You can always add tags later, but it's a nice touch.

Show you all commits that mention a version number:

```sh
git log --grep="(\d+\.\d+\.\d+)" --perl-regexp --oneline --reverse
```

Then just:

```
git tag v0.0.2 abcd1234
git tag v0.0.3 deadbeef
```

Usually the initial extraction didn't mention a version number so you can just do that one manually.