apple / apple/container

[Bug]: Container machine docs disagree on the home directory path

Open Beginner friendly
#1,678 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
49.9k
Forks
1.8k
Avg merge
1d 20h
Merged PRs (30d)
22

Description

The new container machine docs describe the home directory in two different ways.

### What I found

In `docs/container-machine.md`, the first section says:

```text
Your repo lives in $HOME on macOS and is mounted at /Users/ inside the container machine.
```

But the quickstart right below it says:

```bash
container machine run -n dev pwd # /home/ — your Mac home dir, mounted in
```

Those two paths point users in different directions:

- `/Users/` sounds like the macOS path is preserved inside the Linux machine
- `/home/` sounds like a normal Linux home directory

### What the code seems to do

The implementation and tests point to `/home/` as the machine user's home.

`Sources/Services/MachineAPIService/Client/MachineConfiguration.swift`:

```swift
public var home: String {
"/home/\(username)"
}
```

The CLI test also checks for that exact path:

```swift
#expect(home == "/home/\(hostUsername)", "HOME should be set to /home/")
```

### Expected

The docs should use one clear story for this.

Something like:

```text
Your macOS home is shared into the container machine and exposed as the Linux user's home at /home/.
```

That keeps the docs aligned with the code and avoids users looking for their files under `/Users/` inside the machine.

### Why this matters

Container machines are meant to feel like a persistent Linux dev environment. The first thing users will check is `pwd`, `$HOME`, and where their repo is mounted. If the docs mention both `/Users/` and `/home/`, it is easy to think the mount is broken when it is actually just the doc wording.

Contributor guide

Open the contributing guide

Research direction

Start with docs/container-machine.md and compare its first section with the quickstart example. Use Sources/Services/MachineAPIService/Client/MachineConfiguration.swift and the cited CLI test to verify the documented home path. Done means the documentation consistently explains that the macOS home is exposed as /home/ inside the machine.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.