Re: as promised, docs: git for the confused

linux@horizon.com writes:

Some users want to track someone else's repository.
Others...

Exactly.  That's why task oriented list would be most useful.
Here is a starter.


Everyday GIT Cheat Sheet Or Git With 20 Commands
================================================

Repository Administration
-------------------------

  * "init-db" or "clone" to create the initial repository.
  * hooks.
    - public accessible via dumb protocols: need
      update-server-info in hooks/post-update
    - CVS style shared repository: see howto/update-hook-example
      for ideas on branch head policy
  * "fsck-objects", "repack" and "prune".


Individual Developer
--------------------

Standalone tasks

  * "show-branch" or "gitk" to see where you are.
  * "diff" or "status" to see what you are in the middle of.
  * "log" to see what happened.
  * "whatchanged" to find out where things come from.
  * "checkout" and "checkout -b" to switch branches.
  * "commit" to advance the current branch head.
  * "reset" to undo unpublished changes.
  * "checkout -- path" to undo working tree chanegs.
  * "pull ." to merge between branches.
  * "rebase" to maintain topic branches.
  * "fsck-objects", "repack" and "prune".

Working as a participant

  * all the commands useful for standalone individual developer tasks.
  * "pull origin" to keep up-to-date.
  * "push upstream" in CVS style shared repository workflow.
  * "format-patch" in kernel style public forum workflow.

Integrator
----------

  * all the commands useful for standalone individual developer tasks.
  * "am" to apply patches.
  * "pull somewhere-else" to merge from trusted lieutenants.
  * "format-patch" to send suggested alternative to contributors.
  * "revert" to undo botched changes.
  * "push public" to publish the results.


It might be surprising that only handful commands are of
everyday use among 100+, but the ones listed above are the only
ones I use every day.  The exact number depends on how you count
multi-purpose commands like "checkout" and "pull", but only
these need to be learned to play all roles listed above.

	am
	checkout
	checkout -- path
	checkout -b
	commit
	diff
	fetch
	format-patch
	fsck-objects
	gitk
	init-db
	log
	prune
	pull .
	pull other
	push
	rebase
	repack
	reset
	revert
	show-branch
	status
	whatchanged

On Fri, 9 Dec 2005, Junio C Hamano wrote:

Exactly.  That's why task oriented list would be most useful.
Here is a starter.


Everyday GIT Cheat Sheet Or Git With 20 Commands
================================================

Would this file perhaps also have examples?

I really think a lot of people learn better from examples than from having 
pointers to git programs that can be useful.

For example, earlier today I got the bash tar-ball because I had forgotten 
what the magic config option was to make bash do the right thing wrt pipe 
write errors. And because I'm totally dependent on "git grep" these days, 
I turned that tar-ball into a git archive. It's really a sinfully simple 
thing to do, but I don't think we mention that anywhere in the docs.

Here's what I did:

	# Extract the thing as normal
	zcat < bash-3.0.tar.gz | tar xvf -
	cd bash-3.0/

	# make a git archive out of it
	git init-db
	git add .
	git commit

and that's it. That creates a git archive from a tar-ball. Very simple, 
and short sequences like these would make tons of sense for a "cheat 
sheet" like yours, and I really think most people can look at those three 
git commands and suddenly they understand what they do a lot better than 
by reading the man-pages.

Or maybe it's just me. But I know _I_ understand things better by seeing 
the "context" that they are used in. Then I go to man-pages later on, if I 
want to know the details.

No?

		Linus

On Mon, 12 Dec 2005 08:34:12 -0800 (PST)
Linus Torvalds [off-list ref] wrote:

Or maybe it's just me. But I know _I_ understand things better by seeing 
the "context" that they are used in. Then I go to man-pages later on, if I 
want to know the details.

Me too.  BTW, new users very likely read tutorial.txt first.  But it is
way too low level (git-cat-file, git-write-tree...).  Maybe those low
level commands should be described in technical/ instead?  The tutorial
would be logical place for examples.

-- 
http://onion.dynserv.net/~timo/

Linus Torvalds [off-list ref] writes:

... But I know _I_ understand things better by seeing 
the "context" that they are used in. Then I go to man-pages later on, if I 
want to know the details.

No?

Absolutely.  It's the way how I pick up new things for me too.

On Mon, 12 Dec 2005, Timo Hirvonen wrote:

Me too.  BTW, new users very likely read tutorial.txt first.  But it is
way too low level (git-cat-file, git-write-tree...).  Maybe those low
level commands should be described in technical/ instead?  The tutorial
would be logical place for examples.

I'd almost suggest skipping the technical notes in the current tutorial, 
and just gearing it directly more towards a regular user. 

When I started writing it, I cared more about people understanding how git 
works internally. I think that was useful too, but I suspect that it's 
less useful than just knowing how to use git, and there _are_ enough 
people out there that understand how git works under the hood that it 
probably would be much better to concentrate on getting people _first_ 
used to using git, and then having a separate tutorial for "what goes 
under the hood".

So instead of teaching people about "git-read-tree --reset HEAD" etc that 
you'd never know on your own, just teach about "git reset". And not 
bothering with the "git-write-tree + git-commit-tree + git-update-ref" 
approach, just make people use "git commit" from the very beginning.

Anybody willing to just strip out the raw internals talk?

Then we could add a small section about importing from a tar-file. 

			Linus

quoted

quoted

quoted

quoted

"Linus" == Linus Torvalds [off-list ref] writes:

Linus> So instead of teaching people about "git-read-tree --reset HEAD" etc that 
Linus> you'd never know on your own, just teach about "git reset". And not 
Linus> bothering with the "git-write-tree + git-commit-tree + git-update-ref" 
Linus> approach, just make people use "git commit" from the very beginning.

I learned more by reading the cg-tutorial, at least from the user
perspective.  I then went back to the git-tutorial, and was able to
finally understand that these commands are worth ignoring. :)

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
[off-list ref] <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

On Mon, Dec 12, 2005 at 12:39:39PM -0800, Randal L. Schwartz wrote:

I learned more by reading the cg-tutorial, at least from the user
perspective.  I then went back to the git-tutorial, and was able to
finally understand that these commands are worth ignoring. :)

I don't remmeber which documentation I read but after spending a month
with cogito, I felt like I was ready for git.  The only thing I miss
from cogito is colorized diff output.  ;-)

quoted

quoted

quoted

quoted

"Joshua" == Joshua N Pritikin [off-list ref] writes:

Joshua> I don't remmeber which documentation I read but after spending a month
Joshua> with cogito, I felt like I was ready for git.  The only thing I miss
Joshua> from cogito is colorized diff output.  ;-)

Yes, that fits my experience as well.  I also don't see any direct
support for .gitignore files in any of the plumbing.  Am I missing
something there?

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
[off-list ref] <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!