From 881e5b1c190791962a303ffdfd124a4e32c6d042 Mon Sep 17 00:00:00 2001 From: Ali Nazzal Date: Wed, 13 Aug 2025 02:51:30 +0300 Subject: [PATCH 1/4] docs: add troubleshooting section to DEVELOPMENT.md - Add comprehensive troubleshooting section between Debugging and Building - Include solutions for case-sensitive volume issues with Turbo - Add Turbo daemon fixes and cache clearing procedures - Cover platform-specific issues and Node.js/pnpm problems - Provide links to toolchain-specific GitHub issues - Update Table of Contents with new section Addresses #5025 --- DEVELOPMENT.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index bfc6ad9de0..0e5c7015af 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -16,6 +16,7 @@ you right. Let's get started. - [Debugging](#debugging) - [Logs](#logs) - [Tokio](#tokio) +- [Troubleshooting](#troubleshooting) - [Building](#building) - [Building on Windows](#building-on-windows) - [File permissions](#file-permissions) @@ -222,6 +223,115 @@ We are also collecting tokio's runtime tracing information that could be viewed --- +## Troubleshooting + +Common issues and solutions when developing GitButler. + +### Turbo/Build Issues + +### Case-sensitive volume problems + +If you're experiencing issues with the `dev:desktop` target failing to start, especially on macOS with case-sensitive filesystems, this may be related to Turborepo's handling of case-sensitive volumes. + +**Solution:** See the related issue at [vercel/turborepo#8491](https://github.com/vercel/turborepo/issues/8491) for current workarounds. + +#### Turbo daemon issues + +If builds are hanging or behaving unexpectedly: + +```bash +# Stop the turbo daemon +$ pnpm exec turbo daemon stop + +# Clear turbo cache +$ pnpm exec turbo daemon clean + +# Restart development +$ pnpm dev:desktop +``` + +### Cache Issues + +If you're seeing stale builds or unexpected behavior: + +```bash +# Clear all caches +$ pnpm clean +$ cargo clean +$ rm -rf node_modules +$ pnpm install +``` + +### Platform-specific Issues + +For Windows-specific build issues, refer to the [Building on Windows](#building-on-windows) section. Common issues include: + +- Missing Perl interpreter for OpenSSL compilation +- Incorrect npm prefix configuration +- File permission issues with pnpm + +#### macOS + +- Ensure Xcode Command Line Tools are installed: `xcode-select --install` +- If using Homebrew, ensure cmake is installed: `brew install cmake` + +#### Linux + +- Double-check all system dependencies are installed (see Prerequisites) +- On some distributions, you may need additional development packages + +### Node.js and pnpm Issues + +#### pnpm installation failures + +```bash +# Disable and re-enable corepack +$ corepack disable +$ corepack enable + +# Or install pnpm globally +$ npm install -g pnpm +``` + +#### Node version conflicts + +Ensure you're using Node 20+. If using a version manager like nvm: + +```bash +$ nvm use 20 +$ nvm alias default 20 +``` + +### Rust Issues + +#### Cargo build failures + +```bash +# Update Rust toolchain +$ rustup update + +# Clean and rebuild +$ cargo clean +$ cargo build +``` + +#### Missing system dependencies + +On Linux, if you're getting linking errors, ensure all required system libraries are installed. Revisit the Prerequisites section for your distribution. + +### Additional Resources + +For issues specific to our toolchain components: + +- [Turborepo Issues](https://github.com/vercel/turborepo/issues) +- [Tauri Issues](https://github.com/tauri-apps/tauri/issues) +- [Svelte Issues](https://github.com/sveltejs/svelte/issues) +- [Rust Issues](https://github.com/rust-lang/rust/issues) + +If none of these solutions work, please check our [GitHub Issues](https://github.com/gitbutlerapp/gitbutler/issues) or create a new issue with detailed information about your system and the error you're encountering. + +--- + ## Building To build the app in production mode, run: From 434a9e31ff54b256028baabf922b5d0592b1a96d Mon Sep 17 00:00:00 2001 From: Ali Nazzal Date: Wed, 13 Aug 2025 03:09:35 +0300 Subject: [PATCH 2/4] docs: add troubleshooting section to DEVELOPMENT.md - Add comprehensive troubleshooting section between Debugging and Building - Include solutions for case-sensitive volume issues with Turbo - Add Turbo daemon fixes and cache clearing procedures - Cover platform-specific issues and Node.js/pnpm problems - Provide links to toolchain-specific GitHub issues - Update Table of Contents with new section Addresses #5025 --- DEVELOPMENT.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0e5c7015af..f39100721d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -295,11 +295,12 @@ $ npm install -g pnpm #### Node version conflicts -Ensure you're using Node 20+. If using a version manager like nvm: +Use the Node version pinned by `.nvmrc` (currently LTS “jod” / Node 22): ```bash -$ nvm use 20 -$ nvm alias default 20 +nvm install +nvm use +node -v ``` ### Rust Issues From a90ada0b0f8f29b979e1a1f2bcbaedbe62f080fb Mon Sep 17 00:00:00 2001 From: Ali Nazzal <89179776+ali90h@users.noreply.github.com> Date: Wed, 13 Aug 2025 12:52:55 +0300 Subject: [PATCH 3/4] Update DEVELOPMENT.md Co-authored-by: Sebastian Thiel --- DEVELOPMENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index f39100721d..af28563ee4 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -229,7 +229,7 @@ Common issues and solutions when developing GitButler. ### Turbo/Build Issues -### Case-sensitive volume problems +#### Case-sensitive volume problems If you're experiencing issues with the `dev:desktop` target failing to start, especially on macOS with case-sensitive filesystems, this may be related to Turborepo's handling of case-sensitive volumes. From 6b59b47d0cb67da6121bea5ea85dfcc7c5a57c8b Mon Sep 17 00:00:00 2001 From: Ali Nazzal Date: Wed, 13 Aug 2025 13:30:59 +0300 Subject: [PATCH 4/4] docs(dev): normalize heading case --- DEVELOPMENT.md | 78 ++++++++++++-------------------------------------- 1 file changed, 18 insertions(+), 60 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index af28563ee4..e0e06d5c60 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -227,7 +227,7 @@ We are also collecting tokio's runtime tracing information that could be viewed Common issues and solutions when developing GitButler. -### Turbo/Build Issues +### Turbo/build issues #### Case-sensitive volume problems @@ -241,59 +241,27 @@ If builds are hanging or behaving unexpectedly: ```bash # Stop the turbo daemon -$ pnpm exec turbo daemon stop +pnpm exec turbo daemon stop # Clear turbo cache -$ pnpm exec turbo daemon clean +pnpm exec turbo daemon clean # Restart development -$ pnpm dev:desktop +pnpm dev:desktop ``` -### Cache Issues +### Cache issues If you're seeing stale builds or unexpected behavior: ```bash -# Clear all caches -$ pnpm clean -$ cargo clean -$ rm -rf node_modules -$ pnpm install -``` - -### Platform-specific Issues - -For Windows-specific build issues, refer to the [Building on Windows](#building-on-windows) section. Common issues include: - -- Missing Perl interpreter for OpenSSL compilation -- Incorrect npm prefix configuration -- File permission issues with pnpm - -#### macOS - -- Ensure Xcode Command Line Tools are installed: `xcode-select --install` -- If using Homebrew, ensure cmake is installed: `brew install cmake` - -#### Linux - -- Double-check all system dependencies are installed (see Prerequisites) -- On some distributions, you may need additional development packages - -### Node.js and pnpm Issues - -#### pnpm installation failures - -```bash -# Disable and re-enable corepack -$ corepack disable -$ corepack enable - -# Or install pnpm globally -$ npm install -g pnpm +rm -rf .turbo node_modules +pnpm install +# Optional (Rust artifacts): +cargo clean ``` -#### Node version conflicts +### Node.js & pnpm Use the Node version pinned by `.nvmrc` (currently LTS “jod” / Node 22): @@ -303,31 +271,21 @@ nvm use node -v ``` -### Rust Issues - -#### Cargo build failures +Use pnpm via Corepack (avoid global installs): ```bash -# Update Rust toolchain -$ rustup update - -# Clean and rebuild -$ cargo clean -$ cargo build +corepack enable +corepack pnpm -v +# optionally pin a major: +corepack prepare pnpm@10 --activate ``` -#### Missing system dependencies - -On Linux, if you're getting linking errors, ensure all required system libraries are installed. Revisit the Prerequisites section for your distribution. - -### Additional Resources +### Additional resources For issues specific to our toolchain components: -- [Turborepo Issues](https://github.com/vercel/turborepo/issues) -- [Tauri Issues](https://github.com/tauri-apps/tauri/issues) -- [Svelte Issues](https://github.com/sveltejs/svelte/issues) -- [Rust Issues](https://github.com/rust-lang/rust/issues) +- [Turborepo issues](https://github.com/vercel/turborepo/issues) +- [Tauri issues](https://github.com/tauri-apps/tauri/issues) If none of these solutions work, please check our [GitHub Issues](https://github.com/gitbutlerapp/gitbutler/issues) or create a new issue with detailed information about your system and the error you're encountering.