Skip to content

Install for local development

The source code of gaslamp is publicly available on GitLab.

Bash
# Move to your workspace directory
cd ~/repos/

# Clone the repository
git clone https://gitlab.com/qumasan/gaslamp.git

# Move to the project root
cd gaslamp

# Install all dependencies (npm + uv)
task env:setup

# or without task
npm install   # Install required node packages
uv sync       # Install required python packages

Although, it is not possible to emulate the Google Apps Script (GAS) environment locally, we use TypeScript and JavaScript tools to develop and test the code on local machines.

Start a new development branch

To develop a new feature or fix a bug, create a new Git branch using git worktree:

Bash
# Create a new branch and worktree in one step
task wt:create BRANCH=new-branch-name

# Move into the new worktree
cd ../worktrees/new-branch-name
  • Use a unique but simple name for the branch.
  • The worktree is created outside the main project directory (in ../worktrees/).
  • Using a worktree ensures a safe development environment (no more stash & pop entanglement).

Working at the worktree directory

Once you've created the worktree directory, you can build and test as usual:

Bash
task env:setup   # install dependencies
task test        # run tests
task build       # type-check TypeScript (tsc --noEmit, no output files)
task bundle      # bundle for GAS (src/index.ts → gaslamp/gaslamp.bundle.js)

# or without task
npm install
npm test
npx tsc --noEmit
npm run bundle

Once you're done with your changes:

Bash
git add modified-filename
git commit  # Write a Conventional Commit message
git push

After the branch is merged, clean up the worktree:

Bash
# Move back to the project root first
cd ../../gaslamp

task wt:cleanup BRANCH=new-branch-name

Why git worktree?

We recommend using git worktree for all feature and fix development.

It allows you to work on multiple branches in parallel without switching back and forth in the same directory.

Each worktree is isolated, which helps prevent mistakes like overwriting changes or misusing git stash.

This avoids common pitfalls such as uncommitted changes, stashing, or accidental overwrites, keeping your main working tree clean and conflict-free.