Skip to content

feat: rename /directory to /workspace and unify terminology (v2)#20774

Closed
keithguerin wants to merge 11 commits into
mainfrom
rename-directory-to-workspace
Closed

feat: rename /directory to /workspace and unify terminology (v2)#20774
keithguerin wants to merge 11 commits into
mainfrom
rename-directory-to-workspace

Conversation

@keithguerin

@keithguerin keithguerin commented Mar 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Rename the /directory command to /workspace and standardize on 'workspace' terminology (instead of 'project') across the CLI, UI, MCP, settings, and prompts.

Details

  • Renamed /directory and /dir to /workspace, keeping old names as aliases for backward compatibility.
  • Updated all user-facing strings in packages/cli and packages/core to use "workspace" terminology.
  • Standardized internal symbols and types (e.g., workspaceHash instead of projectHash).
  • Updated prompt snippets and context tags to reflect the terminology change.
  • Fixed numerous test failures in packages/cli caused by snapshot mismatches, terminology updates, and missing custom matchers.
  • Resolved ESLint issues in tests.
  • Updated documentation in docs/.
  • Preserved 'project' terminology only for GCP-related strings (e.g., projectId).

Per Core/UX chat on 2/18.

Related Issues

Linked to #20737

How to Validate

  1. Run npm run start
  2. Try /workspace and verify it shows the workspace status.
  3. Try /directory and /dir and verify they still work as aliases.
  4. Verify the prompt headers and context tags use "Workspace" instead of "Project".
  5. Run npm run test across the monorepo to ensure all fixes are passing.

Pre-Merge Checklist

  • Updated relevant documentation and README (if needed)
  • Added/updated tests (if needed)
  • Noted breaking changes (if any)
  • Validated on required platforms/methods:
    • MacOS
      • npm run
      • npx

Renames the /directory command to /workspace, adds aliases for backward compatibility, and updates UI strings, settings, and prompts to use 'workspace' terminology consistently.

Linked to #20737. Per Core/UX chat on 2/18.
@keithguerin keithguerin requested review from a team as code owners March 1, 2026 17:17
@gemini-cli

gemini-cli Bot commented Mar 1, 2026

Copy link
Copy Markdown
Contributor

Hi @keithguerin, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

@github-actions

github-actions Bot commented Mar 1, 2026

Copy link
Copy Markdown

You already have 7 pull requests open. Please work on getting existing PRs merged before opening more.

@github-actions github-actions Bot closed this Mar 1, 2026
@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant terminology refactor, standardizing the use of 'workspace' in place of 'directory' and 'project' throughout the application. This change aims to improve conceptual clarity and consistency, particularly in how users interact with commands, configure settings, and understand the scope of operations within the CLI. The update encompasses command names, configuration files, internal APIs, and all relevant documentation and user interface elements, ensuring a cohesive user experience.

Highlights

  • Terminology Unification: The terms 'directory' and 'project' have been consistently renamed to 'workspace' across the codebase and documentation to unify terminology.
  • Command Renaming: The /directory command has been renamed to /workspace, with /directory and /dir now serving as aliases for backward compatibility.
  • Configuration Scope Update: Configuration options and settings previously scoped to 'project' now use 'workspace' as the primary term, including default scopes for MCP commands and settings files.
  • Internal API Refactoring: Numerous internal functions and interfaces, such as getProjectRoot, projectHash, and projectHooks, have been renamed to their 'workspace' equivalents (e.g., getWorkspaceRoot, workspaceHash, workspaceHooks) with deprecation warnings for older names to ensure a smooth transition.
  • Documentation and UI Updates: All user-facing documentation, UI elements, and system prompts have been updated to reflect the new 'workspace' terminology, enhancing clarity and consistency for users.
Changelog
  • docs/reference/commands.md
    • Updated command documentation to reflect /workspace command and unified terminology.
    • Renamed /directory command to /workspace and added /dir, /directory as aliases.
    • Changed references from 'project-level' to 'workspace-level' for command definitions.
    • Updated /restore command description to refer to 'workspace files'.
  • docs/reference/configuration.md
    • Updated configuration documentation to use 'workspace' terminology consistently.
    • Replaced 'Project settings file' with 'Workspace settings file' in settings hierarchy and descriptions.
    • Changed 'The .gemini directory in your project' heading to 'The .gemini directory in your workspace'.
    • Updated shell history location description from <project_hash> to <workspace_hash>.
  • packages/cli/src/commands/mcp/add.ts
    • Updated MCP add command to support 'workspace' scope and made it the default.
    • Modified scope check to include 'workspace' alongside 'project'.
    • Changed default scope option from 'project' to 'workspace' and added 'workspace' to choices.
  • packages/cli/src/commands/mcp/remove.test.ts
    • Updated test assertions for MCP remove command to reflect new terminology, changing 'project settings' to 'workspace settings'.
  • packages/cli/src/commands/mcp/remove.ts
    • Updated MCP remove command to support 'workspace' scope and made it the default.
    • Changed default scope option from 'project' to 'workspace' and added 'workspace' to choices.
  • packages/cli/src/config/config.ts
    • Updated CLI argument descriptions for session listing, changing 'current project' to 'current workspace'.
  • packages/cli/src/config/settingsSchema.ts
    • Updated settings schema for UI options to use 'workspace path', changing 'Hide CWD' label and description.
  • packages/cli/src/nonInteractiveCli.test.ts
    • Updated non-interactive CLI test data to use workspaceHash instead of projectHash.
  • packages/cli/src/services/BuiltinCommandLoader.ts
    • Updated builtin command loader to use the new workspaceCommand instead of directoryCommand.
  • packages/cli/src/services/FileCommandLoader.ts
    • Refactored file command loader to use workspaceRoot and updated related comments and methods.
    • Replaced projectRoot property with workspaceRoot and updated its usage.
    • Updated comments from 'project' to 'workspace' for command loading and conflict resolution.
    • Updated getCommandDirectories to use storage.getWorkspaceCommandsDir().
  • packages/cli/src/ui/AppContainer.test.tsx
    • Updated AppContainer test data to use workspaceHash instead of projectHash in mock conversation records.
  • packages/cli/src/ui/auth/AuthDialog.tsx
    • Updated authentication dialog text for consistency, changing 'authenticate for this project?' to 'authenticate for this workspace?'.
  • packages/cli/src/ui/auth/snapshots/AuthDialog.test.tsx.snap
    • Updated UI snapshots for AuthDialog to reflect 'authenticate for this workspace?'.
  • packages/cli/src/ui/commands/directoryCommand.test.tsx
    • Renamed test file to workspaceCommand.test.tsx.
    • Updated imports and describe block name to reflect workspaceCommand.
    • Changed command references within tests from /directory to /workspace.
    • Updated error message for sandbox restriction from /directory add to /workspace add.
  • packages/cli/src/ui/commands/directoryCommand.tsx
    • Renamed command file to workspaceCommand.tsx.
    • Renamed directoryCommand export to workspaceCommand.
    • Updated name to 'workspace' and altNames to include 'directory' and 'dir'.
    • Updated error message for sandbox restriction from /directory add to /workspace add.
  • packages/cli/src/ui/commands/initCommand.test.ts
    • Updated init command test assertion for info message, changing 'analyzing the project' to 'analyzing the workspace'.
  • packages/cli/src/ui/commands/initCommand.ts
    • Updated init command description and info messages to refer to 'workspace' instead of 'project'.
  • packages/cli/src/ui/components/NewAgentsNotification.tsx
    • Updated new agents notification text for consistency, changing 'found in this project' to 'found in this workspace'.
  • packages/cli/src/ui/components/RewindViewer.test.tsx
    • Updated RewindViewer test data to use workspaceHash instead of projectHash.
  • packages/cli/src/ui/components/snapshots/NewAgentsNotification.test.tsx.snap
    • Updated UI snapshots for NewAgentsNotification to reflect 'found in this workspace'.
  • packages/cli/src/ui/components/triage/TriageIssues.tsx
    • Updated triage issue prompts for consistency, changing 'Gemini CLI project' to 'Gemini CLI workspace' and 'out of scope for this project' to 'out of scope for this workspace'.
  • packages/cli/src/ui/constants/tips.ts
    • Updated various informative tips to use 'workspace' terminology.
    • Changed 'CWD' to 'Workspace Path' in footer elements tip.
    • Updated /directory command references to /workspace for adding/showing directories.
    • Changed 'project-specific GEMINI.md file' to 'workspace-specific GEMINI.md file' for /init command.
    • Updated /restore command tip from 'project files' to 'workspace files'.
  • packages/cli/src/ui/hooks/useFolderTrust.test.ts
    • Updated folder trust test assertion for warning message, changing 'project settings' to 'workspace settings'.
  • packages/cli/src/ui/hooks/useFolderTrust.ts
    • Updated folder trust warning message to refer to 'workspace settings' instead of 'project settings'.
  • packages/cli/src/ui/hooks/useRewind.test.ts
    • Updated useRewind test data to use workspaceHash instead of projectHash.
  • packages/cli/src/ui/hooks/useSessionResume.test.ts
    • Updated session resume test data to use workspaceHash instead of projectHash in mock session data.
  • packages/cli/src/ui/utils/clipboardUtils.ts
    • Refactored clipboard utility functions to use 'workspace' terminology and paths.
    • Renamed getProjectClipboardImagesDir to getWorkspaceClipboardImagesDir and updated its usage.
    • Updated internal calls to storage.getWorkspaceTempDir().
  • packages/cli/src/utils/sessionUtils.ts
    • Updated session utility error messages, changing 'No previous sessions found for this project.' to 'No previous sessions found for this workspace.'.
  • packages/cli/src/utils/sessions.test.ts
    • Updated session test assertions to refer to 'workspace' instead of 'project' for session messages.
  • packages/cli/src/utils/sessions.ts
    • Updated messages for listing and deleting sessions from 'project' to 'workspace'.
  • packages/cli/src/zed-integration/zedIntegration.ts
    • Updated Zed integration debug message, changing 'outside the project directory' to 'outside the workspace directory'.
  • packages/core/src/agents/registry.ts
    • Refactored agent registry to use workspaceRoot and 'workspace' terminology for agent loading and acknowledgment.
    • Replaced projectRoot with workspaceRoot and updated calls to ackService.acknowledge.
    • Updated comments from 'project-level agents' to 'workspace-level agents'.
    • Updated calls to storage.getWorkspaceAgentsDir() and ackService.isAcknowledged.
    • Changed info message from 'Skipping project agents' to 'Skipping workspace agents'.
  • packages/core/src/commands/restore.ts
    • Updated restore command success message, changing 'Restored project' to 'Restored workspace'.
  • packages/core/src/config/config.ts
    • Introduced workspaceHooks and deprecated projectHooks in ConfigParameters.
    • Renamed private projectHooks to private workspaceHooks.
    • Updated constructor logic to prioritize workspaceHooks and map projectHooks to workspaceHooks.
    • Added getWorkspaceRoot() and deprecated getProjectRoot().
    • Updated error messages to refer to getWorkspaceContext().targetDir and storage.getWorkspaceTempDir().
    • Added getWorkspaceHooks() and deprecated getProjectHooks().
    • Updated getMemory() to return workspace instead of project for environment memory.
  • packages/core/src/config/memory.ts
    • Added workspace property to HierarchicalMemory interface and deprecated project.
    • Updated flattenMemory to prioritize workspace over project for memory sections.
  • packages/core/src/config/storage.ts
    • Extensively refactored to rename all 'project' related storage paths and methods to 'workspace', with deprecation for backward compatibility.
    • Renamed getProjectTempDir() to getWorkspaceTempDir() and deprecated the old name.
    • Renamed ensureProjectTempDirExists() to ensureWorkspaceTempDirExists() and deprecated the old name.
    • Renamed getProjectRoot() to getWorkspaceRoot() and deprecated the old name.
    • Renamed various getProject...Dir() methods to getWorkspace...Dir() and deprecated their old names.
    • Renamed listProjectChatFiles() to listWorkspaceChatFiles() and deprecated the old name.
    • Renamed loadProjectTempFile() to loadWorkspaceTempFile() and deprecated the old name.
    • Updated getPlansDir() to use getWorkspaceRoot() and getWorkspaceTempPlansDir().
    • Updated getHistoryFilePath() to use getWorkspaceTempDir().
  • packages/core/src/core/prompts.test.ts
    • Updated core prompt test snapshot assertion from <project_context> to <workspace_context>.
  • packages/core/src/hooks/hookRegistry.ts
    • Refactored hook registry to use 'workspace' terminology for trust checks and hook processing.
    • Renamed checkProjectHooksTrust() to checkWorkspaceHooksTrust().
    • Updated internal calls to config.getWorkspaceRoot() and config.getWorkspaceHooks().
    • Updated warning messages from 'project-level hooks' to 'workspace-level hooks' and 'trust this project' to 'trust this workspace'.
    • Changed warning message for disabled hooks from 'Project hooks disabled' to 'Workspace hooks disabled'.
  • packages/core/src/policy/types.ts
    • Updated policy types to include 'workspace' as a HookSource and in VALID_HOOK_SOURCES.
    • Modified getHookSource to return 'workspace' as default and treat 'project' as 'workspace' for backward compatibility.
    • Updated comment for source property from 'Workspace: project.toml' to 'Workspace: workspace.toml'.
  • packages/core/src/prompts/promptProvider.ts
    • Updated prompt provider logic to consider workspace memory when checking for hierarchical memory.
  • packages/core/src/prompts/snippets.legacy.ts
    • Extensively updated legacy prompt snippets to replace 'project' with 'workspace' for consistency in core mandates, workflows, sandbox descriptions, git repository context, and final reminders.
    • Changed hierarchical memory context tag from <project_context> to <workspace_context>.
  • packages/core/src/prompts/snippets.ts
    • Extensively updated prompt snippets to replace 'project' with 'workspace' for consistency in engineering standards, delegation candidates, execution steps, sandbox descriptions, git repository context, and file system state examples.
    • Changed hierarchical memory context tag from <project_context> to <workspace_context>.
  • packages/core/src/services/FolderTrustDiscoveryService.ts
    • Updated folder trust discovery service messages for consistency, changing 'This project' to 'This workspace' in security-related checks.
  • packages/core/src/services/chatRecordingService.ts
    • Refactored chat recording service to use workspaceHash and workspace temporary directories.
    • Replaced getProjectHash with getWorkspaceHash.
    • Renamed projectHash to workspaceHash in ConversationRecord interface and ChatRecordingService class.
    • Updated constructor to use getWorkspaceHash(config.getWorkspaceContext().targetDir).
    • Updated chatsDir path to use config.storage.getWorkspaceTempDir().
  • packages/core/src/services/contextManager.ts
    • Refactored context manager to use workspaceMemory for environment context.
    • Renamed projectMemory to workspaceMemory.
    • Updated discoverMemoryPaths, loadMemoryContents, and categorizeMemoryContents to use workspace paths.
    • Updated getEnvironmentMemory() to return workspaceMemory.
  • packages/core/src/services/gitService.ts
    • Refactored Git service to use workspaceRoot and restoreWorkspaceFromSnapshot.
    • Renamed projectRoot to workspaceRoot in class property and constructor.
    • Updated userGitIgnorePath and shadowGitRepository to use workspaceRoot.
    • Renamed restoreProjectFromSnapshot to restoreWorkspaceFromSnapshot and deprecated the old name.
  • packages/core/src/tools/definitions/dynamic-declaration-helpers.ts
    • Updated description for PARAM_DIR_PATH from 'project root directory' to 'workspace root directory'.
  • packages/core/src/tools/definitions/model-family-sets/default-legacy.ts
    • Updated example ToDo list from 'React project environment' to 'React workspace environment'.
  • packages/core/src/tools/definitions/model-family-sets/gemini-3.ts
    • Updated Gemini-3 model family set tool descriptions and examples.
    • Changed save_memory tool description from 'project-specific files' to 'workspace-specific files' and 'project-specific names' to 'workspace-specific names'.
    • Updated example ToDo list from 'React project environment' to 'React workspace environment'.
  • packages/core/src/tools/read-many-files.ts
    • Updated read-many-files tool message, changing skipped files reason from 'ignored by project ignore files' to 'ignored by workspace ignore files'.
  • packages/core/src/tools/tool-registry.ts
    • Updated tool registry descriptions and comments.
    • Changed tool discovery description from 'project' to 'workspace' for root and settings.
    • Updated comment from 'Discovers tools from project' to 'Discovers tools from workspace'.
  • packages/core/src/utils/environmentContext.ts
    • Updated environment context description, changing 'project's temporary directory' to 'workspace's temporary directory'.
  • packages/core/src/utils/ignorePatterns.ts
    • Updated ignore patterns comments, changing 'development projects' to 'development workspaces'.
  • packages/core/src/utils/memoryDiscovery.ts
    • Extensive refactoring to rename 'project' related memory discovery functions and variables to 'workspace'.
    • Renamed findProjectRoot to findWorkspaceRoot.
    • Updated return type of getGeminiMdFilePathsInternal from project to workspace.
    • Renamed projectPaths to workspacePaths in internal functions.
    • Updated debug messages from 'project root' to 'workspace root'.
    • Updated categorizeAndConcatenate to accept workspace paths and prioritize them.
    • Updated loadServerHierarchicalMemory to use workspace paths.
  • packages/core/src/utils/paths.ts
    • Renamed path hashing utility to use workspaceHash.
    • Renamed getProjectHash to getWorkspaceHash and deprecated the old name.
Activity
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request primarily renames all instances of 'project' to 'workspace' across the codebase, including documentation, CLI commands, configuration settings, UI elements, and internal services. Key changes involve updating command names (e.g., /directory to /workspace), configuration scopes, file paths, temporary directories, and prompt contexts to reflect a 'workspace'-centric terminology. Deprecated 'project' references are often replaced with 'workspace' equivalents, sometimes with backward compatibility. The change aims to standardize the terminology used throughout the application.

@gemini-cli gemini-cli Bot added the area/core Issues related to User Interface, OS Support, Core Functionality label Mar 1, 2026
const client = config.getBaseLlmClient();
const prompt = `
I am triaging GitHub issues for the Gemini CLI project. I need to identify issues that should be closed because they are:
I am triaging GitHub issues for the Gemini CLI workspace. I need to identify issues that should be closed because they are:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure about this one...

- Abusive or offensive
- Gibberish (nonsense text)
- Clearly out of scope for this project
- Clearly out of scope for this workspace

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto here, leave as project.

@github-actions

github-actions Bot commented Mar 1, 2026

Copy link
Copy Markdown

Size Change: +3.98 kB (+0.02%)

Total Size: 25.8 MB

Filename Size Change
./bundle/gemini.js 25.3 MB +3.98 kB (+0.02%)
ℹ️ View Unchanged
Filename Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js 221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js 227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js 11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js 132 B
./bundle/sandbox-macos-permissive-open.sb 890 B
./bundle/sandbox-macos-permissive-proxied.sb 1.31 kB
./bundle/sandbox-macos-restrictive-open.sb 3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb 3.56 kB
./bundle/sandbox-macos-strict-open.sb 4.82 kB
./bundle/sandbox-macos-strict-proxied.sb 5.02 kB

compressed-size-action

@gemini-cli gemini-cli Bot added priority/p1 Important and should be addressed in the near term. 🔒 maintainer only ⛔ Do not contribute. Internal roadmap item. labels Mar 4, 2026
…orkspace

# Conflicts:
#	docs/cli/settings.md
#	docs/reference/configuration.md
#	packages/cli/src/config/settings.test.ts
#	packages/cli/src/config/settingsSchema.ts
#	packages/cli/src/services/CommandService.test.ts
#	packages/cli/src/services/FileCommandLoader.ts
#	packages/cli/src/ui/components/RewindViewer.test.tsx
#	packages/cli/src/ui/constants/tips.ts
#	packages/cli/src/ui/utils/borderStyles.test.tsx
#	packages/cli/src/utils/processUtils.test.ts
#	packages/cli/src/utils/sessionUtils.ts
#	packages/core/src/commands/memory.test.ts
#	packages/core/src/config/config.ts
#	packages/core/src/config/storage.test.ts
#	packages/core/src/core/__snapshots__/prompts.test.ts.snap
#	packages/core/src/scheduler/tool-executor.ts
#	packages/core/src/services/contextManager.ts
#	packages/core/src/utils/memoryDiscovery.test.ts
#	packages/core/src/utils/memoryDiscovery.ts
#	schemas/settings.schema.json
@LyalinDotCom

Copy link
Copy Markdown
Collaborator

This PR is resolved by #21877 that took inspiration from this original change.

@sripasg sripasg added the size/xl An extra large PR label Jun 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/core Issues related to User Interface, OS Support, Core Functionality 🔒 maintainer only ⛔ Do not contribute. Internal roadmap item. priority/p1 Important and should be addressed in the near term. size/xl An extra large PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants