Filing this as an error ticket pursuant to conversation with @aryairani here: https://discord.com/channels/862108724948500490/1463996219633303766

What's the message you're seeing?

Not strictly an error, but a suggested help message improvement. Here is what you see for branch.squash:

branch.squash (or squash.branch)
  `branch.squash /foo /bar`  creates (or updates) the branch `/bar` with a snapshot of the code at branch `/foo` without any of its history.

What would a better version look like?

We determined this would be a nice improvement:

`branch.squash /foo /bar`  creates (or updates) the branch `/bar` with a snapshot of the code at branch `/foo` without any history.

Context for why the original docs are ambiguous, and how that can create a problem

The "its" toward the end of the help message is ambiguous as to which branch's history is going away. Here is the problem that arose due to this ambiguity:

I have main. I forked it into feature-branch. I worked through implementing a feature with many updates. Ready to merge feature-branch back into main, I branch.squash /feature-branch /main.

I interpreted the "its" toward the end as referring to performing a merge with none of bar`'s history (foo's being untouched)

So I went back to feature-branch and checked its history. it's got all the history of main + the new changes to feature-branch. Great, let's merge it in.

Merge successful. But oh no, main's histroy is now only three, unannotated updates.

cbor/main> history

  Note: The most recent namespace hash is immediately below this message.
   This segment of history starts with a merge. Use `history #som3n4m3space` to view history
  starting from a given namespace hash.
  
  ⊙ 1. #l4fnu51757
  ⑃
  2. #h1rgme7rjo
  3. #pod7s9ui0t

The squash terminology is reminiscent of Git's squash, which is often used with rebasing, where the use case is to neatly smoosh a feature branches changes into a single commit and then plop it on top of the target branch. (smoosh and plop are highly technical terms). So I think this could lead to some confusion.