user-manual: patch proposals and questions

user-manual: patch proposals and questions

[kalle]

The patches are attached.
Further some questions:

-see the explanations of the branch command, ca. line 280: wouldn't it
be better to use other words than 'references'?
-sentence "it shows all commits reachable from the parent commit": it
seems wrong to me. The last commit is also shown.
- chapter "Browsing revisions": it seems counterintuitive to me to have
two different logics for the meaning of "branch1..branch2" and
"branch1...branch2", according to whether it's the argument of `git log'
or `git diff'
-section "Check whether two branches point at the same history": 'git
diff origin..master' -> shouldn't it be rather 'git diff
branch1..branch2'? … or rewrite the example with branch1=origin and
branch2=master.

greetings,
kalle

user-manual: patch proposals and questions

[kalle]

[-- Attachment #1: Type: text/plain, Size: 743 bytes --]

The patches are attached.
Further some questions:

-see the explanations of the branch command, ca. line 280: wouldn't it
be better to use other words than 'references'?
-sentence "it shows all commits reachable from the parent commit": it
seems wrong to me. The last commit is also shown.
- chapter "Browsing revisions": it seems counterintuitive to me to have
two different logics for the meaning of "branch1..branch2" and
"branch1...branch2", according to whether it's the argument of `git log'
or `git diff'
-section "Check whether two branches point at the same history": 'git
diff origin..master' -> shouldn't it be rather 'git diff
branch1..branch2'? … or rewrite the example with branch1=origin and
branch2=master.

greetings,
kalle

[-- Attachment #2: 0002-3-small-formulation-changes-in-Documentation-user-ma.patch --]
[-- Type: text/x-patch, Size: 1880 bytes --]

From 19061a0dd4363edbf8757a5e9eee8ace210f4029 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Fri, 9 Feb 2018 20:46:52 +0100
Subject: [PATCH 2/5] 3 small formulation changes in
 Documentation/user-manual.txt

---
 Documentation/user-manual.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index eff7890..e3efc26 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -322,7 +322,7 @@ do so (now or later) by using -b with the checkout command again. Example:
 HEAD is now at 427abfa Linux v2.6.17
 ------------------------------------------------
 
-The HEAD then refers to the SHA-1 of the commit instead of to a branch,
+If you haven't created a new branch yet, the HEAD then refers to the SHA-1 of the commit instead of to a branch,
 and git branch shows that you are no longer on a branch:
 
 ------------------------------------------------
@@ -370,7 +370,7 @@ be updated by `git fetch` (hence `git pull`) and `git push`. See
 <<Updating-a-repository-With-git-fetch>> for details.
 
 You might want to build on one of these remote-tracking branches
-on a branch of your own, just as you would for a tag:
+a branch of your own, just as you would for a tag:
 
 ------------------------------------------------
 $ git checkout -b my-todo-copy origin/todo
@@ -404,7 +404,7 @@ they may also be packed together in a single file; see
 linkgit:git-pack-refs[1]).
 
 As another useful shortcut, the "HEAD" of a repository can be referred
-to just using the name of that repository.  So, for example, "origin"
+to by just using the name of that repository.  So, for example, "origin"
 is usually a shortcut for the HEAD branch in the repository "origin".
 
 For the complete list of paths which Git checks for references, and
-- 
2.1.4


[-- Attachment #3: 0003-I-changed-the-sequence-of-2-sentences.patch --]
[-- Type: text/x-patch, Size: 1988 bytes --]

From 3917eeaf8d21b8b90a773c46ee5b9d12eac901e3 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Sat, 10 Feb 2018 16:08:45 +0100
Subject: [PATCH 3/5] I changed the sequence of 2 sentences.

---
 Documentation/user-manual.txt | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index e3efc26..b9dc17a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -609,13 +609,9 @@ $ git show HEAD^2   # show the second parent of HEAD
 In addition to HEAD, there are several other special names for
 commits:
 
-Merges (to be discussed later), as well as operations such as
-`git reset`, which change the currently checked-out commit, generally
-set ORIG_HEAD to the value HEAD had before the current operation.
+ORIG_HEAD is set to the value HEAD before merging (to be discussed later) operations as well as operations such as `git reset'. which change the currently checked-out commit.
 
-The `git fetch` operation always stores the head of the last fetched
-branch in FETCH_HEAD.  For example, if you run `git fetch` without
-specifying a local branch as the target of the operation
+FETCH_HEAD after a `git fetch' operation stores the head of the last fetched branch. For example, if you run `git fetch' without specifying a local branch as the target of the operation.
 
 -------------------------------------------------
 $ git fetch git://example.com/proj.git theirbranch
@@ -664,7 +660,7 @@ can also make more specific requests:
 
 -------------------------------------------------
 $ git log v2.5..	# commits since (not reachable from) v2.5
-$ git log test..master	# commits reachable from master but not test
+$ git log ..master	# commits reachable from master but not from test
 $ git log master..test	# ...reachable from test but not master
 $ git log master...test	# ...reachable from either test or master,
 			#    but not both
-- 
2.1.4


[-- Attachment #4: 0004-I-errouneously-have-deleted-one-word-too-much-in-the.patch --]
[-- Type: text/x-patch, Size: 991 bytes --]

From a084b699ed7a0768530f9112ae8469fd5e297356 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Sat, 10 Feb 2018 16:14:25 +0100
Subject: [PATCH 4/5] I errouneously have deleted one word too much in the last
 commit

---
 Documentation/user-manual.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index b9dc17a..5468163 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -660,7 +660,7 @@ can also make more specific requests:
 
 -------------------------------------------------
 $ git log v2.5..	# commits since (not reachable from) v2.5
-$ git log ..master	# commits reachable from master but not from test
+$ git log test..master	# commits reachable from master but not from test
 $ git log master..test	# ...reachable from test but not master
 $ git log master...test	# ...reachable from either test or master,
 			#    but not both
-- 
2.1.4


[-- Attachment #5: 0005-small-error-fixed.patch --]
[-- Type: text/x-patch, Size: 1147 bytes --]

From 23b13bd16e752fd2c69c1e8bd23c3c35e6c43503 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Sat, 10 Feb 2018 16:29:39 +0100
Subject: [PATCH 5/5] small error fixed

---
 Documentation/user-manual.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5468163..8143310 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -661,9 +661,9 @@ can also make more specific requests:
 -------------------------------------------------
 $ git log v2.5..	# commits since (not reachable from) v2.5
 $ git log test..master	# commits reachable from master but not from test
-$ git log master..test	# ...reachable from test but not master
+$ git log master..test	# ...reachable from test but not from master
 $ git log master...test	# ...reachable from either test or master,
-			#    but not both
+			#    but not from both
 $ git log --since="2 weeks ago" # commits from the last 2 weeks
 $ git log Makefile      # commits which modify Makefile
 $ git log fs/		# ... which modify any file under fs/
-- 
2.1.4

Fwd: user-manual: patch proposals and questions

[kalle]

[-- Attachment #1: Type: text/plain, Size: 1339 bytes --]


hello,

1.I wonder, why the "user-manual" is so hidden on the (official?) site
git-scm.com [it is accessible at git-scm.com/docs/user-manual ,but is
not viewable in /docs ]

2.I did not receive an answer to my mail. Maybe it could have to do with
a possible stopped maintainment of the 'user-manual'

3.it would be for non-graphics-users to have the Git-Pro-book in
text-format.

thanks,
kalle

-------- Weitergeleitete Nachricht --------
Betreff: user-manual: patch proposals and questions
Datum: Tue, 6 Mar 2018 00:08:55 +0100
Von: kalle <kalle@projektwerkstatt.de>
An: git@vger.kernel.org

The patches are attached.
Further some questions:

-see the explanations of the branch command, ca. line 280: wouldn't it
be better to use other words than 'references'?
-sentence "it shows all commits reachable from the parent commit": it
seems wrong to me. The last commit is also shown.
- chapter "Browsing revisions": it seems counterintuitive to me to have
two different logics for the meaning of "branch1..branch2" and
"branch1...branch2", according to whether it's the argument of `git log'
or `git diff'
-section "Check whether two branches point at the same history": 'git
diff origin..master' -> shouldn't it be rather 'git diff
branch1..branch2'? … or rewrite the example with branch1=origin and
branch2=master.

greetings,
kalle



[-- Attachment #2: 0002-3-small-formulation-changes-in-Documentation-user-ma.patch --]
[-- Type: text/x-patch, Size: 1882 bytes --]

From 19061a0dd4363edbf8757a5e9eee8ace210f4029 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Fri, 9 Feb 2018 20:46:52 +0100
Subject: [PATCH 2/5] 3 small formulation changes in
 Documentation/user-manual.txt

---
 Documentation/user-manual.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index eff7890..e3efc26 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -322,7 +322,7 @@ do so (now or later) by using -b with the checkout command again. Example:
 HEAD is now at 427abfa Linux v2.6.17
 ------------------------------------------------
 
-The HEAD then refers to the SHA-1 of the commit instead of to a branch,
+If you haven't created a new branch yet, the HEAD then refers to the SHA-1 of the commit instead of to a branch,
 and git branch shows that you are no longer on a branch:
 
 ------------------------------------------------
@@ -370,7 +370,7 @@ be updated by `git fetch` (hence `git pull`) and `git push`. See
 <<Updating-a-repository-With-git-fetch>> for details.
 
 You might want to build on one of these remote-tracking branches
-on a branch of your own, just as you would for a tag:
+a branch of your own, just as you would for a tag:
 
 ------------------------------------------------
 $ git checkout -b my-todo-copy origin/todo
@@ -404,7 +404,7 @@ they may also be packed together in a single file; see
 linkgit:git-pack-refs[1]).
 
 As another useful shortcut, the "HEAD" of a repository can be referred
-to just using the name of that repository.  So, for example, "origin"
+to by just using the name of that repository.  So, for example, "origin"
 is usually a shortcut for the HEAD branch in the repository "origin".
 
 For the complete list of paths which Git checks for references, and
-- 
2.1.4




[-- Attachment #3: 0003-I-changed-the-sequence-of-2-sentences.patch --]
[-- Type: text/x-patch, Size: 1990 bytes --]

From 3917eeaf8d21b8b90a773c46ee5b9d12eac901e3 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Sat, 10 Feb 2018 16:08:45 +0100
Subject: [PATCH 3/5] I changed the sequence of 2 sentences.

---
 Documentation/user-manual.txt | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index e3efc26..b9dc17a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -609,13 +609,9 @@ $ git show HEAD^2   # show the second parent of HEAD
 In addition to HEAD, there are several other special names for
 commits:
 
-Merges (to be discussed later), as well as operations such as
-`git reset`, which change the currently checked-out commit, generally
-set ORIG_HEAD to the value HEAD had before the current operation.
+ORIG_HEAD is set to the value HEAD before merging (to be discussed later) operations as well as operations such as `git reset'. which change the currently checked-out commit.
 
-The `git fetch` operation always stores the head of the last fetched
-branch in FETCH_HEAD.  For example, if you run `git fetch` without
-specifying a local branch as the target of the operation
+FETCH_HEAD after a `git fetch' operation stores the head of the last fetched branch. For example, if you run `git fetch' without specifying a local branch as the target of the operation.
 
 -------------------------------------------------
 $ git fetch git://example.com/proj.git theirbranch
@@ -664,7 +660,7 @@ can also make more specific requests:
 
 -------------------------------------------------
 $ git log v2.5..	# commits since (not reachable from) v2.5
-$ git log test..master	# commits reachable from master but not test
+$ git log ..master	# commits reachable from master but not from test
 $ git log master..test	# ...reachable from test but not master
 $ git log master...test	# ...reachable from either test or master,
 			#    but not both
-- 
2.1.4




[-- Attachment #4: 0004-I-errouneously-have-deleted-one-word-too-much-in-the.patch --]
[-- Type: text/x-patch, Size: 993 bytes --]

From a084b699ed7a0768530f9112ae8469fd5e297356 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Sat, 10 Feb 2018 16:14:25 +0100
Subject: [PATCH 4/5] I errouneously have deleted one word too much in the last
 commit

---
 Documentation/user-manual.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index b9dc17a..5468163 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -660,7 +660,7 @@ can also make more specific requests:
 
 -------------------------------------------------
 $ git log v2.5..	# commits since (not reachable from) v2.5
-$ git log ..master	# commits reachable from master but not from test
+$ git log test..master	# commits reachable from master but not from test
 $ git log master..test	# ...reachable from test but not master
 $ git log master...test	# ...reachable from either test or master,
 			#    but not both
-- 
2.1.4




[-- Attachment #5: 0005-small-error-fixed.patch --]
[-- Type: text/x-patch, Size: 1149 bytes --]

From 23b13bd16e752fd2c69c1e8bd23c3c35e6c43503 Mon Sep 17 00:00:00 2001
From: kalledaballe <kalle@projektwerkstatt.de>
Date: Sat, 10 Feb 2018 16:29:39 +0100
Subject: [PATCH 5/5] small error fixed

---
 Documentation/user-manual.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 5468163..8143310 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -661,9 +661,9 @@ can also make more specific requests:
 -------------------------------------------------
 $ git log v2.5..	# commits since (not reachable from) v2.5
 $ git log test..master	# commits reachable from master but not from test
-$ git log master..test	# ...reachable from test but not master
+$ git log master..test	# ...reachable from test but not from master
 $ git log master...test	# ...reachable from either test or master,
-			#    but not both
+			#    but not from both
 $ git log --since="2 weeks ago" # commits from the last 2 weeks
 $ git log Makefile      # commits which modify Makefile
 $ git log fs/		# ... which modify any file under fs/
-- 
2.1.4

Re: user-manual: patch proposals and questions

[Eric Sunshine]

On Sun, Mar 18, 2018 at 7:49 PM, kalle <kalle@projektwerkstatt.de> wrote:
> 1.I wonder, why the "user-manual" is so hidden on the (official?) site
> git-scm.com [it is accessible at git-scm.com/docs/user-manual ,but is
> not viewable in /docs ]

The git-scm.com website is maintained as a distinct project[1] at
Github; it is not directly related to the Git project itself. A good
way to voice your concern about the website is either to open an issue
ticket[2] or submit a pull request[3] if you have a specific change in
mind.

[1]: https://github.com/git/git-scm.com
[2]: https://github.com/git/git-scm.com/issues
[3]: https://github.com/git/git-scm.com/pulls

> 2.I did not receive an answer to my mail. Maybe it could have to do with
> a possible stopped maintainment of the 'user-manual'

More likely it was because your email was not composed in a way for
people to digest and respond to it easily. There are some things you
can do to help make it easier for people to respond:

* Send patches inline rather than attachments since it is much easier
for people to respond to them directly when inline. When they are
attachments, people are forced to open the attachment, then copy/paste
parts of the patch back into the email for response, and most people
won't bother with such effort. Also, make each patch a separate email
with a meaningful commit message ("git format-patch" and "git
send-email" can help with this).

* For your questions about documentation, quote the section of
documentation you want to talk about directly in your email, then ask
a question about it. This saves people the effort of manually having
to open the file and locate the line or paragraph in question. Also,
line numbers change as changes are made to files, so the line number
you cite might not match the line number in a version of the file
someone else is looking at.

> 3.it would be for non-graphics-users to have the Git-Pro-book in
> text-format.

Like the website, the Pro Git book is a distinct project[4], not
directly related to the Git project. To suggest making the book
available as plain text, you can open an issue ticket[5] or submit a
pull request[6] if you implement it yourself.

[4]: https://github.com/progit/progit2
[5]: https://github.com/progit/progit2/issues
[6]: https://github.com/progit/progit2/pulls


> -------- Weitergeleitete Nachricht --------
> Betreff: user-manual: patch proposals and questions
> Datum: Tue, 6 Mar 2018 00:08:55 +0100
> Von: kalle <kalle@projektwerkstatt.de>
> An: git@vger.kernel.org
>
> The patches are attached.
> Further some questions:
>
> -see the explanations of the branch command, ca. line 280: wouldn't it
> be better to use other words than 'references'?
> -sentence "it shows all commits reachable from the parent commit": it
> seems wrong to me. The last commit is also shown.
> - chapter "Browsing revisions": it seems counterintuitive to me to have
> two different logics for the meaning of "branch1..branch2" and
> "branch1...branch2", according to whether it's the argument of `git log'
> or `git diff'
> -section "Check whether two branches point at the same history": 'git
> diff origin..master' -> shouldn't it be rather 'git diff
> branch1..branch2'? … or rewrite the example with branch1=origin and
> branch2=master.
>
> greetings,
> kalle

Re: user-manual: patch proposals and questions

[kalle]

thank you for your answer and hints.
kalle

Am 19.03.2018 um 01:27 schrieb Eric Sunshine:
> On Sun, Mar 18, 2018 at 7:49 PM, kalle <kalle@projektwerkstatt.de> wrote:
>> 1.I wonder, why the "user-manual" is so hidden on the (official?) site
>> git-scm.com [it is accessible at git-scm.com/docs/user-manual ,but is
>> not viewable in /docs ]
> 
> The git-scm.com website is maintained as a distinct project[1] at
> Github; it is not directly related to the Git project itself. A good
> way to voice your concern about the website is either to open an issue
> ticket[2] or submit a pull request[3] if you have a specific change in
> mind.
> 
> [1]: https://github.com/git/git-scm.com
> [2]: https://github.com/git/git-scm.com/issues
> [3]: https://github.com/git/git-scm.com/pulls
> 
>> 2.I did not receive an answer to my mail. Maybe it could have to do with
>> a possible stopped maintainment of the 'user-manual'
> 
> More likely it was because your email was not composed in a way for
> people to digest and respond to it easily. There are some things you
> can do to help make it easier for people to respond:
> 
> * Send patches inline rather than attachments since it is much easier
> for people to respond to them directly when inline. When they are
> attachments, people are forced to open the attachment, then copy/paste
> parts of the patch back into the email for response, and most people
> won't bother with such effort. Also, make each patch a separate email
> with a meaningful commit message ("git format-patch" and "git
> send-email" can help with this).
> 
> * For your questions about documentation, quote the section of
> documentation you want to talk about directly in your email, then ask
> a question about it. This saves people the effort of manually having
> to open the file and locate the line or paragraph in question. Also,
> line numbers change as changes are made to files, so the line number
> you cite might not match the line number in a version of the file
> someone else is looking at.
> 
>> 3.it would be for non-graphics-users to have the Git-Pro-book in
>> text-format.
> 
> Like the website, the Pro Git book is a distinct project[4], not
> directly related to the Git project. To suggest making the book
> available as plain text, you can open an issue ticket[5] or submit a
> pull request[6] if you implement it yourself.
> 
> [4]: https://github.com/progit/progit2
> [5]: https://github.com/progit/progit2/issues
> [6]: https://github.com/progit/progit2/pulls
> 
> 
>> -------- Weitergeleitete Nachricht --------
>> Betreff: user-manual: patch proposals and questions
>> Datum: Tue, 6 Mar 2018 00:08:55 +0100
>> Von: kalle <kalle@projektwerkstatt.de>
>> An: git@vger.kernel.org
>>
>> The patches are attached.
>> Further some questions:
>>
>> -see the explanations of the branch command, ca. line 280: wouldn't it
>> be better to use other words than 'references'?
>> -sentence "it shows all commits reachable from the parent commit": it
>> seems wrong to me. The last commit is also shown.
>> - chapter "Browsing revisions": it seems counterintuitive to me to have
>> two different logics for the meaning of "branch1..branch2" and
>> "branch1...branch2", according to whether it's the argument of `git log'
>> or `git diff'
>> -section "Check whether two branches point at the same history": 'git
>> diff origin..master' -> shouldn't it be rather 'git diff
>> branch1..branch2'? … or rewrite the example with branch1=origin and
>> branch2=master.
>>
>> greetings,
>> kalle