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

Re: [PATCH v2 08/14] ls-remote doc: fix example invocation on git.git

From
Junio C Hamano <gitster@pobox.com>
Date
Jun 23, 2013, 08:04 UTC
Message-ID
<7vvc55fe1s.fsf@alter.siamese.dyndns.org>
In-Reply-To
<CALkWK0=LRe9V7ETdEAZ7bBEDPFcTv=4cdcAE=CdNA_Xx76+LcQ@mail.gmail.com>
Ramkumar Ramachandra <artagnon@gmail.com> writes:
Show 12 quoted lines
> Junio C Hamano wrote:
>> Ramkumar Ramachandra <artagnon@gmail.com> writes:
>>
>>> Under the EXAMPLES section, there is one invocation on the git.git
>>> repository that attempts to list the refs master, pu, and rc.  The ref
>>> rc does not exist in today's repository, so remove it.  Among other
>>> things, this example demonstrates that the "<refs>..." argument is
>>> simply a filter; requesting a non-existent ref is not an error.
>>
>> These last two lines are better be in the documentation, no?
>
> You're no happy with the existing documentation?

I am not so happy with the existing EXAMPLE. Lazy people (myself included when trying to figure out other people's software) jump straight to the EXAMPLES section without reading the main body.

Especially for these people, it makes tons of difference if a sample command is accompanied by an explanation of key points the example tries to illustrate. In this particular manual page, there are a couple of commands and its sample output listed but nothing else.

Previous: Ramkumar RamachandraNext: Ramkumar Ramachandra
Message 15 of 25 in “Classify {branches,remotes}-file as fringe features”
  1. 00/14 Classify {branches,remotes}-file as fringe featuresRamkumar Ramachandra, Jun 22, 2013
  2. 01/14 t/t5505-remote: modernize styleRamkumar Ramachandra, Jun 22, 2013
  3. Junio C HamanoJun 23, 2013
  4. Ramkumar RamachandraJun 23, 2013
  5. 02/14 t/t5505-remote: test push-refspec in branches-fileRamkumar Ramachandra, Jun 22, 2013
  6. 03/14 t/t5505-remote: use test_path_is_missingRamkumar Ramachandra, Jun 22, 2013
  7. 04/14 t/t5505-remote: remove dependency on $origin_urlRamkumar Ramachandra, Jun 22, 2013
  8. 05/14 remote: remove dead code in read_branches_file()Ramkumar Ramachandra, Jun 22, 2013
  9. Junio C HamanoJun 23, 2013
  10. 06/14 t/t5505-remote: test url-with-# in branches-fileRamkumar Ramachandra, Jun 22, 2013
  11. 07/14 t/t5516-fetch-push: don't use branches-fileRamkumar Ramachandra, Jun 22, 2013
  12. 08/14 ls-remote doc: fix example invocation on git.gitRamkumar Ramachandra, Jun 22, 2013
  13. Junio C HamanoJun 23, 2013
  14. Ramkumar RamachandraJun 23, 2013
  15. Junio C HamanoJun 23, 2013
  16. 09/14 ls-remote doc: rewrite <repository> paragraphRamkumar Ramachandra, Jun 22, 2013
  17. 10/14 ls-remote doc: don't encourage use of branches-fileRamkumar Ramachandra, Jun 22, 2013
  18. 11/14 t/t5505-remote: test multiple push/pull in remotes-fileRamkumar Ramachandra, Jun 22, 2013
  19. Junio C HamanoJun 23, 2013
  20. Ramkumar RamachandraJun 23, 2013
  21. Junio C HamanoJun 23, 2013
  22. 12/14 t/t5510-fetch: don't use remotes-fileRamkumar Ramachandra, Jun 22, 2013
  23. 13/14 t/t5515-fetch-merge-logic: don't use {branches,remotes}-fileRamkumar Ramachandra, Jun 22, 2013
  24. 14/14 remote: add comment about read_{branches,remotes}_fileRamkumar Ramachandra, Jun 22, 2013
  25. Ramkumar RamachandraJun 25, 2013

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.