Re: Call Me Gitless

"Peter Valdemar Mørch (Lists)"  [off-list ref] writes:

Here, here! That is *exactly* what I was thinking when I started
reading this thread: "Hey, the "git diff" stuff was easy enough, it
was the reverting (and friends) that caused me trouble!"

Also, in the same area, I've now understood that to undo a "git add" -
to remove a change from the index and making it show up as a
difference between the working tree and the index - one can use "git
... Would've been helpful to me to have a
sentense or paragraph about that in git-add.txt,...

Wonderful.

Can somebody who is relatively (but not extremely) new to git can
volunteer to be a documentation secretary to collect these "Hear, hear, it
would have been very helpful if X were documented next to Y" stories, and
coordinate documentation updates after enough such improvement suggestions
are collected?

People who lost git virginity like myself cannot do this sensibly and
fairly.  For example, as my mind is already contaminated enough that I
discarded the original "add this as Discussion item to revert" message
after reading it once, judging it to add extra noise without much merit.

On Tue, Aug 19, 2008 at 2:01 PM, Junio C Hamano [off-list ref] wrote:

"Peter Valdemar Mørch (Lists)"  [off-list ref] writes:

quoted

Here, here! That is *exactly* what I was thinking when I started
reading this thread: "Hey, the "git diff" stuff was easy enough, it
was the reverting (and friends) that caused me trouble!"

Also, in the same area, I've now understood that to undo a "git add" -
to remove a change from the index and making it show up as a
difference between the working tree and the index - one can use "git
... Would've been helpful to me to have a
sentense or paragraph about that in git-add.txt,...

Wonderful.

Can somebody who is relatively (but not extremely) new to git can
volunteer to be a documentation secretary to collect these "Hear, hear, it
would have been very helpful if X were documented next to Y" stories, and
coordinate documentation updates after enough such improvement suggestions
are collected?

People who lost git virginity like myself cannot do this sensibly and
fairly.  For example, as my mind is already contaminated enough that I
discarded the original "add this as Discussion item to revert" message
after reading it once, judging it to add extra noise without much merit.

I would not agree it to be a part of git-add man page, but rather it
should be a part of doc that explains basic git commands and their
flows. I feel that we need a place where git flows are explained. IMO,
gitwiki is a great place for it. I would like to volunteer to add
these pages to Wiki.

Best regards,

Imran

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi,

Imran M Yousuf imyousuf-at-gmail.com |Lists| wrote:

I would not agree it to be a part of git-add man page, but rather it
should be a part of doc that explains basic git commands and their
flows. I feel that we need a place where git flows are explained. IMO,
gitwiki is a great place for it. I would like to volunteer to add
these pages to Wiki.

Why not? Shouldn't the man pages be a superset of those other docs?

Does it seem clear to you from reading "git help reset" that it is 
related to "git add" and that one can undo a git add with git reset?

Peter
-- 
Peter Valdemar Mørch
http://www.morch.com

On Tue, Aug 19, 2008 at 2:26 PM, "Peter Valdemar Mørch (Lists)"
[off-list ref] wrote:

Hi,

Imran M Yousuf imyousuf-at-gmail.com |Lists| wrote:

quoted

I would not agree it to be a part of git-add man page, but rather it
should be a part of doc that explains basic git commands and their
flows. I feel that we need a place where git flows are explained. IMO,
gitwiki is a great place for it. I would like to volunteer to add
these pages to Wiki.

Why not? Shouldn't the man pages be a superset of those other docs?

Does it seem clear to you from reading "git help reset" that it is related
to "git add" and that one can undo a git add with git reset?

Actually when I learned git I never learned one command after another,
rather I learned the flows and the most the scenarios mentioned in
this thread mostly got covered then in either first or second flow I
was trying. What learning flows enabled was, for me to experience how
commands are inter-related.

It basically depends how a person learns the tool. My way of learning
a tool is to learn flows. I have also taken the same steps to teach
some of my friends and colleagues git and all seem to understand the
stuffs :). But hey, that is my opinion :) only.

Best regards,

Imran

Peter
--
Peter Valdemar Mørch
http://www.morch.com
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Junio,

I would volunteer as the documentation git-virgin. To prove the hymen
intact, here are some of my thoughts and stumbling blocks over the
past two weeks:

There is no indication in the documentation distinguishing porcelain
from plumbing. Perhaps there is a grey scale, but operations that do
not move the HEAD to the latest should indicate that fact (for
example, pull vs. push, fetch).

Remote never seems to do what I expect, so I manually edit the
.git/refs!! Nor is git-reset what I expect and use git checkout (which
does make sense only after a few backup trials). Git-add adds to the
index but does not create, however git-rm removes from the index and
does delete (an --index-only or --keep flag might be nice).

A single term for cache and index should be decided upon. git diff
--cached is not intuitive when 'index' is used throughout the
documentation. Generally the index is a simple and powerful concept
that should be more thoroughly explained. Likewise for moving the
HEAD, though I don't yet grok it (git-reset HEAD^, git push, git
fetch).

Squashing commits into one is something I do often, and carefully read
the manual every time, whether it's merge, rebase -i, etc. I would
expect all merge-like functions to have an option to squash all new
commits into a new single commit (rather than upon the latest commit).
I'd also expect an abort option at all times during the git rebase -i.
For example, when asked to create a single squash commit message, I
might get cold feet.

I'd expect most commands to accept a branch argument without having to
check it out first, such as git-log and git-status. Git diff might
allow flags before branch, directories, etc to avoid ambiguity (such
as when a branch and directory have the same name)

Cheers,
Alex

-- 
[ alex@genaud.net ][ http://genaud.net ]
[ B068 ED90 F47B 0965 2953 9FC3 EE9C C4D5 3E51 A207 ]

Hi Alex!

--- Alexander E Genaud <alex@genaud.net> schrieb am Di, 19.8.2008:

Von: Alexander E Genaud [off-list ref]
Betreff: Re: Call Me Gitless
An: "Junio C Hamano" [off-list ref]
CC: "Peter Valdemar Mørch (Lists)" <redacted>, git@vger.kernel.org
Datum: Dienstag, 19. August 2008, 10:57
...
Remote never seems to do what I expect, so I manually edit
the .git/refs!! 
Nor is git-reset what I expect and use git
checkout (which
does make sense only after a few backup trials). Git-add
adds to the
index but does not create, however git-rm removes from the
index and
does delete (an --index-only or --keep flag might be nice).

This is explicitely stated in the git-rm manpages: --cached:  Use this option to unstage and remove paths only from the index. Working tree files, whether modified or not, will be left alone.

A single term for cache and index should be decided upon.
git diff --cached is not intuitive when 'index' is used
throughout the documentation. 

The changes are "cached" in the "Index". But I wouldn't name the "Index" really a "Cache" because it is a lot more. All comments for --cached in the manpages mention the Index mechanism. 
Additionally there is a more detailed introduction to the Index in section 7 (Git concepts) of the Git User's Manual 

LieGrue,
strub

__________________________________________________
Do You Yahoo!?
Sie sind Spam leid? Yahoo! Mail verfügt über einen herausragenden Schutz gegen Massenmails. 
http://mail.yahoo.com 

Hi Mark,

Thanks for pointing me to 'git-rm --cached'.

The changes are "cached" in the "Index". But I wouldn't name
the "Index" really a "Cache" because it is a lot more. All
comments for --cached in the manpages mention the Index
mechanism. Additionally there is a more detailed introduction
to the Index in section 7 (Git concepts) of the Git User's
Manual

Funny the first example shows the contents of the index using a '--stage' flag.

$ git ls-files --stage
...
Note that in older documentation you may see the index called the
"current directory cache" or just the "cache".

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#the-index

To my ear, the term cache is a volatile space used for optimization,
while an index is a pointer or reference within a data structure.
Neither are obvious concerns of an end user and using both terms is
plain confusing. Staging implies something more tangible and useful to
the end user.

Cheers,
Alex

-- 
[ alex@genaud.net ][ http://genaud.net ]
[ B068 ED90 F47B 0965 2953 9FC3 EE9C C4D5 3E51 A207 ]