From: Junio C Hamano Date: Sun, 25 Mar 2007 22:08:11 +0000 (-0700) Subject: Merge branch 'maint' X-Git-Tag: v1.5.1-rc2~5 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/2603fa5fb358ee7834bc9e1a2e391f69d8fce815?ds=inline;hp=-c Merge branch 'maint' * maint: user-manual: introduce "branch" and "branch head" differently glossary: clean up cross-references glossary: stop generating automatically user-manual: Use def_ instead of ref_ for glossary references. user-manual.txt: fix a tiny typo. user-manual: run xsltproc without --nonet option --- 2603fa5fb358ee7834bc9e1a2e391f69d8fce815 diff --combined Documentation/user-manual.txt index d7b227e647,3ed9f84524..1c49e6995b --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@@ -288,21 -288,22 +288,22 @@@ collection of files. It stores the his collection of interrelated snapshots (versions) of the project's contents. - A single git repository may contain multiple branches. Each branch - is a bookmark referencing a particular point in the project history. - The gitlink:git-branch[1] command shows you the list of branches: + A single git repository may contain multiple branches. It keeps track + of them by keeping a list of <> which reference the + latest version on each branch; the gitlink:git-branch[1] command shows + you the list of branch heads: ------------------------------------------------ $ git branch * master ------------------------------------------------ - A freshly cloned repository contains a single branch, named "master", - and the working directory contains the version of the project - referred to by the master branch. + A freshly cloned repository contains a single branch head, named + "master", and working directory is initialized to the state of + the project referred to by "master". - Most projects also use tags. Tags, like branches, are references - into the project's history, and can be listed using the + Most projects also use <>. Tags, like heads, are + references into the project's history, and can be listed using the gitlink:git-tag[1] command: ------------------------------------------------ @@@ -320,9 -321,9 +321,9 @@@ v2.6.1 ------------------------------------------------ Tags are expected to always point at the same version of a project, - while branches are expected to advance as development progresses. + while heads are expected to advance as development progresses. - Create a new branch pointing to one of these versions and check it + Create a new branch head pointing to one of these versions and check it out using gitlink:git-checkout[1]: ------------------------------------------------ @@@ -346,10 -347,10 +347,10 @@@ the current branch to point at v2.6.17 $ git reset --hard v2.6.17 ------------------------------------------------ - Note that if the current branch was your only reference to a + Note that if the current branch head was your only reference to a particular point in history, then resetting that branch may leave you - with no way to find the history it used to point to; so use this - command carefully. + with no way to find the history it used to point to; so use this command + carefully. Understanding History: Commits ------------------------------ @@@ -452,17 -453,15 +453,15 @@@ be replaced with another letter or numb Understanding history: What is a branch? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Though we've been using the word "branch" to mean a kind of reference - to a particular commit, the word branch is also commonly used to - refer to the line of commits leading up to that point. In the - example above, git may think of the branch named "A" as just a - pointer to one particular commit, but we may refer informally to the - line of three commits leading up to that point as all being part of + When we need to be precise, we will use the word "branch" to mean a line + of development, and "branch head" (or just "head") to mean a reference + to the most recent commit on a branch. In the example above, the branch + head named "A" is a pointer to one particular commit, but we refer to + the line of three commits leading up to that point as all being part of "branch A". - If we need to make it clear that we're just talking about the most - recent commit on the branch, we may refer to that commit as the - "head" of the branch. + However, when no confusion will result, we often just use the term + "branch" both for branches and for branch heads. Manipulating branches --------------------- @@@ -1698,7 -1697,7 +1697,7 @@@ If you and maintainer both have account then you can just pull changes from each other's repositories directly; note that all of the commands (gitlink:git-clone[1], git-fetch[1], git-pull[1], etc.) that accept a URL as an argument - will also accept a local file patch; so, for example, you can + will also accept a local directory name; so, for example, you can use ------------------------------------------------- @@@ -2870,7 -2869,7 +2869,7 @@@ stages to temporary files and calls a " $ git-merge-index git-merge-one-file hello.c ------------------------------------------------- -and that is what higher level `git resolve` is implemented with. +and that is what higher level `git merge -s resolve` is implemented with. How git stores objects efficiently: pack files ---------------------------------------------- @@@ -3013,9 -3012,6 +3012,6 @@@ confusing and scary messages, but it wo contrast, running "git prune" while somebody is actively changing the repository is a *BAD* idea). - Glossary of git terms - ===================== - include::glossary.txt[] Notes and todo list for this manual