[PATCH] glossary: explain "master" and "origin"

[PATCH] glossary: explain "master" and "origin"

[Johannes Schindelin]

If you are a long time git user/developer, you forget that to a new git
user, these words have not the same meaning as to you.

Signed-off-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>

---

 Documentation/glossary.txt |   11 +++++++++++
 1 files changed, 11 insertions(+), 0 deletions(-)

diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt
index 2331be5..4ef7d2a 100644
--- a/Documentation/glossary.txt
+++ b/Documentation/glossary.txt
@@ -111,6 +111,17 @@ branch::
 	a particular revision, which is called the branch head. The
 	branch heads are stored in `$GIT_DIR/refs/heads/`.
 
+master::
+	The default branch. Whenever you create a git repository, a branch
+	named "master" is created, and becomes the active branch. In most
+	cases, this contains the local development.
+
+origin::
+	The default upstream branch. Most projects have one upstream 
+        project which is tracked, and augmented with local changes which
+        eventually get merged back. You never commit to this branch,
+	unless you are maintaining the upstream project.
+
 ref::
 	A 40-byte hex representation of a SHA1 pointing to a particular
 	object. These may be stored in `$GIT_DIR/refs/`.

Re: [PATCH] glossary: explain "master" and "origin"

[J. Bruce Fields]

On Tue, Jan 10, 2006 at 10:26:46PM +0100, Johannes Schindelin wrote:
> +origin::
> +	The default upstream branch. Most projects have one upstream 
> +        project which is tracked, and augmented with local changes which
> +        eventually get merged back. You never commit to this branch,
> +	unless you are maintaining the upstream project.

The last line is somewhat confusing--a naive reader might take it to
mean that as an upstream maintainer it would make sense to commit to a
branch named "origin".  How about something like this?

	"The default upstream branch.  Most projects have one upstream
	project which they track.  This is is the branch used for
	tracking that project.  New updates from upstream will be
	fetched into this branch, but you should never commit to it
	yourself."

--b.

Re: [PATCH] glossary: explain "master" and "origin"

[Johannes Schindelin]

Hi,

On Tue, 10 Jan 2006, J. Bruce Fields wrote:

> On Tue, Jan 10, 2006 at 10:26:46PM +0100, Johannes Schindelin wrote:
> > +origin::
> > +	The default upstream branch. Most projects have one upstream 
> > +        project which is tracked, and augmented with local changes which
> > +        eventually get merged back. You never commit to this branch,
> > +	unless you are maintaining the upstream project.
> 
> The last line is somewhat confusing--a naive reader might take it to
> mean that as an upstream maintainer it would make sense to commit to a
> branch named "origin".  How about something like this?
> 
> 	"The default upstream branch.  Most projects have one upstream
> 	project which they track.  This is is the branch used for
> 	tracking that project.  New updates from upstream will be
> 	fetched into this branch, but you should never commit to it
> 	yourself."

It is probably safer. Note: I actually commit to the origin branch in one 
of my projects, and I follow it directly by a "git push origin".

Ciao,
Dscho

P.S.: I just noted that some of the tabs were turned into spaces. Does 
asciidoc mind?

Re: [PATCH] glossary: explain "master" and "origin"

[walt]

J. Bruce Fields wrote:
[...]
> 	Most projects have one upstream
> 	project which they track.  This is is the branch used for
> 	tracking that project...

s/This/'origin'/

Lordy, I think many of the world's problems could be solved just
by forbidding the use of pronouns entirely!

Re: [PATCH] glossary: explain "master" and "origin"

[walt]

walt wrote:
> J. Bruce Fields wrote:
> [...]
>> 	Most projects have one upstream
>> 	project which they track.  This is is the branch used for
>> 	tracking that project...
> 
> s/This/'origin'/
> 
> Lordy, I think many of the world's problems could be solved just
> by forbidding the use of pronouns entirely!

Now that I've had another beer, it occurs to me that a 'pronoun'
is nothing more or less than a 'pointer' to a noun.

Well!  We all know that pointers are a major source of bugs in
C code.  Is it possible that lint could be taught to detect
ambiguous pronouns in everyday speech?

Re: [PATCH] glossary: explain "master" and "origin"

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> P.S.: I just noted that some of the tabs were turned into spaces. Does 
> asciidoc mind?

Probably not, but I do so I fixed them up myself.