[RFC] Managing projects - advanced Git tutorial/walkthrough

[RFC] Managing projects - advanced Git tutorial/walkthrough

[Jakub Narebski]

I have browsed through Git documentation: "A tutorial introduction to
git" (tutorial.txt), "A short git tutorial" (core-tutorial.txt) which
contrary to the title is the tutorial in low-level git commands and is
longer that the first one, "Everyday GIT With 20 Commands Or
So" (everyday.txt) and "git for CVS users" (cvs-migration.txt) which does
not mention git-blame and git-annotate.

What I miss is walkthrough type tutorial, describing typical workflow (or
workflows), and tutorial concentrating on advanced topics which may come
once in a while or for some topics only, but it would be nice to know how
to resolve them.

Perhaps some of the following problems would need Git improvement (e.g.
better support for subprojects: "bind" idea)...


1. Description of typical workflow, with 'stable'/'maintenance'/'fixes' and
'development'/'master'/'main' branches, how to put bugfixes into both
branches etc. Perhaps description of git branches and workflow, or Linux
kernel branches and workflow.

2. Contrib: how to add project which was externally managed to contrib and
later/or to core, preserving history. Examples: gitk for git, or like
perhaps parsecvs would be for git, or like git-svn for git.

3. Subprojects: how to manage project which depends on other externally
managed (third-party) project, and perhaps needs patches for it. Examples:
out of tree kernel patches + userspace tools, plugin for some program which
may need bugfixes, program which need some library, gitk before
incorporating into git,... Perhaps description of the whole sequence of
project development from add-on project (some new filesystem for Linux,
gitk) to being incorporated into bigger project (filesystem included in
Linux kernel, gitk in git repository).

4. Splitting repository: splitting one big project (X.org, Linux
distribution) into modules.

-- 
Jakub Narebski
Warsaw, Poland

Re: [RFC] Managing projects - advanced Git tutorial/walkthrough

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> I have browsed through Git documentation: "A tutorial introduction to
> git" (tutorial.txt), "A short git tutorial" (core-tutorial.txt) which
> contrary to the title is the tutorial in low-level git commands and is
> longer that the first one, "Everyday GIT With 20 Commands Or
> So" (everyday.txt) and "git for CVS users" (cvs-migration.txt) which does
> not mention git-blame and git-annotate.

I was initially somewhat dissapointed that a posting marked as
RFC did not contain a draft that is commentable, but we would
probably want to know how the updated document set will be
organized in general first.  There was a discussion both here
and on #irc, while Pasky and gang were working on the wiki,
about sprucing up the introductory documentation set.

The core-tutorial grow out of a short tutorial to start from
Plumbing basics (what's in object store) to cover Porcelainish;
when it was written there was not another user-level document,
so it had to cover both, but it is probably a good idea to move
the parts that talk about Porcelainish to other documents and
make it "A short tutorial on git Plumbing" document.  Maybe we
can have a tiered document set like this:

 - Your first experience with git with walkthru.  This shows the
   minimum basic operations to get started a stand-alone "hello
   world" project, without talking about index nor object store.
   The current tutorial.txt is probably good enough with
   updates.

 - Understanding git as an end user.  Currently, this is
   included in the global map git(7) documentation.  It might
   make sense to separate it out.  This should talk about
   concepts like blobs/trees/commits/trust/index without going
   into lowlevel details of the implementation.  The stress
   should be on what they are for, not operationally but
   philosophically.  What's currently in README would be
   suitable for this part, with some additional topics:

   - branches.  "Tying it all together" section talks about the
     single branch and "the HEAD state"; we should talk about
     why you would want to use multiple branches (either
     keeping track of your own development, or keeping track of
     somebody else's) and stress branches are to keep separate
     things separate (explained that way it becomes clear why
     you should not commit on a remote tracking branch).

   - ancestry traversal.  what "A..B" or "^A ^B C" means and why
     you would want to say them.

 - Everyday.

 - Special interests: cvs migration, howto/ documents.

 - The global map git(7) with pointers to individual commands,
   and the glossary.

 - Tutorial on Plumbing.

For a new end-user, the order to read would be from the top to
bottom.  "Everyday" should cover most of what are needed for
different classes of users, and other things can be looked up
from the global map.


I think tutorial.txt is the right "your first experience with
git with walkthru" document, and the materials it gives, and the
order in which it introduces them, are very well thought out;
kudos to JBF.  We might also want to show "git grep", but other
than that I do not think of anything that a new user might want
to use on the first day.

It is deliberately sketchy at times to keep the flow of walkthru
clean and simple, and I'd like to keep it that way.  I would
however like to see the examples to show the expected output
from the commands, like the initial part of the current
core-tutorial.txt does.  Also, I'd like to see a "see also" link
to each step that refers the user to "what if this step does not
work as expected for you", either separate document or a section
in the appendix part of the same document, without cluttering
the main text too much.

Some commands and syntax it mentions may need to be rethought in
the light what happened recently, especially the internal
version of diff and log/show/whatchanged unification that
happened before the 1.3.0 came out.

 * "git diff A B" should probably be spelled as "git diff A..B"
   throughout for consistency.

 * Today's "git log" is more powerful than the one we had when
   the tutorial was first written, and we probably want to
   recommend "git log [-p|--stat]" in place of whatchanged;
   whatchanged is kept primarily for historical reasons and to
   give a different default output format than log.  A new user
   does not have to even know about it.

Then reorganize the initial part core-tutorial.txt to match the
examples tutorial.txt gives, and demonstrate what is happening
under the hood.  The tutorial says "git init-db" then "git
add".  The core-tutorial would match that and explain what
happens when "git init-db" is run (creates .git/objects etc.)
and "git add" is run (populates the index).

Re: [RFC] Managing projects - advanced Git tutorial/walkthrough

[sean]

On Sat, 06 May 2006 13:09:03 -0700
Junio C Hamano <junkio@cox.net> wrote:

[...]
> I think tutorial.txt is the right "your first experience with
> git with walkthru" document, and the materials it gives, and the
> order in which it introduces them, are very well thought out;
> kudos to JBF.  We might also want to show "git grep", but other
> than that I do not think of anything that a new user might want
> to use on the first day.

It doesn't mention git log, show or status which are important
for the first day.  Also an example of git commit --amend would
be a nice touch.

Part of the problem people new to git are having arise by reading
documentation in the wrong order and coming to the conclusion that
git is an ugly beast.   Also many people are still finding out-of-
date information before anything else (eg. git isn't an scm only an
object tracker).

Part of this will be solved by having a useful and inviting web page
(thanks Pasky!).  But it would also help to rename core-tutorial.txt
to something that doesn't sound inviting to newbies.  Something
along the line of core-internal-design.txt (or here-be-dragons.txt).

Turning the main man page into more of a reference than a tutorial
slash concepts page would be something worth doing too.  Removing
all of the plumbing commands from that page should at least be
considered.

[...]

> Then reorganize the initial part core-tutorial.txt to match the
> examples tutorial.txt gives, and demonstrate what is happening
> under the hood.  The tutorial says "git init-db" then "git
> add".  The core-tutorial would match that and explain what
> happens when "git init-db" is run (creates .git/objects etc.)
> and "git add" is run (populates the index).
> 

There really seems to be a lot of room for another intermediate user
level document between tutorial.txt and the current core-tutorial.txt.
There are lots of concepts that can be explained without having to get
into the low level design or tools of git.  For example, a user could
have long been productive with git before ever having to learn about
read-tree/write-tree etc.. all those commands are more for porcelain
writers and git guru/experts now.

Sean

Re: [RFC] Managing projects - advanced Git tutorial/walkthrough

[J. Bruce Fields]

On Sat, May 06, 2006 at 01:09:03PM -0700, Junio C Hamano wrote:
>  - Understanding git as an end user.  Currently, this is
>    included in the global map git(7) documentation.  It might
>    make sense to separate it out.  This should talk about
>    concepts like blobs/trees/commits/trust/index without going
>    into lowlevel details of the implementation.  The stress
>    should be on what they are for, not operationally but
>    philosophically.  What's currently in README would be
>    suitable for this part, with some additional topics:

Yeah, I actually made a start at a sequel to tutorial.txt, with the goal
that after reading the sequel a user would have encountered the main
concepts necessary to read any of the man pages--mainly the object
database and the index file.  My work so far is in the
"advanced-tutorial" branch of

	git://linux-nfs.org/~bfields/exports/git.git

but it needs some cleaning up.

I was hoping I'd be able to replace some of the README or
core-tutorial.txt in the process, but the latter has a lot of
git-hacker-only detail in it, and the former is a bit more verbose and
has some motivation (explaining why stuff was designed the way it was)
that is nice but maybe not necessary for a minimal tutorial.

--b.