Remove gittutorial-2
cover Remove gittutorial-2
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/[email protected]/T/#mf600063180d6239916e3fa6e9d33da86969547ec
Julia Evans (3):
[doc] Remove gittutorial-2
[doc] Remove references to gittutorial-2 [doc] Delete translations of gittutorial-2 description
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(-)
base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2241%2Fjvns%2Fdelete-tutorial2-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2241/jvns/delete-tutorial2-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2241
Signature · 1 line
gitgitgadget
PATCH 1/3 Remove gittutorial-2
From: Julia Evans <[email protected]>
It hasn't been substantially updated for 20 years (see `git diff e31952da5c52a4c1:Documentation/tutorial-2.txt
0f8e75abebff0877:Documentation/gittutorial-2.adoc`)
and it's becoming out of date, for example:
- refs do not necessarily live in .git/refs
- we don't really call it "the index file" anymore, and we don't encourage users to think about the individual files in .git as much as we did 20 years ago
More importantly, this approach of introducing Git by learning about the contents of .git does not work for most people learning Git for the first time. It's interesting information for some people (maybe more advanced users or folks with a strong computer science background, for not appropriate for a general tutorial).
Right now gittutorial-2 is meant to be a logical sequel to gittutorial ("read gittutorial, then gittutorial-2"). Deleting gittutorial-2 means that we can more easily rewrite the main gittutorial (which is also not effective) in any way we want, without having to make sure that gittutorial-2 is the logical next step.
We have other documentation which can serve a similar purpose to tutorial-2 and isn't framed as a general tutorial appropriate for everyone.
Keep building the man page for now and leave behind a stub to redirect folks to those other documents.
--- Documentation/gittutorial-2.adoc | 422 +------------------------------ 1 file changed, 6 insertions(+), 416 deletions(-)
Documentation/gittutorial-2.adoc +6 -416
@@ -3,7 +3,7 @@ gittutorial-2(7) NAME ---- -gittutorial-2 - A tutorial introduction to Git: part two +gittutorial-2 - Obsolete tutorial SYNOPSIS --------
@@ -13,423 +13,13 @@ git * DESCRIPTION ----------- -You should work through linkgit:gittutorial[7] before reading this tutorial. +This tutorial has been deleted since it had become very stale. -The goal of this tutorial is to introduce two fundamental pieces of -Git's architecture--the object database and the index file--and to -provide the reader with everything necessary to understand the rest -of the Git documentation. +See linkgit:gitdatamodel[7] for an explanation of how Git's core data +structures work (objects, references and the index). -The Git object database ------------------------ - -Let's start a new project and create a small amount of history: - ------------------------------------------------- -$ mkdir test-project -$ cd test-project -$ git init -Initialized empty Git repository in .git/ -$ echo 'hello world' > file.txt -$ git add . -$ git commit -a -m "initial commit" -[master (root-commit) 54196cc] initial commit - 1 file changed, 1 insertion(+) - create mode 100644 file.txt -$ echo 'hello world!' >file.txt -$ git commit -a -m "add emphasis" -[master c4d59f3] add emphasis - 1 file changed, 1 insertion(+), 1 deletion(-) ------------------------------------------------- - -What are the 7 digits of hex that Git responded to the commit with? - -We saw in part one of the tutorial that commits have names like this. -It turns out that every object in the Git history is stored under -a 40-digit hex name. That name is the SHA-1 hash of the object's -contents; among other things, this ensures that Git will never store -the same data twice (since identical data is given an identical SHA-1 -name), and that the contents of a Git object will never change (since -that would change the object's name as well). The 7 char hex strings -here are simply the abbreviation of such 40 character long strings. -Abbreviations can be used everywhere where the 40 character strings -can be used, so long as they are unambiguous. - -It is expected that the content of the commit object you created while -following the example above generates a different SHA-1 hash than -the one shown above because the commit object records the time when -it was created and the name of the person performing the commit. - -We can ask Git about this particular object with the `cat-file` -command. Don't copy the 40 hex digits from this example but use those -from your own version. Note that you can shorten it to only a few -characters to save yourself typing all 40 hex digits: - ------------------------------------------------- -$ git cat-file -t 54196cc2 -commit -$ git cat-file commit 54196cc2 -tree 92b8b694ffb1675e5975148e1121810081dbdffe -author J. Bruce Fields <[email protected]> 1143414668 -0500 -committer J. Bruce Fields <[email protected]> 1143414668 -0500 - -initial commit ------------------------------------------------- - -A tree can refer to one or more "blob" objects, each corresponding to -a file. In addition, a tree can also refer to other tree objects, -thus creating a directory hierarchy. You can examine the contents of -any tree using ls-tree (remember that a long enough initial portion -of the SHA-1 will also work): - ------------------------------------------------- -$ git ls-tree 92b8b694 -100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt ------------------------------------------------- - -Thus we see that this tree has one file in it. The SHA-1 hash is a -reference to that file's data: - ------------------------------------------------- -$ git cat-file -t 3b18e512 -blob ------------------------------------------------- - -A "blob" is just file data, which we can also examine with cat-file: - ------------------------------------------------- -$ git cat-file blob 3b18e512 -hello world ------------------------------------------------- - -Note that this is the old file data; so the object that Git named in -its response to the initial tree was a tree with a snapshot of the -directory state that was recorded by the first commit. - -All of these objects are stored under their SHA-1 names inside the Git -directory: - ------------------------------------------------- -$ find .git/objects/ -.git/objects/ -.git/objects/pack -.git/objects/info -.git/objects/3b -.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad -.git/objects/92 -.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe -.git/objects/54 -.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7 -.git/objects/a0 -.git/objects/a0/423896973644771497bdc03eb99d5281615b51 -.git/objects/d0 -.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59 -.git/objects/c4 -.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241 ------------------------------------------------- - -and the contents of these files is just the compressed data plus a -header identifying their length and their type. The type is either a -blob, a tree, a commit, or a tag. - -The simplest commit to find is the HEAD commit, which we can find -from .git/HEAD: - ------------------------------------------------- -$ cat .git/HEAD -ref: refs/heads/master ------------------------------------------------- - -As you can see, this tells us which branch we're currently on, and it -tells us this by naming a file under the .git directory, which itself -contains a SHA-1 name referring to a commit object, which we can -examine with cat-file: - ------------------------------------------------- -$ cat .git/refs/heads/master -c4d59f390b9cfd4318117afde11d601c1085f241 -$ git cat-file -t c4d59f39 -commit -$ git cat-file commit c4d59f39 -tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59 -parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 -author J. Bruce Fields <[email protected]> 1143418702 -0500 -committer J. Bruce Fields <[email protected]> 1143418702 -0500 - -add emphasis ------------------------------------------------- - -The "tree" object here refers to the new state of the tree: - ------------------------------------------------- -$ git ls-tree d0492b36 -100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt -$ git cat-file blob a0423896 -hello world! ------------------------------------------------- - -and the "parent" object refers to the previous commit: - ------------------------------------------------- -$ git cat-file commit 54196cc2 -tree 92b8b694ffb1675e5975148e1121810081dbdffe -author J. Bruce Fields <[email protected]> 1143414668 -0500 -committer J. Bruce Fields <[email protected]> 1143414668 -0500 - -initial commit ------------------------------------------------- - -The tree object is the tree we examined first, and this commit is -unusual in that it lacks any parent. - -Most commits have only one parent, but it is also common for a commit -to have multiple parents. In that case the commit represents a -merge, with the parent references pointing to the heads of the merged -branches. - -Besides blobs, trees, and commits, the only remaining type of object -is a "tag", which we won't discuss here; refer to linkgit:git-tag[1] -for details. - -So now we know how Git uses the object database to represent a -project's history: - - * "commit" objects refer to "tree" objects representing the - snapshot of a directory tree at a particular point in the - history, and refer to "parent" commits to show how they're - connected into the project history. - * "tree" objects represent the state of a single directory, - associating directory names to "blob" objects containing file - data and "tree" objects containing subdirectory information. - * "blob" objects contain file data without any other structure. - * References to commit objects at the head of each branch are - stored in files under .git/refs/heads/. - * The name of the current branch is stored in .git/HEAD. - -Note, by the way, that lots of commands take a tree as an argument. -But as we can see above, a tree can be referred to in many different -ways--by the SHA-1 name for that tree, by the name of a commit that -refers to the tree, by the name of a branch whose head refers to that -tree, etc.--and most such commands can accept any of these names. - -In command synopses, the word "tree-ish" is sometimes used to -designate such an argument. - -The index file --------------- - -The primary tool we've been using to create commits is `git-commit --a`, which creates a commit including every change you've made to -your working tree. But what if you want to commit changes only to -certain files? Or only certain changes to certain files? - -If we look at the way commits are created under the cover, we'll see -that there are more flexible ways creating commits. - -Continuing with our test-project, let's modify file.txt again: - ------------------------------------------------- -$ echo "hello world, again" >>file.txt ------------------------------------------------- - -but this time instead of immediately making the commit, let's take an -intermediate step, and ask for diffs along the way to keep track of -what's happening: - ------------------------------------------------- -$ git diff ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again -$ git add file.txt -$ git diff ------------------------------------------------- - -The last diff is empty, but no new commits have been made, and the -head still doesn't contain the new line: - ------------------------------------------------- -$ git diff HEAD -diff --git a/file.txt b/file.txt -index a042389..513feba 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again ------------------------------------------------- - -So 'git diff' is comparing against something other than the head. -The thing that it's comparing against is actually the index file, -which is stored in .git/index in a binary format, but whose contents -we can examine with ls-files: - ------------------------------------------------- -$ git ls-files --stage -100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt -$ git cat-file -t 513feba2 -blob -$ git cat-file blob 513feba2 -hello world! -hello world, again ------------------------------------------------- - -So what our 'git add' did was store a new blob and then put -a reference to it in the index file. If we modify the file again, -we'll see that the new modifications are reflected in the 'git diff' -output: - ------------------------------------------------- -$ echo 'again?' >>file.txt -$ git diff -index 513feba..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1,2 +1,3 @@ - hello world! - hello world, again -+again? ------------------------------------------------- - -With the right arguments, 'git diff' can also show us the difference -between the working directory and the last commit, or between the -index and the last commit: - ------------------------------------------------- -$ git diff HEAD -diff --git a/file.txt b/file.txt -index a042389..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,3 @@ - hello world! -+hello world, again -+again? -$ git diff --cached -diff --git a/file.txt b/file.txt -index a042389..513feba 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again ------------------------------------------------- - -At any time, we can create a new commit using 'git commit' (without -the "-a" option), and verify that the state committed only includes the -changes stored in the index file, not the additional change that is -still only in our working tree: - ------------------------------------------------- -$ git commit -m "repeat" -$ git diff HEAD -diff --git a/file.txt b/file.txt -index 513feba..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1,2 +1,3 @@ - hello world! - hello world, again -+again? ------------------------------------------------- - -So by default 'git commit' uses the index to create the commit, not -the working tree; the "-a" option to commit tells it to first update -the index with all changes in the working tree. - -Finally, it's worth looking at the effect of 'git add' on the index -file: - ------------------------------------------------- -$ echo "goodbye, world" >closing.txt -$ git add closing.txt ------------------------------------------------- - -The effect of the 'git add' was to add one entry to the index file: - ------------------------------------------------- -$ git ls-files --stage -100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0 closing.txt -100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt ------------------------------------------------- - -And, as you can see with cat-file, this new entry refers to the -current contents of the file: - ------------------------------------------------- -$ git cat-file blob 8b9743b2 -goodbye, world ------------------------------------------------- - -The "status" command is a useful way to get a quick summary of the -situation: - ------------------------------------------------- -$ git status -On branch master -Changes to be committed: - (use "git restore --staged <file>..." to unstage) - - new file: closing.txt - -Changes not staged for commit: - (use "git add <file>..." to update what will be committed) - (use "git restore <file>..." to discard changes in working directory) - - modified: file.txt - ------------------------------------------------- - -Since the current state of closing.txt is cached in the index file, -it is listed as "Changes to be committed". Since file.txt has -changes in the working directory that aren't reflected in the index, -it is marked "changed but not updated". At this point, running "git -commit" would create a commit that added closing.txt (with its new -contents), but that didn't modify file.txt. - -Also, note that a bare `git diff` shows the changes to file.txt, but -not the addition of closing.txt, because the version of closing.txt -in the index file is identical to the one in the working directory. - -In addition to being the staging area for new commits, the index file -is also populated from the object database when checking out a -branch, and is used to hold the trees involved in a merge operation. -See linkgit:gitcore-tutorial[7] and the relevant man -pages for details. - -What next? ----------- - -At this point you should know everything necessary to read the man -pages for any of the git commands; one good place to start would be -with the commands mentioned in linkgit:giteveryday[7]. You -should be able to find any unknown jargon in linkgit:gitglossary[7]. - -The link:user-manual.html[Git User's Manual] provides a more -comprehensive introduction to Git. - -linkgit:gitcvs-migration[7] explains how to -import a CVS repository into Git, and shows how to use Git in a -CVS-like way. - -For some interesting examples of Git use, see the -link:howto-index.html[howtos]. - -For Git developers, linkgit:gitcore-tutorial[7] goes -into detail on the lower-level Git mechanisms involved in, for -example, creating a new commit. - -SEE ALSO --------- -linkgit:gittutorial[7], -linkgit:gitcvs-migration[7], -linkgit:gitcore-tutorial[7], -linkgit:gitglossary[7], -linkgit:git-help[1], -linkgit:giteveryday[7], -link:user-manual.html[The Git User's Manual] +See linkgit:gitcore-tutorial[7] for a practical tutorial on how to +explore Git's internals. GIT ---
Signature · 1 line
gitgitgadget
PATCH 2/3 Remove references to gittutorial-2
In reply to Julia Evans via GitGitGadgetFrom: Julia Evans <[email protected]>
Redirect folks to gitdatamodel instead, since every time it's referenced the intent is to explain objects, references, blobs, etc.
The update to gittutorial isn't very carefully thought through since we're planning to delete that entire document anyway. It's just there to maintain some internal consistency.
--- Documentation/MyFirstObjectWalk.adoc | 2 +- Documentation/git.adoc | 2 +- Documentation/gitcore-tutorial.adoc | 1 - Documentation/gitcvs-migration.adoc | 2 +- Documentation/gitglossary.adoc | 1 - Documentation/gittutorial.adoc | 23 +++++------------------ 6 files changed, 8 insertions(+), 23 deletions(-)
Documentation/MyFirstObjectWalk.adoc +1 -1
@@ -145,7 +145,7 @@ used to track the allocated size of the list. Per entry, we find: `item` is the object provided upon which to base the object walk. Items in Git -can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.adoc`.) +can be blobs, trees, commits, or tags. (See `Documentation/gitdatamodel.adoc`.) `name` is the object ID (OID) of the object - a hex string you may be familiar with from using Git to organize your source in the past. Check the tutorial
Documentation/git.adoc +1 -1
@@ -1200,7 +1200,7 @@ the Git Security mailing list <[email protected]>. SEE ALSO -------- -linkgit:gittutorial[7], linkgit:gittutorial-2[7], +linkgit:gittutorial[7], linkgit:giteveryday[7], linkgit:gitcvs-migration[7], linkgit:gitglossary[7], linkgit:gitdatamodel[7], linkgit:gitcore-tutorial[7], linkgit:gitcli[7],
Documentation/gitcore-tutorial.adoc +0 -1
@@ -1649,7 +1649,6 @@ to follow, not easier. SEE ALSO -------- linkgit:gittutorial[7], -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:git-help[1], linkgit:giteveryday[7],
Documentation/gitcvs-migration.adoc +1 -1
@@ -194,7 +194,7 @@ repositories without the need for a central maintainer. SEE ALSO -------- linkgit:gittutorial[7], -linkgit:gittutorial-2[7], +linkgit:gitdatamodel[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], linkgit:giteveryday[7],
Documentation/gitglossary.adoc +0 -1
@@ -18,7 +18,6 @@ SEE ALSO -------- linkgit:gitdatamodel[7], linkgit:gittutorial[7], -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:giteveryday[7], link:user-manual.html[The Git User's Manual]
Documentation/gittutorial.adoc +5 -18
@@ -622,24 +622,12 @@ Next Steps ---------- This tutorial should be enough to perform basic distributed revision -control for your projects. However, to fully understand the depth -and power of Git you need to understand two simple ideas on which it -is based: +control for your projects. However, to fully understand the Git +documentation, it's useful to learn how Git stores the history of +your project in its database. See linkgit:gitdatamodel[7] for an +explanation. - * The object database is the rather elegant system used to - store the history of your project--files, directories, and - commits. - - * The index file is a cache of the state of a directory tree, - used to create commits, check out working directories, and - hold the various trees involved in a merge. - -Part two of this tutorial explains the object -database, the index file, and a few other odds and ends that you'll -need to make the most of Git. You can find it at linkgit:gittutorial-2[7]. - -If you don't want to continue with that right away, a few other -digressions that may be interesting at this point are: +A few other commands that may be interesting: * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert series of git commits into emailed patches, and vice versa,
@@ -662,7 +650,6 @@ digressions that may be interesting at this point are: SEE ALSO -------- -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7],
Signature · 1 line
gitgitgadget
PATCH 3/3 Delete translations of gittutorial-2 description
In reply to Julia Evans via GitGitGadgetFrom: Julia Evans <[email protected]>
The tutorial has been deleted so we don't need the translations anymore.
Deleted them with sed like this to try to avoid making mistakes by deleting them manually, and then cleaned up the comments by hand sed -I '' '/msgid "A tutorial introduction to Git: part two"/,+2d' po/*.po
--- 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 ---- 20 files changed, 64 deletions(-)
command-list.txt +0 -1
@@ -244,7 +244,6 @@ gitrepository-layout userinterfaces gitrevisions userinterfaces gitsubmodules guide gittutorial guide -gittutorial-2 guide gitweb ancillaryinterrogators gitworkflows guide scalar mainporcelain
po/bg.po +0 -3
@@ -17097,9 +17097,6 @@ msgstr "Монтиране на едно хранилище в друго" msgid "A tutorial introduction to Git" msgstr "Въвеждащ урок за Git" -msgid "A tutorial introduction to Git: part two" -msgstr "Въвеждащ урок за Git: втора част" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Уеб интерфейс на Git"
po/ca.po +0 -4
@@ -20846,10 +20846,6 @@ msgstr "Muntant un repositori dins un altre" msgid "A tutorial introduction to Git" msgstr "Un tutorial d'introducció al Git" -#: command-list.h -msgid "A tutorial introduction to Git: part two" -msgstr "Un tutorial d'introducció al Git: segona part" - #: command-list.h msgid "Git web interface (web frontend to Git repositories)" msgstr "Interfície web del Git (interfície web pels repositoris Git)"
po/de.po +0 -3
@@ -15263,9 +15263,6 @@ msgstr "Einbinden eines Repositories in ein anderes" msgid "A tutorial introduction to Git" msgstr "eine einführende Anleitung zu Git" -msgid "A tutorial introduction to Git: part two" -msgstr "eine einführende Anleitung zu Git: Teil zwei" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Git Web Interface (Web-Frontend für Git-Repositories)"
po/el.po +0 -4
@@ -19747,10 +19747,6 @@ msgstr "" msgid "Specifying revisions and ranges for Git" msgstr "" -#: command-list.h:206 -msgid "A tutorial introduction to Git: part two" -msgstr "" - #: command-list.h:207 msgid "A tutorial introduction to Git" msgstr ""
po/es.po +0 -3
@@ -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)"
po/fr.po +0 -3
@@ -16698,9 +16698,6 @@ msgstr "Montage d'un dépôt dans un autre dépôt" msgid "A tutorial introduction to Git" msgstr "Une introduction pratique à Git" -msgid "A tutorial introduction to Git: part two" -msgstr "Une introduction pratique à Git : deuxième partie" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Interface web de Git"
po/ga.po +0 -3
@@ -16521,9 +16521,6 @@ msgstr "Stóra amháin a chur isteach taobh istigh de cheann" msgid "A tutorial introduction to Git" msgstr "Réamhrá teagaisc ar Git" -msgid "A tutorial introduction to Git: part two" -msgstr "Réamhrá teagaisc ar Git: cuid a dara" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Comhéadan gréasáin Git (tosaigh gréasáin chuig stórais Git)"
po/id.po +0 -3
@@ -20476,9 +20476,6 @@ msgid "A tutorial introduction to Git" msgstr "Tutorial perkenalan Git" #: command-list.h -msgid "A tutorial introduction to Git: part two" -msgstr "Tutorial perkenalan Git: bagian dua" - #: command-list.h msgid "Git web interface (web frontend to Git repositories)" msgstr "Antarmuka web Git (tampilan depan web untuk repositori Git)"
po/it.po +0 -4
@@ -24498,10 +24498,6 @@ msgstr "Come specificare revisioni e intervalli in Git" msgid "Mounting one repository inside another" msgstr "Monto un repository dentro un altro" -#: command-list.h:215 -msgid "A tutorial introduction to Git: part two" -msgstr "Un tutorial introduttivo per Git: seconda parte" - #: command-list.h:216 msgid "A tutorial introduction to Git" msgstr "Un tutorial introduttivo per Git"
po/ko.po +0 -3
@@ -15972,9 +15972,6 @@ msgid "Specifying revisions and ranges for Git" msgstr "깃의 리비전 및 범위를 지정하기" #: command-list.h:204 -msgid "A tutorial introduction to Git: part two" -msgstr "깃 따라하기 안내서: 2부" - #: command-list.h:205 msgid "A tutorial introduction to Git" msgstr "깃 따라하기 안내서"
po/pl.po +0 -3
@@ -25581,9 +25581,6 @@ msgid "Mounting one repository inside another" msgstr "Montowanie jednego repozytorium w drugim" #: command-list.h:216 -msgid "A tutorial introduction to Git: part two" -msgstr "Samouczek wprowadzenia do Gita: część druga" - #: command-list.h:217 msgid "A tutorial introduction to Git" msgstr "Samouczek wprowadzenia do Gita"
po/pt_PT.po +0 -4
@@ -25857,10 +25857,6 @@ msgstr "" msgid "A tutorial introduction to Git" msgstr "Um tutorial de introdução a Git" -#: command-list.h:217 -msgid "A tutorial introduction to Git: part two" -msgstr "Um tutorial de introdução a Git: parte dois" - #: command-list.h:218 msgid "Git web interface (web frontend to Git repositories)" msgstr "Interface web de Git (frontend web para repositórios Git)"
po/ru.po +0 -3
@@ -13866,9 +13866,6 @@ msgstr "" msgid "A tutorial introduction to Git" msgstr "Обучающее введение в Git" -msgid "A tutorial introduction to Git: part two" -msgstr "Обучающее введение в Git: часть вторая" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Веб интерфейс Git (веб-интерфейс для Git репозиториев)"
po/sv.po +0 -3
@@ -16194,9 +16194,6 @@ msgstr "Monterar ett arkiv inuti ett annat" msgid "A tutorial introduction to Git" msgstr "Introduktion till Git" -msgid "A tutorial introduction to Git: part two" -msgstr "Introduktion till Git: del två" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Git-webbgränssnitt (webbframända för Git-arkiv)"
po/tr.po +0 -3
@@ -16319,9 +16319,6 @@ msgstr "Bir depoyu bir başkasının içine bağlama" msgid "A tutorial introduction to Git" msgstr "Git'e giriş için bir öğretici" -msgid "A tutorial introduction to Git: part two" -msgstr "Git'e giriş için bir öğretici: Bölüm 2" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Git web arabirimi (Git depoları için web ön ucu)"
po/uk.po +0 -3
@@ -16509,9 +16509,6 @@ msgstr "Монтування одного сховища всередині ін msgid "A tutorial introduction to Git" msgstr "Навчальний вступ до Git" -msgid "A tutorial introduction to Git: part two" -msgstr "Навчальний вступ до Git: частина друга" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Веб-інтерфейс Git (веб-фронтенд до сховищ Git)"
po/vi.po +0 -3
@@ -15606,9 +15606,6 @@ msgstr "Gắn một kho chứa vào trong một cái khác" msgid "A tutorial introduction to Git" msgstr "Hướng dẫn cách dùng Git" -msgid "A tutorial introduction to Git: part two" -msgstr "Hướng dẫn cách dùng Git: phần hai" - msgid "Git web interface (web frontend to Git repositories)" msgstr "Giao diện Git trên nền web (ứng dụng web chạy trên kho Git)"
po/zh_CN.po +0 -4
@@ -20237,10 +20237,6 @@ msgstr "将一个仓库挂载到另一个仓库中" msgid "A tutorial introduction to Git" msgstr "Git 入门教程" -#: command-list.h -msgid "A tutorial introduction to Git: part two" -msgstr "Git 入门教程：第二部分" - #: command-list.h msgid "Git web interface (web frontend to Git repositories)" msgstr "Git Web 界面（Git 仓库的 Web 前端）"
po/zh_TW.po +0 -4
@@ -20095,10 +20095,6 @@ msgstr "在某個版本庫掛載某個版本庫" msgid "A tutorial introduction to Git" msgstr "一個 Git 教學" -#: command-list.h -msgid "A tutorial introduction to Git: part two" -msgstr "一個 Git 教學：第二部分" - #: command-list.h msgid "Git web interface (web frontend to Git repositories)" msgstr "Git web 介面（Git 版本庫的 web 前端）"
Signature · 1 line
gitgitgadget
Quoted 3 lines · Julia Evans via GitGitGadget
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.
Quoted 1 line
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.
Quoted 11 lines
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!
Quoted 5 lines
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.
Quoted 3 lines
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/HEADgitdatamodel explains the Git object model in a different way, and gitcore-tutorial introduces these same commands in more detail.
Quoted 7 lines · Julia Evans
Quoted 4 lines
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.
Quoted 6 lines
Quoted 5 lines
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.
Quoted 6 lines
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.
Quoted 8 lines
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 initetc.
Quoted 7 lines
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
Quoted 8 lines · Julia Evans
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.
Quoted 2 lines
It's important for us to cover branching, collaboration, and how to restore old work in our tutorial material.
OK.
Quoted 3 lines
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.
Quoted 4 lines
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.
Quoted 20 lines · Julia Evans via GitGitGadget
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 -
Quoted 8 lines
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
SYNOPSISthe 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
SYNOPSISand 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.
Quoted 31 lines · Junio C Hamano
Quoted 20 lines · Julia Evans via GitGitGadget
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 -Quoted 8 lines
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(-)
Quoted 1 line
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
Quoted 8 lines · Junio C Hamano
Quoted 2 lines · Junio C Hamano
One thing I forgot to mention.
Sorry, but there was another. With this merged, doc-lint seems to fail and breaks 'seen'.
Quoted 7 lines
...
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:
Documentation/lint-manpages.sh +1 -0
@@ -32,6 +32,7 @@ check_missing_docs () ( git-legacy-*) continue;; git-?*--?* ) continue ;; gitweb.conf) continue ;; + gittutorial-2) continue ;; esac if ! test -f "$v.adoc"
Quoted 19 lines · Tuomas Ahola
Quoted 10 lines
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 2If 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:Documentation/lint-manpages.sh +0
-0
Documentation/lint-manpages.sh check_missing_docs () ( · line 38
Quoted 7 lines
Documentation/lint-manpages.sh +1
-0@@ -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.
Quoted 11 lines
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.
Quoted 11 lines · Julia Evans
Quoted 10 lines
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
Quoted 3 lines
Weird, when I run
make lint-docson my branch it succeeds (before merging it intoseen). But I agree with you that it fails when merged intoseen. 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
doQuoted 7 lines · Julia Evans via GitGitGadget
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.
Quoted 5 lines
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.
Quoted 8 lines
Here's a pointer to a past discussion:
https://lore.kernel.org/git/[email protected]/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
Quoted 7 lines
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.
v2 cover Remove gittutorial-2
In reply to Julia Evans via GitGitGadgetThis 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.
Changes in v2:
* Remove changes to .po files (thanks to Junio)
* Reword commit messages to doc: ... (thanks to Tuomas)
To deal with the conflict with 4ce144a1 (which requires that all guides be listed in command-list.txt) I think we need to add another exception to lint-manpages.sh (like Tuomas said).
Julia Evans (2):
doc: remove gittutorial-2
doc: remove references to gittutorial-2
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 +- 7 files changed, 14 insertions(+), 439 deletions(-)
base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2241%2Fjvns%2Fdelete-tutorial2-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2241/jvns/delete-tutorial2-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2241
Range-diff vs v1:
1: 54404cd8df ! 1: 5fd36f91f0 [doc] Remove gittutorial-2
@@ Metadata
Author: Julia Evans <[email protected]>
## Commit message ##
- [doc] Remove gittutorial-2
+ doc: remove gittutorial-2
It hasn't been substantially updated for 20 years (see `git diff e31952da5c52a4c1:Documentation/tutorial-2.txt
2: a76819e3af ! 2: 68867aa3fc [doc] Remove references to gittutorial-2
@@ Metadata
Author: Julia Evans <[email protected]>
## Commit message ##
- [doc] Remove references to gittutorial-2
+ doc: remove references to gittutorial-2
Redirect folks to gitdatamodel instead, since every time it's referenced the intent is to explain objects, references, blobs, etc.
3: 017ca1346d < -: ---------- [doc] Delete translations of gittutorial-2 description
Signature · 1 line
gitgitgadget
PATCH v2 1/2 doc: remove gittutorial-2
From: Julia Evans <[email protected]>
It hasn't been substantially updated for 20 years (see `git diff e31952da5c52a4c1:Documentation/tutorial-2.txt
0f8e75abebff0877:Documentation/gittutorial-2.adoc`)
and it's becoming out of date, for example:
- refs do not necessarily live in .git/refs
- we don't really call it "the index file" anymore, and we don't encourage users to think about the individual files in .git as much as we did 20 years ago
More importantly, this approach of introducing Git by learning about the contents of .git does not work for most people learning Git for the first time. It's interesting information for some people (maybe more advanced users or folks with a strong computer science background, for not appropriate for a general tutorial).
Right now gittutorial-2 is meant to be a logical sequel to gittutorial ("read gittutorial, then gittutorial-2"). Deleting gittutorial-2 means that we can more easily rewrite the main gittutorial (which is also not effective) in any way we want, without having to make sure that gittutorial-2 is the logical next step.
We have other documentation which can serve a similar purpose to tutorial-2 and isn't framed as a general tutorial appropriate for everyone.
Keep building the man page for now and leave behind a stub to redirect folks to those other documents.
--- Documentation/gittutorial-2.adoc | 422 +------------------------------ 1 file changed, 6 insertions(+), 416 deletions(-)
Documentation/gittutorial-2.adoc +6 -416
@@ -3,7 +3,7 @@ gittutorial-2(7) NAME ---- -gittutorial-2 - A tutorial introduction to Git: part two +gittutorial-2 - Obsolete tutorial SYNOPSIS --------
@@ -13,423 +13,13 @@ git * DESCRIPTION ----------- -You should work through linkgit:gittutorial[7] before reading this tutorial. +This tutorial has been deleted since it had become very stale. -The goal of this tutorial is to introduce two fundamental pieces of -Git's architecture--the object database and the index file--and to -provide the reader with everything necessary to understand the rest -of the Git documentation. +See linkgit:gitdatamodel[7] for an explanation of how Git's core data +structures work (objects, references and the index). -The Git object database ------------------------ - -Let's start a new project and create a small amount of history: - ------------------------------------------------- -$ mkdir test-project -$ cd test-project -$ git init -Initialized empty Git repository in .git/ -$ echo 'hello world' > file.txt -$ git add . -$ git commit -a -m "initial commit" -[master (root-commit) 54196cc] initial commit - 1 file changed, 1 insertion(+) - create mode 100644 file.txt -$ echo 'hello world!' >file.txt -$ git commit -a -m "add emphasis" -[master c4d59f3] add emphasis - 1 file changed, 1 insertion(+), 1 deletion(-) ------------------------------------------------- - -What are the 7 digits of hex that Git responded to the commit with? - -We saw in part one of the tutorial that commits have names like this. -It turns out that every object in the Git history is stored under -a 40-digit hex name. That name is the SHA-1 hash of the object's -contents; among other things, this ensures that Git will never store -the same data twice (since identical data is given an identical SHA-1 -name), and that the contents of a Git object will never change (since -that would change the object's name as well). The 7 char hex strings -here are simply the abbreviation of such 40 character long strings. -Abbreviations can be used everywhere where the 40 character strings -can be used, so long as they are unambiguous. - -It is expected that the content of the commit object you created while -following the example above generates a different SHA-1 hash than -the one shown above because the commit object records the time when -it was created and the name of the person performing the commit. - -We can ask Git about this particular object with the `cat-file` -command. Don't copy the 40 hex digits from this example but use those -from your own version. Note that you can shorten it to only a few -characters to save yourself typing all 40 hex digits: - ------------------------------------------------- -$ git cat-file -t 54196cc2 -commit -$ git cat-file commit 54196cc2 -tree 92b8b694ffb1675e5975148e1121810081dbdffe -author J. Bruce Fields <[email protected]> 1143414668 -0500 -committer J. Bruce Fields <[email protected]> 1143414668 -0500 - -initial commit ------------------------------------------------- - -A tree can refer to one or more "blob" objects, each corresponding to -a file. In addition, a tree can also refer to other tree objects, -thus creating a directory hierarchy. You can examine the contents of -any tree using ls-tree (remember that a long enough initial portion -of the SHA-1 will also work): - ------------------------------------------------- -$ git ls-tree 92b8b694 -100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt ------------------------------------------------- - -Thus we see that this tree has one file in it. The SHA-1 hash is a -reference to that file's data: - ------------------------------------------------- -$ git cat-file -t 3b18e512 -blob ------------------------------------------------- - -A "blob" is just file data, which we can also examine with cat-file: - ------------------------------------------------- -$ git cat-file blob 3b18e512 -hello world ------------------------------------------------- - -Note that this is the old file data; so the object that Git named in -its response to the initial tree was a tree with a snapshot of the -directory state that was recorded by the first commit. - -All of these objects are stored under their SHA-1 names inside the Git -directory: - ------------------------------------------------- -$ find .git/objects/ -.git/objects/ -.git/objects/pack -.git/objects/info -.git/objects/3b -.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad -.git/objects/92 -.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe -.git/objects/54 -.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7 -.git/objects/a0 -.git/objects/a0/423896973644771497bdc03eb99d5281615b51 -.git/objects/d0 -.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59 -.git/objects/c4 -.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241 ------------------------------------------------- - -and the contents of these files is just the compressed data plus a -header identifying their length and their type. The type is either a -blob, a tree, a commit, or a tag. - -The simplest commit to find is the HEAD commit, which we can find -from .git/HEAD: - ------------------------------------------------- -$ cat .git/HEAD -ref: refs/heads/master ------------------------------------------------- - -As you can see, this tells us which branch we're currently on, and it -tells us this by naming a file under the .git directory, which itself -contains a SHA-1 name referring to a commit object, which we can -examine with cat-file: - ------------------------------------------------- -$ cat .git/refs/heads/master -c4d59f390b9cfd4318117afde11d601c1085f241 -$ git cat-file -t c4d59f39 -commit -$ git cat-file commit c4d59f39 -tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59 -parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 -author J. Bruce Fields <[email protected]> 1143418702 -0500 -committer J. Bruce Fields <[email protected]> 1143418702 -0500 - -add emphasis ------------------------------------------------- - -The "tree" object here refers to the new state of the tree: - ------------------------------------------------- -$ git ls-tree d0492b36 -100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt -$ git cat-file blob a0423896 -hello world! ------------------------------------------------- - -and the "parent" object refers to the previous commit: - ------------------------------------------------- -$ git cat-file commit 54196cc2 -tree 92b8b694ffb1675e5975148e1121810081dbdffe -author J. Bruce Fields <[email protected]> 1143414668 -0500 -committer J. Bruce Fields <[email protected]> 1143414668 -0500 - -initial commit ------------------------------------------------- - -The tree object is the tree we examined first, and this commit is -unusual in that it lacks any parent. - -Most commits have only one parent, but it is also common for a commit -to have multiple parents. In that case the commit represents a -merge, with the parent references pointing to the heads of the merged -branches. - -Besides blobs, trees, and commits, the only remaining type of object -is a "tag", which we won't discuss here; refer to linkgit:git-tag[1] -for details. - -So now we know how Git uses the object database to represent a -project's history: - - * "commit" objects refer to "tree" objects representing the - snapshot of a directory tree at a particular point in the - history, and refer to "parent" commits to show how they're - connected into the project history. - * "tree" objects represent the state of a single directory, - associating directory names to "blob" objects containing file - data and "tree" objects containing subdirectory information. - * "blob" objects contain file data without any other structure. - * References to commit objects at the head of each branch are - stored in files under .git/refs/heads/. - * The name of the current branch is stored in .git/HEAD. - -Note, by the way, that lots of commands take a tree as an argument. -But as we can see above, a tree can be referred to in many different -ways--by the SHA-1 name for that tree, by the name of a commit that -refers to the tree, by the name of a branch whose head refers to that -tree, etc.--and most such commands can accept any of these names. - -In command synopses, the word "tree-ish" is sometimes used to -designate such an argument. - -The index file --------------- - -The primary tool we've been using to create commits is `git-commit --a`, which creates a commit including every change you've made to -your working tree. But what if you want to commit changes only to -certain files? Or only certain changes to certain files? - -If we look at the way commits are created under the cover, we'll see -that there are more flexible ways creating commits. - -Continuing with our test-project, let's modify file.txt again: - ------------------------------------------------- -$ echo "hello world, again" >>file.txt ------------------------------------------------- - -but this time instead of immediately making the commit, let's take an -intermediate step, and ask for diffs along the way to keep track of -what's happening: - ------------------------------------------------- -$ git diff ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again -$ git add file.txt -$ git diff ------------------------------------------------- - -The last diff is empty, but no new commits have been made, and the -head still doesn't contain the new line: - ------------------------------------------------- -$ git diff HEAD -diff --git a/file.txt b/file.txt -index a042389..513feba 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again ------------------------------------------------- - -So 'git diff' is comparing against something other than the head. -The thing that it's comparing against is actually the index file, -which is stored in .git/index in a binary format, but whose contents -we can examine with ls-files: - ------------------------------------------------- -$ git ls-files --stage -100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt -$ git cat-file -t 513feba2 -blob -$ git cat-file blob 513feba2 -hello world! -hello world, again ------------------------------------------------- - -So what our 'git add' did was store a new blob and then put -a reference to it in the index file. If we modify the file again, -we'll see that the new modifications are reflected in the 'git diff' -output: - ------------------------------------------------- -$ echo 'again?' >>file.txt -$ git diff -index 513feba..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1,2 +1,3 @@ - hello world! - hello world, again -+again? ------------------------------------------------- - -With the right arguments, 'git diff' can also show us the difference -between the working directory and the last commit, or between the -index and the last commit: - ------------------------------------------------- -$ git diff HEAD -diff --git a/file.txt b/file.txt -index a042389..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,3 @@ - hello world! -+hello world, again -+again? -$ git diff --cached -diff --git a/file.txt b/file.txt -index a042389..513feba 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again ------------------------------------------------- - -At any time, we can create a new commit using 'git commit' (without -the "-a" option), and verify that the state committed only includes the -changes stored in the index file, not the additional change that is -still only in our working tree: - ------------------------------------------------- -$ git commit -m "repeat" -$ git diff HEAD -diff --git a/file.txt b/file.txt -index 513feba..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1,2 +1,3 @@ - hello world! - hello world, again -+again? ------------------------------------------------- - -So by default 'git commit' uses the index to create the commit, not -the working tree; the "-a" option to commit tells it to first update -the index with all changes in the working tree. - -Finally, it's worth looking at the effect of 'git add' on the index -file: - ------------------------------------------------- -$ echo "goodbye, world" >closing.txt -$ git add closing.txt ------------------------------------------------- - -The effect of the 'git add' was to add one entry to the index file: - ------------------------------------------------- -$ git ls-files --stage -100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0 closing.txt -100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt ------------------------------------------------- - -And, as you can see with cat-file, this new entry refers to the -current contents of the file: - ------------------------------------------------- -$ git cat-file blob 8b9743b2 -goodbye, world ------------------------------------------------- - -The "status" command is a useful way to get a quick summary of the -situation: - ------------------------------------------------- -$ git status -On branch master -Changes to be committed: - (use "git restore --staged <file>..." to unstage) - - new file: closing.txt - -Changes not staged for commit: - (use "git add <file>..." to update what will be committed) - (use "git restore <file>..." to discard changes in working directory) - - modified: file.txt - ------------------------------------------------- - -Since the current state of closing.txt is cached in the index file, -it is listed as "Changes to be committed". Since file.txt has -changes in the working directory that aren't reflected in the index, -it is marked "changed but not updated". At this point, running "git -commit" would create a commit that added closing.txt (with its new -contents), but that didn't modify file.txt. - -Also, note that a bare `git diff` shows the changes to file.txt, but -not the addition of closing.txt, because the version of closing.txt -in the index file is identical to the one in the working directory. - -In addition to being the staging area for new commits, the index file -is also populated from the object database when checking out a -branch, and is used to hold the trees involved in a merge operation. -See linkgit:gitcore-tutorial[7] and the relevant man -pages for details. - -What next? ----------- - -At this point you should know everything necessary to read the man -pages for any of the git commands; one good place to start would be -with the commands mentioned in linkgit:giteveryday[7]. You -should be able to find any unknown jargon in linkgit:gitglossary[7]. - -The link:user-manual.html[Git User's Manual] provides a more -comprehensive introduction to Git. - -linkgit:gitcvs-migration[7] explains how to -import a CVS repository into Git, and shows how to use Git in a -CVS-like way. - -For some interesting examples of Git use, see the -link:howto-index.html[howtos]. - -For Git developers, linkgit:gitcore-tutorial[7] goes -into detail on the lower-level Git mechanisms involved in, for -example, creating a new commit. - -SEE ALSO --------- -linkgit:gittutorial[7], -linkgit:gitcvs-migration[7], -linkgit:gitcore-tutorial[7], -linkgit:gitglossary[7], -linkgit:git-help[1], -linkgit:giteveryday[7], -link:user-manual.html[The Git User's Manual] +See linkgit:gitcore-tutorial[7] for a practical tutorial on how to +explore Git's internals. GIT ---
Signature · 1 line
gitgitgadget
Re: [PATCH v2 1/2] doc: remove gittutorial-2
Quoted 8 lines · Julia Evans via GitGitGadget
From: Julia Evans <[email protected]>
[snip]More importantly, this approach of introducing Git by learning about the contents of
.gitdoes not work for most people learning Git for the first time. It's interesting information for some people (maybe more advanced users or folks with a strong computer science background, for not appropriate for a general tutorial).
for not?
), but not appropriate
PATCH v2 2/2 doc: remove references to gittutorial-2
In reply to Julia Evans via GitGitGadgetFrom: Julia Evans <[email protected]>
Redirect folks to gitdatamodel instead, since every time it's referenced the intent is to explain objects, references, blobs, etc.
The update to gittutorial isn't very carefully thought through since we're planning to delete that entire document anyway. It's just there to maintain some internal consistency.
--- Documentation/MyFirstObjectWalk.adoc | 2 +- Documentation/git.adoc | 2 +- Documentation/gitcore-tutorial.adoc | 1 - Documentation/gitcvs-migration.adoc | 2 +- Documentation/gitglossary.adoc | 1 - Documentation/gittutorial.adoc | 23 +++++------------------ 6 files changed, 8 insertions(+), 23 deletions(-)
Documentation/MyFirstObjectWalk.adoc +1 -1
@@ -145,7 +145,7 @@ used to track the allocated size of the list. Per entry, we find: `item` is the object provided upon which to base the object walk. Items in Git -can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.adoc`.) +can be blobs, trees, commits, or tags. (See `Documentation/gitdatamodel.adoc`.) `name` is the object ID (OID) of the object - a hex string you may be familiar with from using Git to organize your source in the past. Check the tutorial
Documentation/git.adoc +1 -1
@@ -1200,7 +1200,7 @@ the Git Security mailing list <[email protected]>. SEE ALSO -------- -linkgit:gittutorial[7], linkgit:gittutorial-2[7], +linkgit:gittutorial[7], linkgit:giteveryday[7], linkgit:gitcvs-migration[7], linkgit:gitglossary[7], linkgit:gitdatamodel[7], linkgit:gitcore-tutorial[7], linkgit:gitcli[7],
Documentation/gitcore-tutorial.adoc +0 -1
@@ -1649,7 +1649,6 @@ to follow, not easier. SEE ALSO -------- linkgit:gittutorial[7], -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:git-help[1], linkgit:giteveryday[7],
Documentation/gitcvs-migration.adoc +1 -1
@@ -194,7 +194,7 @@ repositories without the need for a central maintainer. SEE ALSO -------- linkgit:gittutorial[7], -linkgit:gittutorial-2[7], +linkgit:gitdatamodel[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], linkgit:giteveryday[7],
Documentation/gitglossary.adoc +0 -1
@@ -18,7 +18,6 @@ SEE ALSO -------- linkgit:gitdatamodel[7], linkgit:gittutorial[7], -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:giteveryday[7], link:user-manual.html[The Git User's Manual]
Documentation/gittutorial.adoc +5 -18
@@ -622,24 +622,12 @@ Next Steps ---------- This tutorial should be enough to perform basic distributed revision -control for your projects. However, to fully understand the depth -and power of Git you need to understand two simple ideas on which it -is based: +control for your projects. However, to fully understand the Git +documentation, it's useful to learn how Git stores the history of +your project in its database. See linkgit:gitdatamodel[7] for an +explanation. - * The object database is the rather elegant system used to - store the history of your project--files, directories, and - commits. - - * The index file is a cache of the state of a directory tree, - used to create commits, check out working directories, and - hold the various trees involved in a merge. - -Part two of this tutorial explains the object -database, the index file, and a few other odds and ends that you'll -need to make the most of Git. You can find it at linkgit:gittutorial-2[7]. - -If you don't want to continue with that right away, a few other -digressions that may be interesting at this point are: +A few other commands that may be interesting: * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert series of git commits into emailed patches, and vice versa,
@@ -662,7 +650,6 @@ digressions that may be interesting at this point are: SEE ALSO -------- -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7],
Signature · 1 line
gitgitgadget
Quoted 17 lines · Julia Evans via GitGitGadget
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.
Changes in v2:
* Remove changes to .po files (thanks to Junio)
* Reword commit messages to doc: ... (thanks to Tuomas)
Quoted 7 lines
To deal with the conflict with
4ce144a1(which requires that all guides be listed in command-list.txt) I think we need to add another exception tolint-manpages.sh(like Tuomas said).Julia Evans (2):
doc: remove gittutorial-2
doc: remove references to gittutorial-2
The titles of this round looks much better ;-).
Will replace. Let me mark the topic for 'next'.
Thanks.
Quoted 12 lines · Julia Evans via GitGitGadget
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.
Quoted 9 lines
Changes in v2:
* Remove changes to .po files (thanks to Junio)
* Reword commit messages to doc: ... (thanks to Tuomas)To deal with the conflict with
4ce144a1(which requires that all guides be listed in command-list.txt) I think we need to add another exception tolint-manpages.sh(like Tuomas said).
Excluding the po/ stuff, the v1->v2 interdiff looks like this:
$ git diff je/doc-remove-gittutorial-2@{1} je/doc-remove-gittutorial-2 -- ':!po/'command-list.txt +1 -0
@@ -244,6 +244,7 @@ gitrepository-layout userinterfaces gitrevisions userinterfaces gitsubmodules guide gittutorial guide +gittutorial-2 guide gitweb ancillaryinterrogators gitworkflows guide scalar mainporcelain
That, as can be guessed, causes git(1) to advertize this "obsolete tutorial". Perhaps we would like to avoid that.
$ (cd Documentation/ && ./doc-diff je/doc-remove-gittutorial-2@{1} je/doc-remove-gittutorial-2)0bf477ce01b45853195f5f3da63642712dc35579/home/taahol/share/man/man1/git.1 renamed from 7da429d7fb86fe400c48984ea1506a9e0477e80e/home/taahol/share/man/man1/git.1 +3 -0
@@ -800,6 +800,9 @@ GUIDES gittutorial(7) A tutorial introduction to Git. + gittutorial-2(7) + Obsolete tutorial. + gitworkflows(7) An overview of recommended workflows with Git.
And let's not worry about that exception you mentioned. After this topic hits 'next', I can rebase mine on top on of this, and deal with all necessary integration work.
Thanks!
Quoted 45 lines · Tuomas Ahola
Quoted 9 lines
Changes in v2:
* Remove changes to .po files (thanks to Junio)
* Reword commit messages to doc: ... (thanks to Tuomas)To deal with the conflict with
4ce144a1(which requires that all guides be listed in command-list.txt) I think we need to add another exception tolint-manpages.sh(like Tuomas said).Excluding the po/ stuff, the
v1->v2interdiff looks like this:$ git diff je/doc-remove-gittutorial-2@{1} je/doc-remove-gittutorial-2 -- ':!po/'command-list.txt +1
-0@@ -244,6 +244,7 @@ gitrepository-layout userinterfaces gitrevisions userinterfaces gitsubmodules guide gittutorial guide +gittutorial-2 guide gitweb ancillaryinterrogators gitworkflows guide scalar mainporcelainThat, as can be guessed, causes git(1) to advertize this "obsolete tutorial". Perhaps we would like to avoid that.
$ (cd Documentation/ && ./doc-diff je/doc-remove-gittutorial-2@{1} je/doc-remove-gittutorial-2)0bf477ce01b45853195f5f3da63642712dc35579/home/taahol/share/man/man1/git.1 renamed from 7da429d7fb86fe400c48984ea1506a9e0477e80e/home/taahol/share/man/man1/git.1 +3
-0@@ -800,6 +800,9 @@ GUIDES gittutorial(7) A tutorial introduction to Git. + gittutorial-2(7) + Obsolete tutorial. + gitworkflows(7) An overview of recommended workflows with Git.
Quoted 3 lines
And let's not worry about that exception you mentioned. After this topic hits 'next', I can rebase mine on top on of this, and deal with all necessary integration work.
OK. So ...
- I'll tentatively eject both topics out of my tree,
- Julia will send in a replacement that does not add gittutorial-2 to the command-list, which will be merged to 'next',
- and then your topic will be queued again with an evil merge (by me) to add gittutorial-2 back to the command-list file.
... and both topics will be happy?
Quoted 10 lines · Junio C Hamano
Quoted 3 lines · Tuomas Ahola
And let's not worry about that exception you mentioned. After this topic hits 'next', I can rebase mine on top on of this, and deal with all necessary integration work.
OK. So ...
- I'll tentatively eject both topics out of my tree,
Quoted 7 lines
- Julia will send in a replacement that does not add gittutorial-2 to the command-list, which will be merged to 'next',
- and then your topic will be queued again with an evil merge (by me) to add gittutorial-2 back to the command-list file.
... and both topics will be happy?
With an evil merge, or by stacking my topic on top of Julia's---which I think is the cleaner solution because that way I can add gt-2 as a linter exemption in the patch itself and explain it in the commit message.
And if "back to the command-list file" wasn't just a thinko, then no, I don't see that gt-2 should be re-added to command-list.txt.
Quoted 3 lines · Tuomas Ahola
With an evil merge, or by stacking my topic on top of Julia's---which I think is the cleaner solution because that way I can add gt-2 as a linter exemption in the patch itself and explain it in the commit message.
OK, then I'll use a synthetic base (i.e., not directly on 'master' or 'maint', but topic(s) by others merged to a more natural base) when queuing your rerolled patch.
Thanks.
Quoted 20 lines · Junio C Hamano
Quoted 10 lines · Tuomas Ahola
gittutorial(7)
A tutorial introduction to Git.0bf477ce01b45853195f5f3da63642712dc35579/home/taahol/share/man/man1/git.1 renamed from 7da429d7fb86fe400c48984ea1506a9e0477e80e/home/taahol/share/man/man1/git.1 +3
-0+ gittutorial-2(7) + Obsolete tutorial. + gitworkflows(7) An overview of recommended workflows with Git.Quoted 3 lines
And let's not worry about that exception you mentioned. After this topic hits 'next', I can rebase mine on top on of this, and deal with all necessary integration work.
OK. So ...
- I'll tentatively eject both topics out of my tree,
Quoted 8 lines
- Julia will send in a replacement that does not add gittutorial-2 to the command-list, which will be merged to 'next',
- and then your topic will be queued again with an evil merge (by me) to add gittutorial-2 back to the command-list file.
... and both topics will be happy?
This topic has graduated to 'master', so we should be more than ready for the last bullet point. Please pick up the rerolled ta/command-list-guides-sync-lint at <[email protected]>.
$ git cherry -v origin/seen ta/command-list-guides-sync-lint + 9a1ba61ac0e4491a4f028250be478cfcf05c9ef4 command-list.txt: add gitformat-loose(5) and gitpacking(7) + 5d36d7585956d17172012c8e42d77597524708e8 lint-docs: check the guide list in command-list.txt
--Tuomas
Quoted 19 lines · Tuomas Ahola
Quoted 12 lines · Junio C Hamano
Quoted 10 lines · Tuomas Ahola
gittutorial(7)
A tutorial introduction to Git.0bf477ce01b45853195f5f3da63642712dc35579/home/taahol/share/man/man1/git.1 renamed from 7da429d7fb86fe400c48984ea1506a9e0477e80e/home/taahol/share/man/man1/git.1 +3
-0+ gittutorial-2(7) + Obsolete tutorial. + gitworkflows(7) An overview of recommended workflows with Git.Quoted 4 lines
Quoted 3 lines
And let's not worry about that exception you mentioned. After this topic hits 'next', I can rebase mine on top on of this, and deal with all necessary integration work.
...
Quoted 7 lines
This topic has graduated to 'master', so we should be more than ready for the last bullet point. Please pick up the rerolled ta/command-list-guides-sync-lint at <[email protected]>.
$ git cherry -v origin/seen ta/command-list-guides-sync-lint + 9a1ba61ac0e4491a4f028250be478cfcf05c9ef4 command-list.txt: add gitformat-loose(5) and gitpacking(7) + 5d36d7585956d17172012c8e42d77597524708e8 lint-docs: check the guide list in command-list.txt
Sorry, I have no idea what you are trying to say with that "git cherry" output.
Earlier you said "I can rebase mine on top". Is the patch <[email protected]> the result of such rebasing?
Quoted 25 lines · Junio C Hamano
Quoted 23 lines · Tuomas Ahola
Quoted 12 lines · Junio C Hamano
Quoted 10 lines · Tuomas Ahola
gittutorial(7)
A tutorial introduction to Git.0bf477ce01b45853195f5f3da63642712dc35579/home/taahol/share/man/man1/git.1 renamed from 7da429d7fb86fe400c48984ea1506a9e0477e80e/home/taahol/share/man/man1/git.1 +3
-0+ gittutorial-2(7) + Obsolete tutorial. + gitworkflows(7) An overview of recommended workflows with Git.Quoted 4 lines
Quoted 3 lines
And let's not worry about that exception you mentioned. After this topic hits 'next', I can rebase mine on top on of this, and deal with all necessary integration work.
...
This topic has graduated to 'master', so we should be more than ready for the last bullet point. Please pick up the rerolled ta/command-list-guides-sync-lint at <[email protected]>.
Quoted 7 lines
Quoted 3 lines
$ git cherry -v origin/seen ta/command-list-guides-sync-lint + 9a1ba61ac0e4491a4f028250be478cfcf05c9ef4 command-list.txt: add gitformat-loose(5) and gitpacking(7) + 5d36d7585956d17172012c8e42d77597524708e8 lint-docs: check the guide list in command-list.txtSorry, I have no idea what you are trying to say with that "git cherry" output.
Just double-checked that the topic is not in 'seen' (the lines are plus-marked).
Quoted 2 lines
Earlier you said "I can rebase mine on top". Is the patch <[email protected]> the result of such rebasing?
Yes it is.
Quoted 12 lines · Tuomas Ahola
Quoted 11 lines
Quoted 7 lines
This topic has graduated to 'master', so we should be more than ready for the last bullet point. Please pick up the rerolled ta/command-list-guides-sync-lint at <[email protected]>.
$ git cherry -v origin/seen ta/command-list-guides-sync-lint + 9a1ba61ac0e4491a4f028250be478cfcf05c9ef4 command-list.txt: add gitformat-loose(5) and gitpacking(7) + 5d36d7585956d17172012c8e42d77597524708e8 lint-docs: check the guide list in command-list.txtSorry, I have no idea what you are trying to say with that "git cherry" output.
Quoted 7 lines
Just double-checked that the topic is not in 'seen' (the lines are plus-marked).
Quoted 2 lines
Earlier you said "I can rebase mine on top". Is the patch <[email protected]> the result of such rebasing?
Yes it is.
Thanks. From a cursory read, it seems that the thread has a review comment by Julia which wasn't really answered yet. Is it ready to be picked up?
Quoted 18 lines
$ git diff je/doc-remove-gittutorial-2@{1} je/doc-remove-gittutorial-2 -- ':!po/'command-list.txt +0
-0@@ -244,6 +244,7 @@ gitrepository-layoutuserinterfaces
gitrevisions userinterfaces gitsubmodules guide gittutorial guide +gittutorial-2 guide gitweb ancillaryinterrogators gitworkflows guide scalar mainporcelain
Quoted 2 lines
That, as can be guessed, causes git(1) to advertize this "obsolete tutorial". Perhaps we would like to avoid that.
Agreed that we shouldn't advertise an obsolete tutorial. I'll remove it from command-list.txt on my branch and submit a v3.
Quoted 18 lines · Julia Evans
Quoted 18 lines
$ git diff je/doc-remove-gittutorial-2@{1} je/doc-remove-gittutorial-2 -- ':!po/'command-list.txt +0
-0@@ -244,6 +244,7 @@ gitrepository-layoutuserinterfaces
gitrevisions userinterfaces gitsubmodules guide gittutorial guide +gittutorial-2 guide gitweb ancillaryinterrogators gitworkflows guide scalar mainporcelain
Quoted 5 lines
Quoted 2 lines
That, as can be guessed, causes git(1) to advertize this "obsolete tutorial". Perhaps we would like to avoid that.
Agreed that we shouldn't advertise an obsolete tutorial. I'll remove it from
command-list.txton my branch and submit a v3.
Just a friendly *ping*. :-)
--Tuomas
Quoted 20 lines · Tuomas Ahola
Quoted 18 lines · Julia Evans
Quoted 18 lines
$ git diff je/doc-remove-gittutorial-2@{1} je/doc-remove-gittutorial-2 -- ':!po/'command-list.txt +0
-0@@ -244,6 +244,7 @@ gitrepository-layoutuserinterfaces
gitrevisions userinterfaces gitsubmodules guide gittutorial guide +gittutorial-2 guide gitweb ancillaryinterrogators gitworkflows guide scalar mainporcelain
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
That, as can be guessed, causes git(1) to advertize this "obsolete tutorial". Perhaps we would like to avoid that.
Agreed that we shouldn't advertise an obsolete tutorial. I'll remove it from
command-list.txton my branch and submit a v3.Just a friendly *ping*. :-)
Oh, after I wrote that I realized that gittutorial-2 is actually already removed from. command-list.txt on my branch.
Or at least that's what I see when I look at the version of this branch in Junio's repo. So I'm not totally sure what the next step is here.
$ git show junio/je/doc-remove-gittutorial-2:command-list.txt | grep tutorial gitcore-tutorial guide gittutorial guide
Quoted 1 line
--Tuomas
Quoted 4 lines · Julia Evans
Quoted 4 lines
Quoted 3 lines
Agreed that we shouldn't advertise an obsolete tutorial. I'll remove it from
command-list.txton my branch and submit a v3.
That is still a good plan.
Quoted 11 lines
Oh, after I wrote that I realized that gittutorial-2 is actually already removed from. command-list.txt on my branch.
Or at least that's what I see when I look at the version of this branch in Junio's repo. So I'm not totally sure what the next step is here.
$ git show junio/je/doc-remove-gittutorial-2:command-list.txt | grep tutorial gitcore-tutorial guide gittutorial guide
Are you sure your remote-tracking branch isn't stale? It seems Junio removed je/doc-remove-gittutorial-2 some time ago.[1]
Links:
1. https://github.com/gitster/git/activity?ref=je/doc-remove-gittutorial-2
Quoted 16 lines · Tuomas Ahola
Quoted 4 lines · Julia Evans
Quoted 4 lines
Quoted 3 lines
Agreed that we shouldn't advertise an obsolete tutorial. I'll remove it from
command-list.txton my branch and submit a v3.That is still a good plan.
Quoted 7 lines
Oh, after I wrote that I realized that gittutorial-2 is actually already removed from. command-list.txt on my branch.
Or at least that's what I see when I look at the version of this branch in Junio's repo. So I'm not totally sure what the next step is here.
Quoted 7 lines
Quoted 4 lines
$ git show junio/je/doc-remove-gittutorial-2:command-list.txt | grep tutorial gitcore-tutorial guide gittutorial guideAre you sure your remote-tracking branch isn't stale? It seems Junio removed je/doc-remove-gittutorial-2 some time ago.[1]
I'm not exactly sure what happened but I submitted the new version now.
Quoted 21 lines · Tuomas Ahola
Quoted 4 lines · Julia Evans
Quoted 4 lines
Quoted 3 lines
Agreed that we shouldn't advertise an obsolete tutorial. I'll remove it from
command-list.txton my branch and submit a v3.That is still a good plan.
Quoted 11 lines
Oh, after I wrote that I realized that gittutorial-2 is actually already removed from. command-list.txt on my branch.
Or at least that's what I see when I look at the version of this branch in Junio's repo. So I'm not totally sure what the next step is here.
$ git show junio/je/doc-remove-gittutorial-2:command-list.txt | grep tutorial gitcore-tutorial guide gittutorial guide
Quoted 5 lines
Are you sure your remote-tracking branch isn't stale? It seems Junio removed je/doc-remove-gittutorial-2 some time ago.[1]
Links:
1. https://github.com/gitster/git/activity?ref=je/doc-remove-gittutorial-2
I do not know what "Deleted branch" on that page means.
I did have a squashable fix-up on top of that branch since Julia's patch had some broken mark-up, but I do not think it had anything to do with the entry for gittutorial-2 in the command-list.txt file.
Puzzled.
v3 cover Remove gittutorial-2
In reply to Julia Evans via GitGitGadgetThis 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.
Changes in v2:
* Remove changes to .po files (thanks to Junio)
* Reword commit messages to doc: ... (thanks to Tuomas)
Changes in v3:
* Remove gittutorial-2 from command-list.txt
Julia Evans (2):
doc: remove gittutorial-2
doc: remove references to gittutorial-2
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 - 8 files changed, 14 insertions(+), 440 deletions(-)
base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2241%2Fjvns%2Fdelete-tutorial2-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2241/jvns/delete-tutorial2-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/2241
Range-diff vs v2:
1: 5fd36f91f0 = 1: 5fd36f91f0 doc: remove gittutorial-2 2: 68867aa3fc ! 2: 0a42345cec doc: remove references to gittutorial-2
@@ Documentation/gittutorial.adoc: digressions that may be interesting at this poin
linkgit:gitcvs-migration[7],
linkgit:gitcore-tutorial[7],
linkgit:gitglossary[7],
+
+ ## command-list.txt ##
+@@ command-list.txt: gitrepository-layout userinterfaces
+ gitrevisions userinterfaces
+ gitsubmodules guide
+ gittutorial guide
+-gittutorial-2 guide
+ gitweb ancillaryinterrogators
+ gitworkflows guide
+ scalar mainporcelain
Signature · 1 line
gitgitgadget
PATCH v3 1/2 doc: remove gittutorial-2
From: Julia Evans <[email protected]>
It hasn't been substantially updated for 20 years (see `git diff e31952da5c52a4c1:Documentation/tutorial-2.txt
0f8e75abebff0877:Documentation/gittutorial-2.adoc`)
and it's becoming out of date, for example:
- refs do not necessarily live in .git/refs
- we don't really call it "the index file" anymore, and we don't encourage users to think about the individual files in .git as much as we did 20 years ago
More importantly, this approach of introducing Git by learning about the contents of .git does not work for most people learning Git for the first time. It's interesting information for some people (maybe more advanced users or folks with a strong computer science background, for not appropriate for a general tutorial).
Right now gittutorial-2 is meant to be a logical sequel to gittutorial ("read gittutorial, then gittutorial-2"). Deleting gittutorial-2 means that we can more easily rewrite the main gittutorial (which is also not effective) in any way we want, without having to make sure that gittutorial-2 is the logical next step.
We have other documentation which can serve a similar purpose to tutorial-2 and isn't framed as a general tutorial appropriate for everyone.
Keep building the man page for now and leave behind a stub to redirect folks to those other documents.
--- Documentation/gittutorial-2.adoc | 422 +------------------------------ 1 file changed, 6 insertions(+), 416 deletions(-)
Documentation/gittutorial-2.adoc +6 -416
@@ -3,7 +3,7 @@ gittutorial-2(7) NAME ---- -gittutorial-2 - A tutorial introduction to Git: part two +gittutorial-2 - Obsolete tutorial SYNOPSIS --------
@@ -13,423 +13,13 @@ git * DESCRIPTION ----------- -You should work through linkgit:gittutorial[7] before reading this tutorial. +This tutorial has been deleted since it had become very stale. -The goal of this tutorial is to introduce two fundamental pieces of -Git's architecture--the object database and the index file--and to -provide the reader with everything necessary to understand the rest -of the Git documentation. +See linkgit:gitdatamodel[7] for an explanation of how Git's core data +structures work (objects, references and the index). -The Git object database ------------------------ - -Let's start a new project and create a small amount of history: - ------------------------------------------------- -$ mkdir test-project -$ cd test-project -$ git init -Initialized empty Git repository in .git/ -$ echo 'hello world' > file.txt -$ git add . -$ git commit -a -m "initial commit" -[master (root-commit) 54196cc] initial commit - 1 file changed, 1 insertion(+) - create mode 100644 file.txt -$ echo 'hello world!' >file.txt -$ git commit -a -m "add emphasis" -[master c4d59f3] add emphasis - 1 file changed, 1 insertion(+), 1 deletion(-) ------------------------------------------------- - -What are the 7 digits of hex that Git responded to the commit with? - -We saw in part one of the tutorial that commits have names like this. -It turns out that every object in the Git history is stored under -a 40-digit hex name. That name is the SHA-1 hash of the object's -contents; among other things, this ensures that Git will never store -the same data twice (since identical data is given an identical SHA-1 -name), and that the contents of a Git object will never change (since -that would change the object's name as well). The 7 char hex strings -here are simply the abbreviation of such 40 character long strings. -Abbreviations can be used everywhere where the 40 character strings -can be used, so long as they are unambiguous. - -It is expected that the content of the commit object you created while -following the example above generates a different SHA-1 hash than -the one shown above because the commit object records the time when -it was created and the name of the person performing the commit. - -We can ask Git about this particular object with the `cat-file` -command. Don't copy the 40 hex digits from this example but use those -from your own version. Note that you can shorten it to only a few -characters to save yourself typing all 40 hex digits: - ------------------------------------------------- -$ git cat-file -t 54196cc2 -commit -$ git cat-file commit 54196cc2 -tree 92b8b694ffb1675e5975148e1121810081dbdffe -author J. Bruce Fields <[email protected]> 1143414668 -0500 -committer J. Bruce Fields <[email protected]> 1143414668 -0500 - -initial commit ------------------------------------------------- - -A tree can refer to one or more "blob" objects, each corresponding to -a file. In addition, a tree can also refer to other tree objects, -thus creating a directory hierarchy. You can examine the contents of -any tree using ls-tree (remember that a long enough initial portion -of the SHA-1 will also work): - ------------------------------------------------- -$ git ls-tree 92b8b694 -100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt ------------------------------------------------- - -Thus we see that this tree has one file in it. The SHA-1 hash is a -reference to that file's data: - ------------------------------------------------- -$ git cat-file -t 3b18e512 -blob ------------------------------------------------- - -A "blob" is just file data, which we can also examine with cat-file: - ------------------------------------------------- -$ git cat-file blob 3b18e512 -hello world ------------------------------------------------- - -Note that this is the old file data; so the object that Git named in -its response to the initial tree was a tree with a snapshot of the -directory state that was recorded by the first commit. - -All of these objects are stored under their SHA-1 names inside the Git -directory: - ------------------------------------------------- -$ find .git/objects/ -.git/objects/ -.git/objects/pack -.git/objects/info -.git/objects/3b -.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad -.git/objects/92 -.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe -.git/objects/54 -.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7 -.git/objects/a0 -.git/objects/a0/423896973644771497bdc03eb99d5281615b51 -.git/objects/d0 -.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59 -.git/objects/c4 -.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241 ------------------------------------------------- - -and the contents of these files is just the compressed data plus a -header identifying their length and their type. The type is either a -blob, a tree, a commit, or a tag. - -The simplest commit to find is the HEAD commit, which we can find -from .git/HEAD: - ------------------------------------------------- -$ cat .git/HEAD -ref: refs/heads/master ------------------------------------------------- - -As you can see, this tells us which branch we're currently on, and it -tells us this by naming a file under the .git directory, which itself -contains a SHA-1 name referring to a commit object, which we can -examine with cat-file: - ------------------------------------------------- -$ cat .git/refs/heads/master -c4d59f390b9cfd4318117afde11d601c1085f241 -$ git cat-file -t c4d59f39 -commit -$ git cat-file commit c4d59f39 -tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59 -parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7 -author J. Bruce Fields <[email protected]> 1143418702 -0500 -committer J. Bruce Fields <[email protected]> 1143418702 -0500 - -add emphasis ------------------------------------------------- - -The "tree" object here refers to the new state of the tree: - ------------------------------------------------- -$ git ls-tree d0492b36 -100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt -$ git cat-file blob a0423896 -hello world! ------------------------------------------------- - -and the "parent" object refers to the previous commit: - ------------------------------------------------- -$ git cat-file commit 54196cc2 -tree 92b8b694ffb1675e5975148e1121810081dbdffe -author J. Bruce Fields <[email protected]> 1143414668 -0500 -committer J. Bruce Fields <[email protected]> 1143414668 -0500 - -initial commit ------------------------------------------------- - -The tree object is the tree we examined first, and this commit is -unusual in that it lacks any parent. - -Most commits have only one parent, but it is also common for a commit -to have multiple parents. In that case the commit represents a -merge, with the parent references pointing to the heads of the merged -branches. - -Besides blobs, trees, and commits, the only remaining type of object -is a "tag", which we won't discuss here; refer to linkgit:git-tag[1] -for details. - -So now we know how Git uses the object database to represent a -project's history: - - * "commit" objects refer to "tree" objects representing the - snapshot of a directory tree at a particular point in the - history, and refer to "parent" commits to show how they're - connected into the project history. - * "tree" objects represent the state of a single directory, - associating directory names to "blob" objects containing file - data and "tree" objects containing subdirectory information. - * "blob" objects contain file data without any other structure. - * References to commit objects at the head of each branch are - stored in files under .git/refs/heads/. - * The name of the current branch is stored in .git/HEAD. - -Note, by the way, that lots of commands take a tree as an argument. -But as we can see above, a tree can be referred to in many different -ways--by the SHA-1 name for that tree, by the name of a commit that -refers to the tree, by the name of a branch whose head refers to that -tree, etc.--and most such commands can accept any of these names. - -In command synopses, the word "tree-ish" is sometimes used to -designate such an argument. - -The index file --------------- - -The primary tool we've been using to create commits is `git-commit --a`, which creates a commit including every change you've made to -your working tree. But what if you want to commit changes only to -certain files? Or only certain changes to certain files? - -If we look at the way commits are created under the cover, we'll see -that there are more flexible ways creating commits. - -Continuing with our test-project, let's modify file.txt again: - ------------------------------------------------- -$ echo "hello world, again" >>file.txt ------------------------------------------------- - -but this time instead of immediately making the commit, let's take an -intermediate step, and ask for diffs along the way to keep track of -what's happening: - ------------------------------------------------- -$ git diff ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again -$ git add file.txt -$ git diff ------------------------------------------------- - -The last diff is empty, but no new commits have been made, and the -head still doesn't contain the new line: - ------------------------------------------------- -$ git diff HEAD -diff --git a/file.txt b/file.txt -index a042389..513feba 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again ------------------------------------------------- - -So 'git diff' is comparing against something other than the head. -The thing that it's comparing against is actually the index file, -which is stored in .git/index in a binary format, but whose contents -we can examine with ls-files: - ------------------------------------------------- -$ git ls-files --stage -100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt -$ git cat-file -t 513feba2 -blob -$ git cat-file blob 513feba2 -hello world! -hello world, again ------------------------------------------------- - -So what our 'git add' did was store a new blob and then put -a reference to it in the index file. If we modify the file again, -we'll see that the new modifications are reflected in the 'git diff' -output: - ------------------------------------------------- -$ echo 'again?' >>file.txt -$ git diff -index 513feba..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1,2 +1,3 @@ - hello world! - hello world, again -+again? ------------------------------------------------- - -With the right arguments, 'git diff' can also show us the difference -between the working directory and the last commit, or between the -index and the last commit: - ------------------------------------------------- -$ git diff HEAD -diff --git a/file.txt b/file.txt -index a042389..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,3 @@ - hello world! -+hello world, again -+again? -$ git diff --cached -diff --git a/file.txt b/file.txt -index a042389..513feba 100644 ---- a/file.txt -+++ b/file.txt -@@ -1 +1,2 @@ - hello world! -+hello world, again ------------------------------------------------- - -At any time, we can create a new commit using 'git commit' (without -the "-a" option), and verify that the state committed only includes the -changes stored in the index file, not the additional change that is -still only in our working tree: - ------------------------------------------------- -$ git commit -m "repeat" -$ git diff HEAD -diff --git a/file.txt b/file.txt -index 513feba..ba3da7b 100644 ---- a/file.txt -+++ b/file.txt -@@ -1,2 +1,3 @@ - hello world! - hello world, again -+again? ------------------------------------------------- - -So by default 'git commit' uses the index to create the commit, not -the working tree; the "-a" option to commit tells it to first update -the index with all changes in the working tree. - -Finally, it's worth looking at the effect of 'git add' on the index -file: - ------------------------------------------------- -$ echo "goodbye, world" >closing.txt -$ git add closing.txt ------------------------------------------------- - -The effect of the 'git add' was to add one entry to the index file: - ------------------------------------------------- -$ git ls-files --stage -100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0 closing.txt -100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt ------------------------------------------------- - -And, as you can see with cat-file, this new entry refers to the -current contents of the file: - ------------------------------------------------- -$ git cat-file blob 8b9743b2 -goodbye, world ------------------------------------------------- - -The "status" command is a useful way to get a quick summary of the -situation: - ------------------------------------------------- -$ git status -On branch master -Changes to be committed: - (use "git restore --staged <file>..." to unstage) - - new file: closing.txt - -Changes not staged for commit: - (use "git add <file>..." to update what will be committed) - (use "git restore <file>..." to discard changes in working directory) - - modified: file.txt - ------------------------------------------------- - -Since the current state of closing.txt is cached in the index file, -it is listed as "Changes to be committed". Since file.txt has -changes in the working directory that aren't reflected in the index, -it is marked "changed but not updated". At this point, running "git -commit" would create a commit that added closing.txt (with its new -contents), but that didn't modify file.txt. - -Also, note that a bare `git diff` shows the changes to file.txt, but -not the addition of closing.txt, because the version of closing.txt -in the index file is identical to the one in the working directory. - -In addition to being the staging area for new commits, the index file -is also populated from the object database when checking out a -branch, and is used to hold the trees involved in a merge operation. -See linkgit:gitcore-tutorial[7] and the relevant man -pages for details. - -What next? ----------- - -At this point you should know everything necessary to read the man -pages for any of the git commands; one good place to start would be -with the commands mentioned in linkgit:giteveryday[7]. You -should be able to find any unknown jargon in linkgit:gitglossary[7]. - -The link:user-manual.html[Git User's Manual] provides a more -comprehensive introduction to Git. - -linkgit:gitcvs-migration[7] explains how to -import a CVS repository into Git, and shows how to use Git in a -CVS-like way. - -For some interesting examples of Git use, see the -link:howto-index.html[howtos]. - -For Git developers, linkgit:gitcore-tutorial[7] goes -into detail on the lower-level Git mechanisms involved in, for -example, creating a new commit. - -SEE ALSO --------- -linkgit:gittutorial[7], -linkgit:gitcvs-migration[7], -linkgit:gitcore-tutorial[7], -linkgit:gitglossary[7], -linkgit:git-help[1], -linkgit:giteveryday[7], -link:user-manual.html[The Git User's Manual] +See linkgit:gitcore-tutorial[7] for a practical tutorial on how to +explore Git's internals. GIT ---
Signature · 1 line
gitgitgadget
PATCH v3 2/2 doc: remove references to gittutorial-2
In reply to Julia Evans via GitGitGadgetFrom: Julia Evans <[email protected]>
Redirect folks to gitdatamodel instead, since every time it's referenced the intent is to explain objects, references, blobs, etc.
The update to gittutorial isn't very carefully thought through since we're planning to delete that entire document anyway. It's just there to maintain some internal consistency.
--- Documentation/MyFirstObjectWalk.adoc | 2 +- Documentation/git.adoc | 2 +- Documentation/gitcore-tutorial.adoc | 1 - Documentation/gitcvs-migration.adoc | 2 +- Documentation/gitglossary.adoc | 1 - Documentation/gittutorial.adoc | 23 +++++------------------ command-list.txt | 1 - 7 files changed, 8 insertions(+), 24 deletions(-)
Documentation/MyFirstObjectWalk.adoc +1 -1
@@ -145,7 +145,7 @@ used to track the allocated size of the list. Per entry, we find: `item` is the object provided upon which to base the object walk. Items in Git -can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.adoc`.) +can be blobs, trees, commits, or tags. (See `Documentation/gitdatamodel.adoc`.) `name` is the object ID (OID) of the object - a hex string you may be familiar with from using Git to organize your source in the past. Check the tutorial
Documentation/git.adoc +1 -1
@@ -1200,7 +1200,7 @@ the Git Security mailing list <[email protected]>. SEE ALSO -------- -linkgit:gittutorial[7], linkgit:gittutorial-2[7], +linkgit:gittutorial[7], linkgit:giteveryday[7], linkgit:gitcvs-migration[7], linkgit:gitglossary[7], linkgit:gitdatamodel[7], linkgit:gitcore-tutorial[7], linkgit:gitcli[7],
Documentation/gitcore-tutorial.adoc +0 -1
@@ -1649,7 +1649,6 @@ to follow, not easier. SEE ALSO -------- linkgit:gittutorial[7], -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:git-help[1], linkgit:giteveryday[7],
Documentation/gitcvs-migration.adoc +1 -1
@@ -194,7 +194,7 @@ repositories without the need for a central maintainer. SEE ALSO -------- linkgit:gittutorial[7], -linkgit:gittutorial-2[7], +linkgit:gitdatamodel[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], linkgit:giteveryday[7],
Documentation/gitglossary.adoc +0 -1
@@ -18,7 +18,6 @@ SEE ALSO -------- linkgit:gitdatamodel[7], linkgit:gittutorial[7], -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:giteveryday[7], link:user-manual.html[The Git User's Manual]
Documentation/gittutorial.adoc +5 -18
@@ -622,24 +622,12 @@ Next Steps ---------- This tutorial should be enough to perform basic distributed revision -control for your projects. However, to fully understand the depth -and power of Git you need to understand two simple ideas on which it -is based: +control for your projects. However, to fully understand the Git +documentation, it's useful to learn how Git stores the history of +your project in its database. See linkgit:gitdatamodel[7] for an +explanation. - * The object database is the rather elegant system used to - store the history of your project--files, directories, and - commits. - - * The index file is a cache of the state of a directory tree, - used to create commits, check out working directories, and - hold the various trees involved in a merge. - -Part two of this tutorial explains the object -database, the index file, and a few other odds and ends that you'll -need to make the most of Git. You can find it at linkgit:gittutorial-2[7]. - -If you don't want to continue with that right away, a few other -digressions that may be interesting at this point are: +A few other commands that may be interesting: * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert series of git commits into emailed patches, and vice versa,
@@ -662,7 +650,6 @@ digressions that may be interesting at this point are: SEE ALSO -------- -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7],
command-list.txt +0 -1
@@ -244,7 +244,6 @@ gitrepository-layout userinterfaces gitrevisions userinterfaces gitsubmodules guide gittutorial guide -gittutorial-2 guide gitweb ancillaryinterrogators gitworkflows guide scalar mainporcelain
Signature · 1 line
gitgitgadget
Re: [PATCH v3 2/2] doc: remove references to gittutorial-2
"Julia Evans via GitGitGadget" <[email protected]> writes:
Forgot to mention one more thing.
Quoted 29 lines
Documentation/gittutorial.adoc | 23 +++++------------------...
Documentation/gittutorial.adoc +5
-9@@ -622,24 +622,12 @@ Next Steps ---------- This tutorial should be enough to perform basic distributed revision -control for your projects. However, to fully understand the depth -and power of Git you need to understand two simple ideas on which it -is based: +control for your projects. However, to fully understand the Git +documentation, it's useful to learn how Git stores the history of +your project in its database. See linkgit:gitdatamodel[7] for an +explanation. -Part two of this tutorial explains the object -database, the index file, and a few other odds and ends that you'll -need to make the most of Git. You can find it at linkgit:gittutorial-2[7]. - -If you don't want to continue with that right away, a few other -digressions that may be interesting at this point are: +A few other commands that may be interesting: * linkgit:git-format-patch[1], linkgit:git-am[1]: These convert series of git commits into emailed patches, and vice versa,
Documentation/gittutorial.adoc digressions that may be interesting at this point are: · line 655
Quoted 7 lines
Documentation/gittutorial.adoc +0
-1@@ -662,7 +650,6 @@ digressions that may be interesting at this point are: SEE ALSO -------- -linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7],
As the main tutorial is being rewritten from scratch, and it seems to assume that nobody has ever heard of gittutorial-2 ;-), the above patch would not merge well when both topics meet in 'seen'.
I do not think this topic to remove tutorial-2 would need further rework, but just in case if it ever becomes necessary, could you leave the changes out of this series? I can remember to take the other side and ignore the changes to the file done on this branch, but not having to remember one such thing helps quite a lot when you have to deal with 100+ merges to rebuild 'seen' on top of 'master', with updated topics of the day.
Thanks.
Quoted 3 lines · Julia Evans via GitGitGadget
Changes in v3:
* Remove gittutorial-2 from command-list.txt
Good.
Thanks