git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] Add hints to revert documentation about other ways to undo changes

From
Junio C Hamano <gitster@pobox.com>
Date
Aug 19, 2008, 18:56 UTC
Message-ID
<7vk5ec7s05.fsf@gitster.siamese.dyndns.org>
In-Reply-To
<1219165591-19969-1-git-send-email-tarmigan+git@gmail.com>
Tarmigan Casebolt <tarmigan+git@gmail.com> writes:
> I put this in a Note: in the DESCRIPTION section.  If there is
> consensus about moving it somewhere else, I can send another patch.
I think a note in the description would be fine.
Show 9 quoted lines
> +Note: Despite its name, 'git revert' may not undo changes in the way
> +that you expect.  If you want to throw away all uncommitted changes in
> +your working directory, you should see linkgit:git-reset[1],
> +particulary the '--hard' option.  If you want to extract specific
> +files as they were in another commit, you should see
> +linkgit:git-checkout[1], specifically the 'git checkout <commit> --
> +<filename>' syntax.  Take care with these alternatives as both will
> +discard uncommitted changes in your working directory.
> +
The last sentence makes the paragraph incoherent, doesn't it?

By starting this paragraph with "Despite its name", you are stating your expectation that the people who find "git revert" nonintuitive are the majority. And you explain how to perform the operation that majority would expect, which is to throw away uncommitted changes to go back to the clean slate. If that is what the target audience of this paragraph expects to happen anyway, why do you need to caution against it in the last sentence?

If the answer is "because it is not cut-and-dried which expectation is the majority, and we try to be careful not to lose local modifications of users", then the tone of the paragraph needs to become more neutral.

I'd suggest either dropping the first sentence altogether and starting the paragraph with "If you want to throw away...", or replacing the first sentence with "'git revert' is used to record a new commit to reverse the effect of an earlier commit (often a faulty one)."

Previous: TarmiganNext: Tarmigan Casebolt
Message 2 of 6 in “Add hints to revert documentation about other ways to undo changes”
  1. Add hints to revert documentation about other ways to undo changesTarmigan, Aug 19, 2008
  2. Junio C HamanoAug 19, 2008
  3. Add hints to revert documentation about other ways to undo changesTarmigan Casebolt, Aug 19, 2008
  4. Junio C HamanoAug 20, 2008
  5. TarmiganAug 20, 2008
  6. Junio C HamanoAug 20, 2008

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.