gitbutler Documentation

File: README.md Copy Chapter

GitButler is a powerful new Git-based version control system, designed from scratch to be simple, powerful and flexible. It is designed for ease of use and modern agentic workflows.

It features stacked branches, parallel branches, unlimited undo, easy commit mutations, forge integrations and more.

Works instantly in any existing Git repo as a friendlier and more powerful drop-in Git user interface replacement - for you and your agents.

Main Features Copy Chapter

Why use GitButler instead of vanilla Git? What a great question.

• Stacked Branches (gui, cli)
  • Effortlessly create branches stacked on other branches. Amend or edit any commit easily with automatic restacking.
• Parallel Branches (gui, cli)
  • Organize work on multiple branches simultaneously, rather than constantly switching branches.
• Easy Commit Management (gui, cli)
  • Uncommit, reword, amend, move, split and squash commits by dragging and dropping or simple CLI commands. Forget about rebase -i, you don't need it anymore.
• Undo Timeline (gui, cli)
  • Logs all operations and changes and allows you to easily undo or revert any operation.
• First Class Conflicts (gui, cli)
  • Rebases always succeed. Commits can be marked as conflicted and resolved at any time, in any order.
• Forge Integration (gui, cli)
  • Authenticate to GitHub, GitLab, or Bitbucket to easily open and update Pull Requests, list branches, get CI statuses and more. No other tools required.
• AI Tooling (gui, cli)
  • Use built-in AI handlers to help create commit messages, branch names, PR descriptions and more.
  • Easily install hooks or skills for all modern agent systems to level up their Git management.

Tech Copy Chapter

The GitButler desktop app is a Tauri-based application. Its UI is written in Svelte using TypeScript and its backend is written in Rust.

The but CLI is the same Rust backend engine with a Rust command line UI.

Documentation Copy Chapter

You can find our end user documentation at: https://docs.gitbutler.com

Bugs and Feature Requests Copy Chapter

If you have a bug or feature request, feel free to open an issue,
or join our Discord server.

License Copy Chapter

The TLDR is that GitButler is under a Fair Source software license, meaning that you can use it, view the source, contribute, etc. You just can't build a competitor with it. It also becomes MIT after 2 years. So, MIT with an expiring non-compete clause.

Contributing Copy Chapter

So you want to help out? Please check out the CONTRIBUTING.md
document.

If you want to skip right to getting the code to actually compile, take a look
at the DEVELOPMENT.md file.

Contributors Copy Section

File: packages/ui/src/stories/docs/introduction.mdx Copy Chapter

import { Meta } from "@storybook/addon-docs/blocks";

🤖 Welcome to GitButler UI

Welcome to the GitButler UI Storybook. This is a collection of components that are used to build the GitButler UI. Here you can see all the components that are available and how they can be used.

📚 How to install Copy Chapter

Because the GitButler UI is a part of a monorepo, you can use the components by adding the package to your package.json file.

"@gitbutler/ui": "workspace:*",

Then import the package styles in your project:

@import "@gitbutler/ui/main.css";

This single import automatically includes:

• All UI component styles
• All font definitions (@font-face rules)
• Font file assets (Inter, Geist Mono, PP Editorial New)
• CSS custom properties for fonts

🔤 Font System Copy Section

The UI package uses a centralized font system. Once you import main.css, you can use these font families:

font-family: var(--fonts-inter); /* Primary UI font */
font-family: var(--fonts-geist-mono); /* Code/monospace font */
font-family: var(--fonts-pp-editorial); /* Display/heading font */

Available fonts:

• Inter: Regular, Medium, SemiBold, Bold (+ Italic versions)
• Geist Mono: Regular, Medium, Bold
• PP Editorial New: Regular

No additional font imports needed - everything is included in the single CSS import!

📦 Packing styles Copy Chapter

In order to pack the styles, we use PostCSS. The PostCSS configuration is located in the postcss.config.js file.

const config = {
	plugins: [
		pxToRem({
			rootValue: 16,
			unitPrecision: 5,
			propList: ["*"],
			selectorBlackList: [],
			replace: true,
			mediaQuery: false,
			minPixelValue: 0,
		}),
		autoprefixer(),
		postcssNesting(),
		postcssBundler(),
		postcssMinify(),
	],
};

File: packages/shared/README.md Copy Chapter

create-svelte

Everything you need to build a Svelte library, powered by create-svelte.

Read more about creating a library in the docs.

Creating a project Copy Chapter

If you're seeing this, you've probably already done this step. Congrats!

# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app

Developing Copy Chapter

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a development server:

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Everything inside src/lib is part of your library, everything inside src/routes can be used as a showcase or preview app.

Building Copy Chapter

To build your library:

npm run package

To create a production version of your showcase app:

npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target environment.

Publishing Copy Chapter

Go into the package.json and give your package the desired name through the "name" option. Also consider adding a "license" field and point it to a LICENSE file which you can create from a template (one popular option is the MIT license).

To publish your library to npm:

npm publish

File: packages/no-relative-imports/README.md Copy Chapter

@gitbutler/no-relative-imports

An eslint rule for enforcing non-relative imports if there are paths in your tsconfig.json available to you.

What the rule affects Copy Chapter

The rule requires that any import that could be referenced absolutely via an entry in paths will provide an error.

Even if a sibling import (IE ./foo) is used, if it could be accessed via a path (IE $lib/foo). An error will be provided.

The `paths` format Copy Chapter

It should be noted that the current implementation does not try to handle all the possible paths entries. Instead it handles the three common cases:

{
	"compilerOptions": {
		"paths": {
			"$lib": "./lib", // Without glob. IE pointing directly to a file
			"$lib/*": "./lib/*", // Both with glob, IE anything starting in ./lib/... results in $lib/...
			"$lib": "./lib/*" // Path with, IE anything starting in ./lib/... results in $lib
		}
	}
}

Usage Copy Chapter

import noRelativeImportPaths from '@gitbutler/no-relative-imports';

export default [
  {
    plugins: {
      'no-relative-import-paths': noRelativeImportPaths,
    },
    rules: {
      'no-relative-import-paths/no-relative-import-paths': 'error',
    },
  },
]