<!-- * Use this issue template for suggesting new docs or updates to existing docs. Note: Doc work as part of feature development is covered in the Feature Request template. * For issues related to features of the docs.gitlab.com site, see https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/issues * For information about documentation content and process, see https://docs.gitlab.com/development/documentation/ --> - [x] Start this issue's title with `Docs:` or `Docs feedback:`. ## Problem to solve <!-- Include the following detail as necessary: * What product or feature(s) affected? * What docs or doc section affected? Include links or paths. * Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs? * Any other ideas or requests? --> GitLab CI/CD interprets file path patterns differently in different contexts: 1. in `cache:paths` or `artifacts:paths`, it interprets them as `glob` and `doublestar.Glob` patterns 2. in `cache:key:files`, I think it interprets them like git pathspecs These sometimes behave differently, e.g. for `**/foo`. Example: ``` $ tree . ├── foo └── my_dir └── foo 2 directories, 2 files $ shopt -s globstar # enable globstar expansion $ ls **/foo # DOES match foo at top level foo    my_dir/foo $ git ls-files '**/foo' # DOES NOT match foo at top level my_dir/foo ``` The docs make (1) clear (https://docs.gitlab.com/ci/yaml/#cachepaths and https://docs.gitlab.com/ci/yaml/#artifactspaths), but are silent about (2) (https://docs.gitlab.com/ci/yaml/#cachekeyfiles). This caught me out: I used a pattern like `**/foo` in `cache:key:files`, expecting it to catch `foo` files at every level, but it did not. ## Further details <!-- * Any concepts, procedures, reference info we could add to make it easier to successfully use GitLab? * Include use cases, benefits, and/or goals for this work. * If adding content: What audience is it intended for? (What roles and scenarios?) For ideas, see personas at https://handbook.gitlab.com/handbook/product/personas/ or the persona labels at https://gitlab.com/groups/gitlab-org/-/labels?subscribed=&search=persona%3A --> None ## Proposal <!-- Further specifics for how can we solve the problem. --> Update the docs for `cache:key:files` to note that in this context patterns are interpreted like git pathspecs. ## Who can address the issue <!-- What if any special expertise is required to resolve this issue? --> Anyone ## Other links/references <!-- For example, related GitLab issues/MRs --> I found this recent issue comment https://gitlab.com/gitlab-org/gitlab/-/issues/301161#note_2436729449. It explains how `cache:key:files` patterns are interpreted, and notes the above issue: > That does man however that while `**/package.json` will match that file in any subfolder, it will not match that file in the root directory of the repo.