[doc] Remove gittutorial-2

[jvns]

This patch series removes gittutorial-2 and all references to it, leaving a stub behind to help out any users who might be looking for this documentation.

The goal is to remove obsolete documentation and make it easier to improve our tutorial material in the future.

I tested that the docs are staying internally consistent by running git grep tutorial-2 and making sure that the only remaining references are in the Makefiles, the document itself, and some example output in user-manual.adoc which isn't relevant to the actual manual.

Here's a pointer to a past discussion:

https://lore.kernel.org/git/7004c3b1-2100-4a90-9815-2a679ceb25b2@app.fastmail.com/T/#mf600063180d6239916e3fa6e9d33da86969547ec
cc: Tuomas Ahola taahol@utu.fi
cc: "Kristoffer Haugsbakk" kristofferhaugsbakk@fastmail.com

[dscho]

Delete gittutorial-2

Oh 😆 I read "Delete <stuff>" and, based on plenty of recent experience on GitHub, immediately assumed some troll or AI to have created one of those bogus "Delete README.md" or "Delete .github/workflows/main.yml" PRs 😉

[jvns]

/preview

[gitgitgadget]

Preview email sent as pull.2241.git.1790626730.gitgitgadget@gmail.com

[jvns]

/submit

[gitgitgadget]

Submitted as pull.2241.git.1790627122.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2241/jvns/delete-tutorial2-v1

To fetch this version to local tag pr-2241/jvns/delete-tutorial2-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2241/jvns/delete-tutorial2-v1

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> This patch series removes gittutorial-2 and all references to it, leaving a
> stub behind to help out any users who might be looking for this
> documentation.

Is this the "two series" approach you mentioned earlier?

There is no need to ensure that the new document that replaces the
old one covers everything the old one did.  After all, giving us a
clean slate and letting us choose what to cover (and, more
importantly, what not to cover) with fresh eyes to match the needs
of today's world is the whole point of redoing the tutorial
document.

So I personally feel it is OK to remove the old one, without
promising or even hinting at what in the new one that replaces it.
But we would want to see its replacement in the not-so-distant
future.

Also, we may want to decide what to do with gittutorial.  It is
short and reasonably sweet.  One old-fashioned thing that does not
exactly match today's prevalent usage patterns may be that it starts
tracking a new project from a tarball, but other than that, it may
not hurt to keep it around.  I do not know.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> Is this the "two series" approach you mentioned earlier?

The idea is that:

1. we delete gittutorial-2 (this series)
2. we delete gittutorial
3. we add a new gittutorial

We could also combine #2 and #3 into a single series.
I don't feel strongly about that and it might (as you mention below)
be better to wait to delete gittutorial until we have a replacement
ready to go.

> There is no need to ensure that the new document that replaces the
> old one covers everything the old one did.  After all, giving us a
> clean slate and letting us choose what to cover (and, more
> importantly, what not to cover) with fresh eyes to match the needs
> of today's world is the whole point of redoing the tutorial
> document.
>
> So I personally feel it is OK to remove the old one, without
> promising or even hinting at what in the new one that replaces it.
> But we would want to see its replacement in the not-so-distant
> future.

I'm not planning to replace gittutorial-2 since the material in it
is already covered by gitdatamodel and gitcore-tutorial.
Let me know if you disagree!

> Also, we may want to decide what to do with gittutorial.  It is
> short and reasonably sweet.  One old-fashioned thing that does not
> exactly match today's prevalent usage patterns may be that it starts
> tracking a new project from a tarball, but other than that, it may
> not hurt to keep it around.  I do not know.

We definitely want a tutorial that covers `git init`, `git add`, `git commit`,
etc. Any replacement would definitely cover those topics, but 
I don't see the value of having 2 such tutorials.
Why do you think it would be valuable to keep it around? It seems
like it would cause a lot of confusion to me.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> I'm not planning to replace gittutorial-2 since the material in it
> is already covered by gitdatamodel and gitcore-tutorial.
> Let me know if you disagree!

I realized it might be useful to summarize the content of
gittutorial-2 to give some context for this. It introduces these
commands and files as a way to learn Git's object model:

	git cat-file
        git ls-tree
	git ls-files --stage
	.git/objects
	.git/refs/head/*
	.git/HEAD

gitdatamodel explains the Git object model in a different way,
and gitcore-tutorial introduces these same commands in
more detail.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  Documentation/MyFirstObjectWalk.adoc |   2 +-
>  Documentation/git.adoc               |   2 +-
>  Documentation/gitcore-tutorial.adoc  |   1 -
>  Documentation/gitcvs-migration.adoc  |   2 +-
>  Documentation/gitglossary.adoc       |   1 -
>  Documentation/gittutorial-2.adoc     | 422 +--------------------------
>  Documentation/gittutorial.adoc       |  23 +-
>  command-list.txt                     |   1 -
>  po/bg.po                             |   3 -
>  po/ca.po                             |   4 -
>  po/de.po                             |   3 -
>  po/el.po                             |   4 -
>  po/es.po                             |   3 -
>  po/fr.po                             |   3 -
>  po/ga.po                             |   3 -
>  po/id.po                             |   3 -
>  po/it.po                             |   4 -
>  po/ko.po                             |   3 -
>  po/pl.po                             |   3 -
>  po/pt_PT.po                          |   4 -
>  po/ru.po                             |   3 -
>  po/sv.po                             |   3 -
>  po/tr.po                             |   3 -
>  po/uk.po                             |   3 -
>  po/vi.po                             |   3 -
>  po/zh_CN.po                          |   4 -
>  po/zh_TW.po                          |   4 -
>  27 files changed, 14 insertions(+), 503 deletions(-)

One thing I forgot to mention.

I think we try to stay out of the po/ directory unless the patch is
about updating translated text to catch up with translatable text
that was updated by code or doc changes.  IOW, unless you are
working on the patch set as a member of the l10n team, you do not
touch these files.  This is to avoid unnecessary churn and
burdening the l10n teams with synchronization pain.

The above is my understanding of the workflow agreed on by people
inside and outside the l10n group, but I'd like to double-check
with the i18n coordinator (Cc'ed).  If I understand correctly, the
recent workflow used by the l10n teams gives more autonomy to
individual teams than before, which may have changed the equation.

The removals we see in the diffstat touch lines in the early part
that appears in the manual page, namely ...

    gittutorial-2(7)
    ================

    NAME
    ----
    gittutorial-2 - A tutorial introduction to Git: part two

    SYNOPSIS

the string used for "NAME", and one of them looks like this:

        diff --git c/po/es.po w/po/es.po
        index aa1bb9bf90..dcdcbf5360 100644
        --- c/po/es.po
        +++ w/po/es.po
        @@ -14046,9 +14046,6 @@ msgstr "Montar un repositorio dentro de otro"
         msgid "A tutorial introduction to Git"
         msgstr "Un tutorial de introducción a Git"
        -msgid "A tutorial introduction to Git: part two"
        -msgstr "Un tutorial de introducción a Git: parte dos"
        -
         msgid "Git web interface (web frontend to Git repositories)"
         msgstr "Interfaz web Git (interfaz web para repositorios Git)"

I'd say a patch set like this one, which is not about updating the
localization, should just leave po/ intact, since the removal does
not help without a corresponding addition from the same "NAME" in the
file that replaces this "gittutorial-2", which reads like

    gittutorial-2(7)
    ================

    NAME
    ----
    gittutorial-2 - Obsolete tutorial

    SYNOPSIS

and as the patch set stands, we are leaving it to the l10n teams
anyway to add "Obsolete tutorial" to the set of translatable
strings.

Jiang Xin (i18n/l10n coordinator), what do you and the l10n teams
want to see in a patch like this one?

Thanks.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Junio C Hamano <gitster@pobox.com> writes:

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>>  Documentation/MyFirstObjectWalk.adoc |   2 +-
>>  Documentation/git.adoc               |   2 +-
>>  Documentation/gitcore-tutorial.adoc  |   1 -
>>  Documentation/gitcvs-migration.adoc  |   2 +-
>>  Documentation/gitglossary.adoc       |   1 -
>>  Documentation/gittutorial-2.adoc     | 422 +--------------------------
>>  Documentation/gittutorial.adoc       |  23 +-
>>  command-list.txt                     |   1 -
>>  po/bg.po                             |   3 -
>>  po/ca.po                             |   4 -
>>  po/de.po                             |   3 -
>>  po/el.po                             |   4 -
>>  po/es.po                             |   3 -
>>  po/fr.po                             |   3 -
>>  po/ga.po                             |   3 -
>>  po/id.po                             |   3 -
>>  po/it.po                             |   4 -
>>  po/ko.po                             |   3 -
>>  po/pl.po                             |   3 -
>>  po/pt_PT.po                          |   4 -
>>  po/ru.po                             |   3 -
>>  po/sv.po                             |   3 -
>>  po/tr.po                             |   3 -
>>  po/uk.po                             |   3 -
>>  po/vi.po                             |   3 -
>>  po/zh_CN.po                          |   4 -
>>  po/zh_TW.po                          |   4 -
>>  27 files changed, 14 insertions(+), 503 deletions(-)
>
> One thing I forgot to mention.

Sorry, but there was another.  With this merged, doc-lint seems to
fail and breaks 'seen'.

            ...
            LINT DOCSTYLE includes/cmd-config-section-all.adoc
        no link: gittutorial-2
        gmake[1]: *** [Makefile:537: lint-docs-manpages] Error 1
        gmake[1]: Leaving directory '/home/gitster/w/buildfarm/seen/Documentation'
        gmake: *** [Makefile:4003: check-docs] Error 2

[gitgitgadget]

Tuomas Ahola wrote on the Git mailing list (how to reply to this email):

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> wrote:

> This patch series removes gittutorial-2 and all references to it, leaving a
> stub behind to help out any users who might be looking for this
> documentation.
> 
> The goal is to remove obsolete documentation and make it easier to improve
> our tutorial material in the future.
> 

Thanks, that sounds great.

> I tested that the docs are staying internally consistent by running git grep
> tutorial-2 and making sure that the only remaining references are in the
> Makefiles, the document itself, and some example output in user-manual.adoc
> which isn't relevant to the actual manual.
> 
> Here's a pointer to a past discussion:
> 
> https://lore.kernel.org/git/7004c3b1-2100-4a90-9815-2a679ceb25b2@app.fastmail.com/T/#mf600063180d6239916e3fa6e9d33da86969547ec
> 
> Julia Evans (3):
>   [doc] Remove gittutorial-2
>   [doc] Remove references to gittutorial-2
>   [doc] Delete translations of gittutorial-2 description

Hmm, the normal format would be more like this:

	doc: remove gittutorial-2

Please note that the words in square brackets are dropped by git-am(1).  For
example, another patch series of yours is currently represented like this:

	$ git fetch https://github.com/gitster/git je/doc-merge-conflicts:je/doc-merge-conflicts 
	$ git shortlog origin/seen..je/doc-merge-conflicts 
	Julia Evans (7):
	      Add new gitmergeconflicts man page
	      git-merge: link to new merge conflicts guide
	      git-rebase: link to new merge conflicts guide
	      git-revert: link to new merge conflicts guide
	      git-cherry-pick: link to new merge conflicts guide
	      git-pull: link to new merge conflicts guide
	      ignore conflict markers in gitmergeconflicts.adoc

(And the fact that these are documentation patches is indeed something we would
like to preserve in the shortlog.)

--Tuomas

[gitgitgadget]

User Tuomas Ahola <taahol@utu.fi> has been added to the cc: list.

[gitgitgadget]

Tuomas Ahola wrote on the Git mailing list (how to reply to this email):

Junio C Hamano <gitster@pobox.com> wrote:

> Junio C Hamano <gitster@pobox.com> writes:
> 
> >
> > One thing I forgot to mention.
> 
> Sorry, but there was another.  With this merged, doc-lint seems to
> fail and breaks 'seen'.
> 
>             ...
>             LINT DOCSTYLE includes/cmd-config-section-all.adoc
>         no link: gittutorial-2
>         gmake[1]: *** [Makefile:537: lint-docs-manpages] Error 1
>         gmake[1]: Leaving directory '/home/gitster/w/buildfarm/seen/Documentation'
>         gmake: *** [Makefile:4003: check-docs] Error 2
> 

If we want to build gittutorial-2(7) as a manpage stub but to hide it in `git
help --guides`, we can squelch that linter error with a merge-fix:

diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh
index d4a1977ba6..db2a54116d 100755
--- a/Documentation/lint-manpages.sh
+++ b/Documentation/lint-manpages.sh
@@ -32,6 +32,7 @@ check_missing_docs () (
 		git-legacy-*) continue;;
 		git-?*--?* ) continue ;;
 		gitweb.conf) continue ;;
+		gittutorial-2) continue ;;
 		esac
 
 		if ! test -f "$v.adoc"

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans" <julia@jvns.ca> writes:

>> So I personally feel it is OK to remove the old one, without
>> promising or even hinting at what in the new one that replaces it.
>> But we would want to see its replacement in the not-so-distant
>> future.
>
> I'm not planning to replace gittutorial-2 since the material in it
> is already covered by gitdatamodel and gitcore-tutorial.

OK.  I didn't sense that from the proposed log messages for these
patches.  Sorry for my misunderstanding.

>> Also, we may want to decide what to do with gittutorial.  It is
>> short and reasonably sweet.  One old-fashioned thing that does not
>> exactly match today's prevalent usage patterns may be that it starts
>> tracking a new project from a tarball, but other than that, it may
>> not hurt to keep it around.  I do not know.
>
> We definitely want a tutorial that covers `git init`, `git add`, `git commit`,
> etc. Any replacement would definitely cover those topics, but 
> I don't see the value of having 2 such tutorials.

> Why do you think it would be valuable to keep it around? It seems
> like it would cause a lot of confusion to me.

You confuse me.

What do you mean by "it" in "keep it around"?  gittutorial.adoc?

If so you said it yourself, that we want to have a tutorial that
covers the basics like `git init` etc.

Or do you mean some other document, like gittutorial-2?  It would
have made sense to keep it while a replacement was being written, to
make comparison easier, *if* the goal were to make sure that the new
one covers everything the existing one covered, but we already
agreed that it is not the goal to salvage what is in gittutorial-2
(and that is why I personally feel it is OK to remove the old one
first).

Puzzled.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> Sorry, but there was another.  With this merged, doc-lint seems to
> fail and breaks 'seen'.
>
>             ...
>             LINT DOCSTYLE includes/cmd-config-section-all.adoc
>         no link: gittutorial-2
>         gmake[1]: *** [Makefile:537: lint-docs-manpages] Error 1
>         gmake[1]: Leaving directory 
> '/home/gitster/w/buildfarm/seen/Documentation'
>         gmake: *** [Makefile:4003: check-docs] Error 2

Weird, when I run `make lint-docs` on my branch it succeeds
(before merging it into `seen`). But I agree with you that
it fails when merged into `seen`. I'll try to figure out why.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> Hmm, the normal format would be more like this:
>
> 	doc: remove gittutorial-2
>
> Please note that the words in square brackets are dropped by git-am(1).  For
> example, another patch series of yours is currently represented like this:

Thanks, will fix. For some reason I thought the format I used when
I was working on this last year was `[doc]` but I was remembering wrong and
it was `doc: `, like you say.

[gitgitgadget]

"Kristoffer Haugsbakk" wrote on the Git mailing list (how to reply to this email):

On Wed, Sep 30, 2026, at 15:16, Julia Evans wrote:
>> Sorry, but there was another.  With this merged, doc-lint seems to
>> fail and breaks 'seen'.
>>
>>             ...
>>             LINT DOCSTYLE includes/cmd-config-section-all.adoc
>>         no link: gittutorial-2
>>         gmake[1]: *** [Makefile:537: lint-docs-manpages] Error 1
>>         gmake[1]: Leaving directory
>> '/home/gitster/w/buildfarm/seen/Documentation'
>>         gmake: *** [Makefile:4003: check-docs] Error 2
>
> Weird, when I run `make lint-docs` on my branch it succeeds
> (before merging it into `seen`). But I agree with you that
> it fails when merged into `seen`. I'll try to figure out why.

It looks like it’s because 4ce144a1 (lint-docs: check the guide list in 
command-list.txt, 2026-09-10) introduced `MAN_GUIDES`.

    diff --git Documentation/lint-manpages.sh Documentation/lint-manpages.sh
    index a0ea572382d..d4a1977ba6b 100755
    --- Documentation/lint-manpages.sh
    +++ Documentation/lint-manpages.sh
    @@ -1,21 +1,23 @@
    [...]
     check_missing_docs () (
            ret=0

    -	for v in $ALL_COMMANDS
    +	for v in $ALL_COMMANDS $MAN_GUIDES
            do

[gitgitgadget]

User "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> has been added to the cc: list.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Tuomas Ahola <taahol@utu.fi> writes:

>> Sorry, but there was another.  With this merged, doc-lint seems to
>> fail and breaks 'seen'.
>> 
>>             ...
>>             LINT DOCSTYLE includes/cmd-config-section-all.adoc
>>         no link: gittutorial-2
>>         gmake[1]: *** [Makefile:537: lint-docs-manpages] Error 1
>>         gmake[1]: Leaving directory '/home/gitster/w/buildfarm/seen/Documentation'
>>         gmake: *** [Makefile:4003: check-docs] Error 2
>> 
>
> If we want to build gittutorial-2(7) as a manpage stub but to hide it in `git
> help --guides`, we can squelch that linter error with a merge-fix:
>
> diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh
> index d4a1977ba6..db2a54116d 100755
> --- a/Documentation/lint-manpages.sh
> +++ b/Documentation/lint-manpages.sh
> @@ -32,6 +32,7 @@ check_missing_docs () (
>  		git-legacy-*) continue;;
>  		git-?*--?* ) continue ;;
>  		gitweb.conf) continue ;;
> +		gittutorial-2) continue ;;
>  		esac
>  
>  		if ! test -f "$v.adoc"

Great.  Will use that in future integration runs.

How close is your topic to 'next', by the way?  I think we have
already caught a few missing links since it was queued in 'seen',
and that should be enough to prove its worth.  Even so, that is
merely "we saw cases where it was useful" and neither "we know it
will not fire when it should not" and nor "we know it will always
fire when it should" (which is why we want to see a solid review).

What I am wondering is if Julia's topic should be built on top of
the ta/command-list-guides-sync-lint topic.  Perhaps it is a bad
idea and coping with merge-fix would be more flexible.

Thanks.

[gitgitgadget]

This branch is now known as je/doc-remove-gittutorial-2.

[gitgitgadget]

This patch series was integrated into seen via git@6eec129.

[gitgitgadget]

This patch series is no longer integrated into seen.

[gitgitgadget]

This patch series was integrated into seen via git@4ba36e9.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> You confuse me.
>
> What do you mean by "it" in "keep it around"?  gittutorial.adoc?
>
> If so you said it yourself, that we want to have a tutorial that
> covers the basics like `git init` etc.
>
> Or do you mean some other document, like gittutorial-2?  It would
> have made sense to keep it while a replacement was being written, to
> make comparison easier, *if* the goal were to make sure that the new
> one covers everything the existing one covered, but we already
> agreed that it is not the goal to salvage what is in gittutorial-2
> (and that is why I personally feel it is OK to remove the old one
> first).

Here's another attempt to explain! I think this whole sub-discussion
is not very relevant to `gittutorial-2` (the subject of this patch series) 
which should be deleted in any case. I would move this out to talk
about it separately but the mailing list is still tough for me to navigate.

Everything after this point is about `gittutorial.adoc` and about how
to manage the process of improving it.

Here are some facts, some of my opinions, and some options I see.
Apologies for the length :)

Facts:

1. The current `gittutorial` covers git init, git add, git commit, git diff, git
   log, git branch, git switch, git merge, git clone, git fetch, git pull, gitk,
   git remote add, git show, git reset --hard, git tag, git show, and git status,
   (and potentially more commands I missed)
2. My current `gittutorial` draft covers fewer topics: just
   git init, git add, git commit, git diff, git status git remote add, git push.
   Basically just how to make commits and push them to a remote.
   These tools on their own are enough for a user to back up their code or use Git to
   publish a website (for instance with Github Pages or Heroku RIP)
3. 22 people who are new to Git have tested the new draft so far
3.1. Several of the testers said in the post-tutorial survey that they wanted more
   information on branching and collaboration with Git. This was the most common
   "what do you wish this tutorial covered?" request.
3.2. Several of the testers also said that the new version is a lot of
   material, and they were not able to finish it because they didn't have time
4. Writing tutorial material is a lot of work, it will take time to do a good
   job of covering branching and collaboration

Opinions:

It's important for us to cover branching, collaboration, and how to restore
old work in our tutorial material. There are other topics too but these are the
most important.

It’s not realistic to expect new Git users to be able to learn what they need to
know about branching and collaboration from the “MANAGING BRANCHES” and “USING
GIT FOR COLLABORATION” sections of `gittutorial`. Two of the many issues are
that it starts talking about branches without explaining what they are, and it
teaches collaboration in the context of a multi-user system which is not how the
vast majority of users would collaborate. As far as I can tell it never explains
what a branch is in any way. My impression is that we all already agree that
this tutorial is not doing the job it needs to do in any case.

It's also probably unrealistic to merge a guide to branching at the same time as
the intro to `git commit` just because it's already so much work just to cover
the first parts effectively.

All of this together means we’re not in an ideal situation.

Options I see for dealing with this:

option 1: Refer folks to the contents of the current `gittutorial` (in some new
location?) to learn branching and collaboration. I think this is what you are
suggesting (?). I am not willing to do this because (as mentioned) the current
gittutorial is not a good way to learn those topics.

option 2: Ship the new tutorial without a guide to branching and collaboration,
with that to come later. Not ideal, but I think this is better than option 1,
since at least we are not pointing users to a tutorial that we know will not
help them.

option 3: Recommend some kind of external guide for now. We talked about this
before and I agree there are issues with maintainability etc.

option 4: Wait until we have a new tutorial on branching to merge any new
tutorial. This will take a very long time and it’ll be a lot more to review at
one time.

Right now option 2 is my preferred one of the options (which all have different
drawbacks)

best,
Julia

[gitgitgadget]

There was a status update in the "New Topics" section about the branch je/doc-remove-gittutorial-2 on the Git mailing list:

An outdated tutorial 'gittutorial-2' has been removed.

Expecting a reroll.
cf. <fea59b5f-11e9-4f86-b04e-346a3fe0a757@app.fastmail.com>
source: <pull.2241.git.1790627122.gitgitgadget@gmail.com>

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans" <julia@jvns.ca> writes:

> 3. 22 people who are new to Git have tested the new draft so far
> 3.1. Several of the testers said in the post-tutorial survey that they wanted more
>    information on branching and collaboration with Git. This was the most common
>    "what do you wish this tutorial covered?" request.
> 3.2. Several of the testers also said that the new version is a lot of
>    material, and they were not able to finish it because they didn't have time
> 4. Writing tutorial material is a lot of work, it will take time to do a good
>    job of covering branching and collaboration

Good info to share more widely around here.

> It's important for us to cover branching, collaboration, and how to restore
> old work in our tutorial material.

OK.

> option 1: Refer folks to the contents of the current `gittutorial` (in some new
> location?) to learn branching and collaboration. I think this is what you are
> suggesting (?).

Not at all.  If the material in the existing document is inadequate,
after examining why it is inadequate (e.g., perhaps it assumes
certain prerequisite knowledge or work experience that today's new
users are unlikely to have), we decide if we can salvage it or we
need to write from scratch.  It is very likely that it is the latter
case---otherwise we wouldn't be having this conversation to begin
with.

> option 2: Ship the new tutorial without a guide to branching and collaboration,
> with that to come later. Not ideal, but I think this is better than option 1,
> since at least we are not pointing users to a tutorial that we know will not
> help them.

I think this, #1, and #3 are essentially different sides of the the
same coin.  If gittutorial can fill the gap, we use it as a stop-gap
measure while we prepare a better one.  If it is so bad that it
would contaminate new users' minds, and they are better off learning
the hard way from more technical documentation and external books
instead of tutorial, we won't give them any stop-gap.  We may or may
not have external material we can recommend.