From 12d98507d59d2875fed1846fb6a0a3f5a555fec9 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Wed, 11 Jun 2025 16:05:37 -0400
Subject: [PATCH] Docs: Goose now respects gitignore files (#2858)

Co-authored-by: dianed-square <73617011+dianed-square@users.noreply.github.com>
---
 .../docs/guides/using-gooseignore.md          | 64 ++++++++++++-------
 1 file changed, 40 insertions(+), 24 deletions(-)

diff --git a/documentation/docs/guides/using-gooseignore.md b/documentation/docs/guides/using-gooseignore.md
index 8c58de4a..fb526b7a 100644
--- a/documentation/docs/guides/using-gooseignore.md
+++ b/documentation/docs/guides/using-gooseignore.md
@@ -23,24 +23,6 @@ Goose supports two types of `.gooseignore` files:
 You can use both global and local `.gooseignore` files simultaneously. When both exist, Goose will combine the restrictions from both files to determine which paths are restricted.
 :::
 
-## Automatic `.gitignore` fallback
-
-If no `.gooseignore` file is found in your current directory, Goose will automatically use your `.gitignore` file as a fallback. This means:
-
-1. **Priority Order**: Goose checks for ignore patterns in this order:
-   - Global `.gooseignore` (if exists)
-   - Local `.gooseignore` (if exists)
-   - Local `.gitignore` (if no local `.gooseignore` and `.gitignore` exists)
-   - Default patterns (if none of the above exist)
-
-2. **Seamless Integration**: Projects with existing `.gitignore` files get automatic protection without needing a separate `.gooseignore` file.
-
-3. **Override Capability**: Creating a local `.gooseignore` file will completely override `.gitignore` patterns for that directory.
-
-:::info Debug logging
-When Goose uses `.gitignore` as a fallback, it will log a message to help you understand which ignore file is being used.
-:::
-
 ## Example `.gooseignore` file
 
 In your `.gooseignore` file, you can write patterns to match files you want Goose to ignore. Here are some common patterns:
@@ -65,18 +47,53 @@ downloads/           # Ignore everything in the "downloads" directory
 !error.log           # Except for error.log file
 ```
 
-## Default patterns
+## Ignore File Types and Priority
+Goose respects ignore rules from three sources: global `.gooseignore`, local `.gooseignore`, and `.gitignore`. It uses a priority system to determine which files should be ignored. 
 
-By default, if you haven't created any `.gooseignore` files **and no `.gitignore` file exists**, Goose will not modify files matching these patterns:
+### 1. Global `.gooseignore`
+- Highest priority and always applied first
+- Located at `~/.config/goose/.gooseignore`
+- Affects all projects on your machine
 
+```
+~/.config/goose/
+└── .gooseignore      ← Applied to all projects
+```
+
+### 2. Local `.gooseignore`
+- Project-specific rules
+- Located in your project root directory
+- Overrides `.gitignore` completely
+
+```
+~/.config/goose/
+└── .gooseignore      ← Global rules applied first
+
+Project/
+├── .gooseignore      ← Local rules applied second
+├── .gitignore        ← Ignored when .gooseignore exists
+└── src/
+```
+
+### 3. `.gitignore` Fallback
+- Used when no local `.gooseignore` exists
+- Goose automatically uses your `.gitignore` rules
+- If a global `.gooseignore` file exists, those rules will be applied in addition to the `.gitignore` patterns.
+
+```
+Project/
+├── .gitignore        ← Used by Goose (when no local .gooseignore)
+└── src/
+```
+
+### 4. Default Patterns
+By default, if you haven't created any .gooseignore files and no .gitignore file exists, Goose will not modify files matching these patterns:
 ```plaintext
 **/.env
 **/.env.*
 **/secrets.*
 ```
 
-These default patterns only apply when neither `.gooseignore` nor `.gitignore` files are found in your project.
-
 ## Common use cases
 
 Here are some typical scenarios where `.gooseignore` is helpful:
@@ -86,5 +103,4 @@ Here are some typical scenarios where `.gooseignore` is helpful:
 - **Important Configurations**: Protect critical configuration files from accidental modifications
 - **Version Control**: Prevent changes to version control files like `.git` directory
 - **Existing Projects**: Most projects already have `.gitignore` files that work automatically as ignore patterns for Goose
-- **Custom Restrictions**: Create `.gooseignore` when you need different patterns than your `.gitignore` (e.g., allowing Goose to read files that Git ignores)
-
+- **Custom Restrictions**: Create `.gooseignore` when you need different patterns than your `.gitignore` (e.g., allowing Goose to read files that Git ignores)
\ No newline at end of file