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

Re: [PATCH] Add commands that git-gc runs underneath

From
Theodore Tso <tytso@mit.edu>
Date
Aug 30, 2007, 12:34 UTC
Message-ID
<20070830123432.GD10160@thunk.org>
In-Reply-To
<Pine.LNX.4.64.0708301254420.28586@racer.site>
On Thu, Aug 30, 2007 at 12:58:00PM +0100, Johannes Schindelin wrote:
Show 9 quoted lines
> On Thu, 30 Aug 2007, Andreas Ericsson wrote:
> 
> > I kinda like it [listing the commands git-gc calls], and it might be 
> > helpful if someone's got a large repo and one part of gc for some reason 
> > didn't complete so they want to start at whatever step it broke off on.
> 
> Let me clarify: I do not like the listing in the man page.  This suggests 
> to the user to delve into plumbing areas where it is all too easy to shoot 
> yourself in the foot.

I'm somewhat sympathetic to that argument, but at the same time, we're still telling users to read the man page for plumbing areas in order to understand to get the listing valid command-line options to git commands. In addition, the main git(1) man page is dedicating talking about all sorts of low-level on-disk storage details that arguably should be in the Documentation/technical that you suggested. I also don't quite see how commands like git-repack, git-prune, git-pack-refs, et. al., are likely to get the user into trouble, any more than git-gc --prune might. Those commands are all relatively safe, and indeed, they are all listed in the git-gc's "SEE ALSO" section of its man page, so users are already being encouraged to delve into plumbing areas.

That being said, given the SEE ALSO section, I don't think it adds a huge amount of value to list the exact set of commands and options by git-gc. Also, if we add more functionality to git-gc in the future, it would be pain to have to keep upgrading to man page uptodate.

   	    	    	    	 	      - Ted
Previous: Tom ClarkeNext: Junio C Hamano
Message 7 of 13 in “Add commands that git-gc runs underneath”
  1. Add commands that git-gc runs underneathJari Aalto, Aug 30, 2007
  2. Johannes SchindelinAug 30, 2007
  3. Andreas EricssonAug 30, 2007
  4. Johannes SchindelinAug 30, 2007
  5. Andreas EricssonAug 30, 2007
  6. Tom ClarkeAug 30, 2007
  7. Theodore TsoAug 30, 2007
  8. Junio C HamanoAug 30, 2007
  9. Andreas EricssonAug 31, 2007
  10. David KastrupAug 31, 2007
  11. Junio C HamanoAug 31, 2007
  12. David KastrupAug 31, 2007
  13. David KastrupAug 30, 2007

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.