Lumbermill

Ezpz management of git worktrees

• Usage
• Config Files
• Repo Config
• APFS clone: shares disk blocks with the default branch's copy until files change
• Commands

Usage

$ npm install -g @rabrennie/lumbermill

$ lm clone [email protected]:Rabrennie/lumbermill.git
Creating config file as lumbermill is being run for the first time... done
Cloning into 'main'...

Cloning repo... done
Cloned [email protected]:Rabrennie/lumbermill.git to /development/lumbermill

$ lm create user/ticket-123/testing --repo lumbermill
Created worktree for user/ticket-123/testing in /development/lumbermill/user-ticket-123-testing
Creating worktree... done
...

Config Files

Main Config

After running the lm command it will create a config file in ~/.config/lumbermill/config.json. This file keeps track of the repos and aliases managed by Lumbermill using the following format:

{
  "repos": {
    "lumbermill": "/Users/rab/development/lumbermill"
  },
  "aliases": {}
}

Repo Config

After cloning a repo with lm clone REPO [DIRECTORY] it will create a .lumbermill folder in the repos directory with a config.json file

.lumbermill/config.json

{
  "repo": "[email protected]:Rabrennie/lumbermill.git",
  "directory": "/development/lumbermill",
  "defaultBranch": "main",
}

It will also create a scripts directory where we can store custom scripts

.lumbermill/scripts/my-cool-script

echo "I am running in $(pwd)"

$ lm run my-cool-script --repo lumbermill --branch main
I am running in /Users/rab/development/lumbermill/main

$ lm run my-cool-script --repo lumbermill --branch user/ticket-123/testing
I am running in /Users/rab/development/lumbermill/user-ticket-123-testing

$ cd /Users/rab/development/lumbermill/user-ticket-123-testing/src
$ lm run my-cool-script
I am running in /Users/rab/development/lumbermill/user-ticket-123-testing

Without --branch, scripts run in the worktree you're currently in. If you're not in one, for example at the repo root, and fzf is installed, you can pick a worktree from a list instead.

Executable scripts run directly, so their shebang picks the interpreter. Other scripts run with $SHELL, or sh if it isn't set. lm run exits with the script's exit code.

Scripts run inside the worktree with these environment variables set:

| Variable | Value | | ----------------- | ------------------------------------- | | LM_ROOT | The lumbermill repo directory | | LM_MAIN_DIR | The default branch's worktree | | LM_WORKTREE_DIR | The worktree the script is running in | | LM_BRANCH | The branch name | | LM_FOLDER | The worktree's folder name |

Hooks

Scripts in .lumbermill/scripts/hooks/ run automatically:

| Hook | Runs | If it fails | | ------------- | ----------------------------------- | ---------------------------------------------------- | | post-create | In the new worktree, after lm create and lm pull | The worktree is kept, so you can fix the problem and rerun the hook | | pre-remove | In the worktree, before lm remove | The worktree is kept |

Hooks run the same way as other scripts: they get the same environment variables, and a hook that exits non-zero makes lm exit with the same code. Missing hooks are skipped.

Hooks are ordinary scripts, so you can run one by hand, for example to set up a worktree that was created before the hook existed:

$ lm run hooks/post-create --branch user/ticket-123/testing

.lumbermill/scripts/hooks/post-create

#!/bin/sh
set -e

# APFS clone: shares disk blocks with the default branch's copy until files change
cp -Rc "$LM_MAIN_DIR/node_modules" node_modules
cp "$LM_MAIN_DIR/.env" .env

.lumbermill/scripts/hooks/pre-remove

#!/bin/sh
set -e

docker compose -p "$LM_FOLDER" down -v

Commands

• lm alias delete ALIAS
• lm alias list
• lm alias set ALIAS EXPANSION
• lm clone REPO [DIRECTORY]
• lm create BRANCH
• lm pull BRANCH
• lm remove BRANCH
• lm rm BRANCH
• lm run SCRIPT

lm alias delete ALIAS

deletes an alias

USAGE
  $ lm alias delete ALIAS

ARGUMENTS
  ALIAS  alias to delete

DESCRIPTION
  deletes an alias

EXAMPLES
  $ lm alias delete

See code: src/commands/alias/delete.ts

lm alias list

lists all defined aliases

USAGE
  $ lm alias list

DESCRIPTION
  lists all defined aliases

EXAMPLES
  $ lm alias list

See code: src/commands/alias/list.ts

lm alias set ALIAS EXPANSION

defines a new alias that will expand to a command

USAGE
  $ lm alias set ALIAS EXPANSION

ARGUMENTS
  ALIAS      alias to set
  EXPANSION  expansion to set

DESCRIPTION
  defines a new alias that will expand to a command

EXAMPLES
  $ lm alias set

See code: src/commands/alias/set.ts

lm clone REPO [DIRECTORY]

Clones a repo and configures it for lumbermill

USAGE
  $ lm clone REPO [DIRECTORY]

ARGUMENTS
  REPO         repo to clone
  [DIRECTORY]  target directory

DESCRIPTION
  Clones a repo and configures it for lumbermill

EXAMPLES
  $ lm clone

See code: src/commands/clone.ts

lm create BRANCH

Creates a new worktree for a lumbermill managed repo

USAGE
  $ lm create BRANCH [--repo <value>] [--from <value>]

ARGUMENTS
  BRANCH  branch name to create

FLAGS
  --from=<value>  branch to base the new branch on, if not specified, will use the default branch after pulling it
  --repo=<value>  repo to use, if not specified, will use repo associated with the current directory

DESCRIPTION
  Creates a new worktree for a lumbermill managed repo

EXAMPLES
  $ lm create user/ticket-123/testing

  $ lm create user/ticket-123/follow-up --from user/ticket-123/testing

See code: src/commands/create.ts

lm pull BRANCH

Pulls a remote branch into a worktree

USAGE
  $ lm pull BRANCH [--repo <value>]

ARGUMENTS
  BRANCH  branch name to pull

FLAGS
  --repo=<value>  repo to use, if not specified, will use repo associated with the current directory

DESCRIPTION
  Pulls a remote branch into a worktree

EXAMPLES
  $ lm pull

See code: src/commands/pull.ts

lm remove BRANCH

Removes a worktree from a lumbermill managed repo

USAGE
  $ lm remove BRANCH [--repo <value>]

ARGUMENTS
  BRANCH  branch name to remove

FLAGS
  --repo=<value>  repo to use, if not specified, will use repo associated with the current directory

DESCRIPTION
  Removes a worktree from a lumbermill managed repo

ALIASES
  $ lm rm

EXAMPLES
  $ lm remove

See code: src/commands/remove.ts

lm rm BRANCH

Removes a worktree from a lumbermill managed repo

USAGE
  $ lm rm BRANCH [--repo <value>]

ARGUMENTS
  BRANCH  branch name to remove

FLAGS
  --repo=<value>  repo to use, if not specified, will use repo associated with the current directory

DESCRIPTION
  Removes a worktree from a lumbermill managed repo

ALIASES
  $ lm rm

EXAMPLES
  $ lm rm

lm run SCRIPT

Runs a script in a worktree

USAGE
  $ lm run SCRIPT [--repo <value>] [--branch <value>]

ARGUMENTS
  SCRIPT  file to read

FLAGS
  --branch=<value>  branch name to run script in, if not specified, will use the current worktree
  --repo=<value>    repo to use, if not specified, will use repo associated with the current directory

DESCRIPTION
  Runs a script in a worktree

EXAMPLES
  $ lm run

See code: src/commands/run.ts