#2133: add repository navigation option to icd command

[Ali-Shariati-Najafabadi]

This PR fixes #2133

Implemented changes:

• Added a new -r | --repository [<repository>] option to the icd shell function in cli/src/main/package/functions
• If <repository> is omitted, the project name is used as the repository name (fallback)
• If -w is not given, workspace main is searched first, then all other workspaces; icd navigates into the first workspace containing the repository
• If -w is given explicitly, only that workspace is searched (no fallback)
• If the repository is not found in any workspace, icd fails with Error: Repository '<name>' not found in any workspace.
• Updated icd --help usage/options text
• Updated documentation/cli.adoc with a description and example of the new option

---

Testing instructions

Run the automated test suite, which covers all scenarios from #2133 in both bash and zsh:
bash cli/src/test/functions-test.sh

---

Checklist for this PR

• When running mvn clean test locally all tests pass and build is successful
• PR title is of the form #«issue-id»: «brief summary»
• PR top-level comment summarizes what has been done and contains link to addressed issue(s)
• PR and issue(s) have suitable labels
• Issue is set to In Progress and assigned to you or there is no issue
• You followed all coding conventions
• You have added the issue implemented by your PR in CHANGELOG.adoc unless issue is labeled with internal
• You have formulated clear instructions on how to test your contribution under "Testing instructions"

[coveralls]

Coverage Report for CI Build 29602468709

Coverage remained the same at 72.506%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	16797
Covered Lines:	12697
Line Coverage:	75.59%
Relevant Branches:	7496
Covered Branches:	4917
Branch Coverage:	65.59%
Branches in Coverage %:	Yes
Coverage Strength:	3.2 hits per line

---

💛 - Coveralls

[maybeec]

Thanks for this contribution — the implementation covers the issue requirements well. I verified all scenarios from #2133 hands-on: sourced the functions file from this PR against a synthetic IDE_ROOT (with a stubbed ideasy) and exercised every path in bash and in zsh 5.9. zsh matters here because IdeasyCommandlet wires source "$IDE_ROOT/_ide/installation/functions" into .zshrc as well, and zsh is the default shell on macOS.

Verification against issue #2133

Requirement (#2133)	Result
1: icd -p X -r falls back to the project name	✅ verified
1: no project-name folder, but exactly one non-hidden folder in the workspace → enter it	✅ verified
1: otherwise cd into the workspace and log a warning	✅ bash — ❌ zsh aborts when the workspace is empty (see inline comment)
2: explicit icd -p X -r «repo», incl. nested paths like -r backend/core (example B)	✅ verified
2/3: resolved in the given workspace, or searched main first, then all other workspaces	✅ verified
4: clear error message when not found	✅ bash — ❌ zsh aborts when workspaces is missing/empty; wording misleading with explicit -w (see inline comments)
Help text + documentation/cli.adoc updated	✅

Must-fix

1. zsh: the new workspace-scan globs abort icd — see the inline comment in functions (includes a verified one-click fix).

2. Missing CHANGELOG.adoc entry. #2133 is not labeled internal, so per the PR checklist and the DoD the issue must be added to CHANGELOG.adoc under the next open release (currently the == 2026.07.002 section):

   * https://github.com/devonfw/IDEasy/issues/2133[#2133]: Add repository navigation option (-r) to icd command
   

Should-address

3. No automated tests, although a test harness for this exact file exists and runs in CI: cli/src/test/functions-test.sh unit-tests the functions file and is executed on every PR build (see .github/workflows/build-pr.yml). TDD is our standard for features (see AGENTS.md), and your manual testing instructions map 1:1 to automatable checks using the existing pattern there (fresh bash --noprofile --norc, stub ideasy on PATH, temporary IDE_ROOT tree). Suggested minimum cases: repo found in main; repo found in another workspace; explicit -w restricting the search; not found → exit code 1 + error message; implicit -r resolving the project-name folder; single-folder fallback; warning + cd into the workspace for an empty/ambiguous workspace. Is this planned as a follow-up, or can it land in this PR?
4. Misleading error message when -w is given explicitly — see inline suggestion in functions.

Minor

5. Testing instructions step 5 is outdated since the fallback behavior was added: with the tree from step 1 (main only contains cli), icd -p IDEasy -r now lands in workspaces/main/cli via the single-folder fallback — not in workspaces/main/IDEasy (that folder is never created in step 1). Verified in bash. Please update the PR description (e.g. create workspaces/main/IDEasy for step 5 and add a separate step for the single-folder fallback).
6. Docs: nested repository paths are supported but not documented — see inline suggestion on cli.adoc.

Everything else looks good: the option parsing is consistent with the existing -w handling, the search order matches the issue, existing icd invocations without -r are unaffected, --help and the docs are updated, CI is green, and the branch is up to date with main.

[maybeec]

One design concern about the implicit -r fallback — this questions the requirement from #2133 rather than this implementation, which follows it faithfully (cc @vivu001):

When -r is given without a value and no folder matching the project name exists, the "single non-hidden folder" fallback silently drops you into a folder whose name has nothing to do with what was asked for. Example: in a project IDEasy whose main workspace only contains ide-urls, icd -r ends up in .../main/ide-urls without any hint. This makes the result hard to predict ("what will icd pick?") and invites misconceptions such as repositories being searched recursively (they are not — a repository is always resolved as a direct child of a workspace, or as a literal relative path like -r backend/core).

I would find it more intuitive to drop the auto-descend and always cd into the workspace with the existing warning when the project-name folder is not found — i.e. treat the "exactly one folder" case the same as the ambiguous case. Then icd -r stays fully deterministic: you either land in the folder you named (or the project-name folder), or in the workspace itself with a warning.

@vivu001 was there a specific use case behind the single-folder shortcut in #2133? If we agree to change this, the issue should be updated accordingly and this PR would actually get simpler (the fallback block shrinks to warning + cd into the workspace).

[vivu001]

Hi @maybeec , thanks for the suggestion. I think the concern about implicit behavior is well-founded. To make the behavior explicit, I would summarize your suggestion as follows:

icd -p IDEasy -r
→ /workspaces/main/IDEasy

• -r without a value → no repository is specified
• no fallback or heuristics should be applied
• show a warning (e.g. missing repository)

About the single-folder shortcut: there does not seem to be a strong functional use case behind it. It mainly acts as a convenience shortcut, but introduces implicit behavior.

A hybrid approach (strict default behavior with optional convenience) could work. I even considered something along these lines:
E.g.:

• By default (strict behavior):

icd -p IDEasy -r 
→ /workspaces/main/IDEasy 
Warning: No explicit repository was specified.

• With explicit user intent (convenience behavior):

icd -p IDEasy -r c 
→ /workspaces/main/IDEasy/cli

Overall, keeping repository selection explicit aligns better with the goal of making behavior clear and unambiguous.
Even so, I would still like to get @hohwille ’s opinion on this matter 👍.