Re: as promised, docs: git for the confused

From: Junio C Hamano <junkio@cox.net>
Date: Dec 10, 2005, 01:22 UTC
Message-ID: <7vk6edycea.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <20051209054401.4016.qmail@science.horizon.com>

linux@horizon.com writes:

Show 6 quoted lines

> ....  There has
> been motion towards putting the git-* commands in their own directory,
> to be invoked by the /usr/bin/git wrapper.
>
> In this case, you'll have to leave out the initial hyphen, or add the
> git binary directory to your $PATH.

Misleading, if not incorrect. git wrapper and a handful others such as receive-pack and upload-pack that need to be directly invoked via ssh will remain in /usr/bin and the users do not need to worry about where the rest went. The recommended way would be to use non-dash form. If you care about the extra indirection done by "git" in your script, run "git --exec-path" once to get the git binary directory and prepend the result to PATH. You _could_ do the latter for your interactive shell session as well, but it is not actively recommended.

Show 5 quoted lines

> * Resetting
>
> There are actually three kinds of git-reset:
> git-reset --soft: Only overwrite the reference.  If you need to, you
> 	can put everything back with a second git-reset --soft OLD_HEAD.

I am not sure what you mean by "second" here. Did you mean to say something like this?

    After you did "git-reset --soft somewhereyoudidnotmeantogo"
    by mistake, you can recover with "git-reset --soft ORIG_HEAD".

> There is an undelete: git-reset stores the previous HEAD commit in
> OLD_HEAD.

And probably you meant to say ORIG_HEAD (the latter part of the documentation you do say ORIG_HEAD).

Now I finally had a chance to finish the command list part.

> git-prune.sh
>...
> 	eliminate the

Incomplete sentence.

> git-pack-objects
> 	Given a list of objects on stdin, build a pack file.  This is
> 	a helper used by the various network communication scripts.

... and by (obviously) git-repack.

> + Accepting changes by e-mail
> git-apply
> 	Apply a (git-style extended) patch to the current index
> 	and working directory.

Actually it can take "patch -p1" format patch, and the input does not have to be git-extended patch. Two extra things you can do when the input is git-extended patch is to apply rename/copy and filemode changes.

>   git-merge-base
>...
> 	somewhat hairy.  The algorithm is not 100% final yet.

I do not think there is any remaining issues with the current algorithm, so you can mark it final now.

>   git-mktag
> 	Creates a tag object.  Verifies syntactic correctness of its
> 	input.  (If you want to cheat, use git-hash-object.)

Is there a particular reason to encourage cheating? IOW, is mktag cumbersome to use, and if so how?

>   git-local-fetch
> 	Duplicates a git repository from the local system.
> 	(Er... is this used anywhere???)

Not by git barebone Porcelain, but other Porcelains can use it if they want. Same thing for git-ssh-fetch.

>   git-ssh-pull
> 	A helper program that pulls over ssh.

git-ssh-pull and git-ssh-fetch are the same program, and the former is only for backward compatibility. Earlier, only git-ssh-pull/git-ssh-push pair existed and they continue to invoke the other on the other end. Terminology standardized to call downloading phase "-fetch", and its counterpart "-upload"; so git-ssh-fetch invokes git-ssh-upload on the other end (so ssh-pull/ssh-push can be viewed obsolete if you want).