Re: Considering teaching plumbing to users harmful

["Dmitry Potapov" <dpotapov@gmail.com>]

On Thu, Jul 17, 2008 at 11:30 AM, "Peter Valdemar Mørch (Lists)"
<4ux6as402@sneakemail.com> wrote:
>
> As a total git newbie (5 days) coming from svn, I *am* bewildered. Even
> sticking to porcelain, it is a feature-rich new tool I have in my hands!
>
> I'm missing clarity about what is porcelain and what is plumbing. `git help`
> shows
>
> "The most commonly used git commands are:"  add .. tag.
>
> Is this list exactly the list of porcelain commands? Then say so there.

There are a few other commands that are considered as porcelain, but they
are not so often used or used for very specific purposes, such sending
patches by email. So, you do not have to bother about them right now.
In fact, even this list may be too long to be learned at once. It is
better to proceed step-wise, like this:

=== Getting started ===
1. Creating your repo
git init
git clone

2. Commiting your changes
git add
git commit

There are also git mv, git rm for those who need them.

3. Inspect your changes before committing them
git status
git diff

4. Inspecting history
git log

5. Synchronization with the upstream
git pull
git push

=== More commands ===

6. How to revert my changes?
6.1. reverting uncommitted changes
git checkout file
git checkout HEAD file
6.2. committed but not publish changes
git reset HEAD^
git reset --hard HEAD^
6.3. published changes
git revert

7. Who introduced this change?
git log -S as better alternative to git blame

8. Some useful "tricks"
git grep
git add -p
git diff --cached
git commit --amend
git show
git log -p

=== Working with branches ===

9. Creating branches and tags
git tag
git branch
git checkout

10. Merging is easy
git merge
By the way:
git pull = git fetch + git merge FETCH_HEAD
git merge branch = git pull . branch

11. What is rebase?
When can it be useful?
Advantages and disadvantages.

=== More "advanced" commands ===

12. git safety net
git log -g

13. Find the change that introduced a bug
git bisect

14. Short review other commands:
git gc
git archive
git-cherry-pick
git remote
git format-patch
git apply
git am

===

> Neither `git help diff` nor `git help ls-tree` say whether they are
> porcelain or plumbing commands. `git help diff` mentions git-diff-index,
> which i suspect is plumbing. When I read a man page, it would be nice to
> know whether a command (either the topic of the page or another mentioned
> command) is intended as porcelain or not.

I agree, it is very confusing for beginners. The rule of the thumb that
helped me when I started was that commands with dash in their names are
plumbing (there are a few exceptions though).

Dmitry