tips icon indicating copy to clipboard operation
tips copied to clipboard

Add explanations and links to related documentation

Open scriptin opened this issue 3 years ago • 0 comments

For ease of memorization and education purposes, some of these tips should have at least short explanations.

Example:

Delete remote branch
    git push origin --delete <remote_branchname>
Alternatives:
    git push origin :<remote_branchname>

The first command is almost obvious: newcomers to git only have to learn that "origin" is the conventional name of a remote repository, and thus it may be different in some cases. But explaining this may be deferred to git's official docs.

The alternative option is confusing for me even though I've been using git professionally for many years. The explanation is as follows:

Deleting References You can also use the refspec to delete references from the remote server by running something like this:

$ git push origin :topic Because the refspec is <src>:<dst>, by leaving off the <src> part, this basically says to make the topic branch on the remote nothing, which deletes it.

Or you can use the newer syntax (available since Git v1.7.0):

$ git push origin --delete topic

(from https://git-scm.com/book/en/v2/Git-Internals-The-Refspec)

Having short explanations like this, accompanied by links to related parts of official docs, would prevent a lot of cargo-cult-like behavior many git users are falling into.

Arguably, all this deeper knowledge can be found by reading the official docs but having quick access to only related parts would be very convenient for someone like me, who doesn't start with reading a whole book before trying something, but prefers to learn hands-on, step-by-step.

scriptin avatar Jan 02 '21 12:01 scriptin