[FEATURE] set up gitignore for deployed files

[petemounce]

Is your feature request related to a problem? Please describe.
When apm install is run, it delivers content into the working tree. This can then be accidentally committed to source control in the scenario where apm is not being used as a vendoring-code tool.

Describe the solution you'd like
apm.yml can have a top-level mode parameter, taking values default or vendor. The former behaves as now plus additively starts to also maintain .gitignore entries for the content that is being managed by apm. The latter does not maintain .gitignore entries.

The repo-root .gitignore is tempting but would grow large and as that is usually a hand-maintained file, that would complicate maintainers' UX. If this is accepted I'd propose either

1. {target-root}/.gitignore
2. {target-root}/{content-type}/.gitignore

... as both are more likely to be hands-off files. (1) might be problematic as for example .claude/settings.json or .opencode/opencode.json live within, so there's possibility of human/machine toe-stomping.

Describe alternatives you've considered
I think the ideal would be gitignore having an include directive that would allow apm to have its own file but sadly that's not a feature gitignore has.

I thought also about deploying symlinks aimed into apm_modules - but those would still ideally be gitignored, so discarded it.

Additional context

n/a

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/package-authoring
area/docs-site
type/feature
status/needs-design

Milestone

null

Suggested next action

Share your preference on three design questions in a comment here: (1) config key name (gitignore_deployed: true vs mode: default|vendor), (2) which .gitignore file receives the managed entries, (3) whether apm uninstall removes those entries -- then we can move to a design doc quickly.

Suggested issue comment

Thank you for this well-reasoned feature request, and for working through the alternatives! You have correctly identified the core tension: APM supports both "vendor mode" (commit primitives into source control) and "install mode" (treat them like transient dependencies), and right now there is no signal to git about which mode you intend.

Triage summary:

- **User need**: Valid. When using APM without vendoring, deployed files show as untracked/modified in git and can be accidentally committed. A managed `.gitignore` would make the non-vendor workflow friction-free.
- **Design questions before code can land**:
  1. **Config key naming**: `mode: default|vendor` is the reverse of the intuitive meaning -- "vendor" in the npm/pip/cargo mental model means "commit files to source control," but in the proposal it means "do NOT gitignore." A boolean like `gitignore_deployed: true` or a string `deploy_mode: gitignored|committed` may communicate intent more clearly. This touches `apm.yml` schema (user-visible, sets a lifetime contract).
  2. **Gitignore file placement**: The two options you raised (`{target-root}/.gitignore` vs `{target-root}/{content-type}/.gitignore`) each have trade-offs. A marker-comment block managed inside the repo-root `.gitignore` is a third option worth considering -- it keeps all gitignore state in one place and makes APM's ownership visible.
  3. **Uninstall lifecycle**: The issue does not cover removing gitignore entries when a package is removed (`apm uninstall` / `apm install` without that package). Specifying this is required before implementation can begin.
- **Architecture**: Touches `apm.yml` schema parsing, install phases, and a new gitignore manager utility -- cross-cutting enough to need a design decision before a PR opens.

Decision: **needs-design**. What must be designed: (1) config key name and semantics, (2) gitignore file placement strategy, (3) uninstall lifecycle for managed gitignore entries.

Next step: share your preference on the three questions above (a comment here is fine), and we can move quickly from there. This is a feature we would be happy to accept once the design is settled -- the need is real and the implementation is tractable.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user need is real: APM-deployed files appearing as untracked git changes is adoption friction for users who do not intend to vendor primitives. The mode: default|vendor naming in the proposal is counter-intuitive -- "vendor" in the npm/pip mental model means "commit files to source control," but in the proposal it means "do NOT gitignore." A clearer API: gitignore_deployed: true (opt-in; clear intent) or deploy_mode: gitignored|committed. The gitignore file placement also needs a decision: writing to {target-root}/.gitignore risks stomping on hand-managed entries; a marker-comment block in the repo root .gitignore might be cleaner and more discoverable.

Supply Chain Security Expert -- Risk-Surface Reviewer

No supply-chain risk surface. The .gitignore management is client-side only and does not affect package resolution, lockfile integrity, or MCP trust. One edge case the implementation must guard: scope gitignore entries tightly to known APM-managed paths and never write wildcard patterns that could accidentally exclude security-relevant files (e.g., a local policy override file).

OSS Growth Hacker -- Contributor-Tone Reviewer

petemounce is an external contributor with NONE association on microsoft/apm -- this is likely their first interaction with the project. The feature request is thoughtful: they worked through alternatives and acknowledged gitignore limitations. The reply should be warm, specific about why design questions exist (not vague), and end with a concrete invitation to continue the conversation. This is exactly the kind of external contributor APM wants to retain as a repeat contributor.

Python Architect -- Architecture Reviewer

Adding a new top-level key to apm.yml is a schema change that sets a lifetime contract -- the name and semantics must be right before shipping. The implementation spans: (1) apm.yml parsing to read the new key, (2) install phases to conditionally invoke the gitignore manager, (3) a new utility (utils/gitignore_manager.py or similar) for writing and removing marker-delimited blocks. The uninstall lifecycle (removing managed entries on apm remove) is the hardest part -- it requires the gitignore manager to track ownership via marker comments rather than content matching. status/needs-design until the three interface questions are answered.

Doc Writer -- Documentation Reviewer

A new apm.yml top-level key needs documenting in the manifest reference and the lockfile-spec. The deploy-mode behavior warrants a getting-started guide section ("When to vendor vs gitignore your deployed primitives"). area/docs-site added as secondary label so the implementing PR is reminded. The suggested comment uses plain language the author will recognize from the README.

APM CEO -- Triage Arbiter

Accept-in-principle, needs-design. The user need is real and this feature would meaningfully reduce friction for non-vendor workflows -- a growing segment as APM adoption broadens beyond CI/CD-only users. The naming and placement decisions are not cosmetic: they set the apm.yml schema contract for the project's lifetime. Get the design right before shipping. The Growth Hacker lens is correct: petemounce's early experience shapes whether they become a repeat contributor. Reply warmly, be specific about what needs designing, and invite them into the decision.

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.8M · ◷