discuss: Thread: Getting Started With Working With Git

Hi everyone,

How can I start submitting to Git? Is there a getting started guide I can
read?

-- 
Thanks,

Paul Hendricksen

Hi there again Paul,

>How can I start submitting to Git? Is there a getting started guide 
>I can read?

Yes, there are probably (entirely too many) starting points for 
learning git.  I will provide a few framing notes and some links, 
although I confess to never having taught anybody about git before.

Some framing notes:

  * git is a distributed version control system

  * every file is hashed and stored by its hash

  * all other objects are also identified by a hash; blob, tree, 
    commit, tags, files and other objects are also identified by a 
    hash; this is fundamental to git (and, similarly hg)

    computer scientists refer to this as content addressable 
    storage [0])

  * each person who has a copy (clone) of the 'git' repo has the 
    whole repository with its entire history

  * the special .git directory contains the repository and entire 
    history of the repository; most times you want to be working at 
    the newest edge of history and making your changes there; by 
    default when you 'git clone', you'll not only get the whole 
    repository (required), but also a complete checkout into your 
    local working directory of the most recent (newest) master 
    branch; this represents the newest files

  * each git history is stored internally as a special kind of tree 
    called a directed acyclic graph (DAG); a copied repository 
    history can be newer (more changes than on the original) or 
    older (the original has been updated SINCE copying or cloning)

    (to visualize the DAG, see: https://github.com/tLDP/LDP/network
    for our project; I don't quite understand why my name is there 
    and not mkomarinski's who has recently contributed, but you can
    get the idea of independent "forks" of a project proceeding in 
    independent histories and watch them get merged back into the 
    canonical TLDP repository) [You can look at this on any 
    github.com project you like--useful for visualizing the 
    abstract concept here.]

  * by convention, each project identifies a canonical repository
     
    Ours is:  http://github.com/tLDP/LDP (for most of our documents)

    It is merely convention that a specific repository is regarded 
    as the canonical repository.  But, that's useful for us humans.

  * when somebody makes changes in his/her git repository and wishes 
    the canonical source to accept them, this is called a "pull 
    request" because the admins of the canonical service will, 
    essentially accept and merge in the changes by PULLing the 
    changes into the canonical repository

  * if multiple contributors make changes to the same file (in 
    separate locations), you MIGHT have a problem with merging those 
    changes; this is where careful attention is required by the 
    person accepting the 'pull request' and ideally the person 
    initiating the request

  * internally, each contributor's copy of the git repository may be 
    at a different position in a shared history; some may be ahead 
    of the canonical repository; some may be behind;

Links:

  * The canonical git documentation and pages:
    http://git-scm.com/doc

  * GitHub has a Hello World tutorial that you can walk through 
    with your own account.  They also provide a training system 
    that is targeted to CLI freaks and their web interface:
    https://guides.github.com/activities/hello-world/
    https://training.github.com/kit/

  * This was instructive for me when trying to conceptualize git.
    http://eagain.net/articles/git-for-computer-scientists/

  * Here's another, more colloquial introduction to the concepts 
    around git (I like it, even though I haven't finished reading 
    it yet):
    http://gitolite.com/gcs.html#(1)

There are probably other links and resources, however, I'm not sure 
which ones to best suggest.  I found the O'Reilly book pretty useful 
when I was still becoming familiar with git:

  http://shop.oreilly.com/product/0636920022862.do
  (Of course, I can't find my copy now!  Too much moving around!)

Finally, here's what I might suggest to get started, assuming you 
are comfortable with github.com:

  * make a github.com account for yourself 

  * fork the TLDP repo 

  * make a trivial change (CLI or web interface) to one of the
    one of our document (say, for example, 
    LDP/LDP/howto/linuxdoc/Template-Linuxdoc-Small-HOWTO.sgml)

  * issue a pull request

  * enjoy an cup of tea to celebrate success when your first pull 
    request is accepted into the canonical repository

Comments:

  * I don't completely 'get' the way that github.com works as I'm 
    web interface impaired, i.e. I prefer the CLI.  I hope I didn't 
    suggest anything that is impossible or tricky with their UI.

  * If you don't like github.com, you can still clone freely without 
    registering on their service; and we (somebody, probably me for 
    now) can apply patches supplied via email.

  * I would recommend trying to understand the git conceptual model 
    first and then play a little bit.

Thank you for asking....

Good luck and enjoy,

-Martin

 [0] https://en.wikipedia.org/wiki/Content-addressable_storage

-- 
Martin A. Brown
http://linux-ip.net/

On 2/3/2016 6:11 PM, Paul Hendricksen wrote:
> Hi everyone,
>
> How can I start submitting to Git? Is there a getting started guide I can
> read?
>

Hi Paul,

Here's the steps I've been going through (and it's partially documented 
at 
https://github.com/tLDP/LDP/blob/master/LDP/guide/docbook/LDP-Author-Guide/git.xml 
).  I'd say be sure to go through Martin's e-mail and make sure you 
understand how git and GitHub work.  If you get yourself in a state 
where git gets all confused, there's no harm in deleting your local 
repository or deleting your Forked copy (you'll see big warnings about 
this, but it'll only affect your private fork) and starting over.  You 
don't have the authorization to make changes to the LDP repository so 
you can't mess anything up.

First time use:
1) git clone https://github.com/tLDP/LDP
(after this you'll have an LDP directory with the entire tree of ~400MB)
2) From your GitHub account, Fork the LDP repository into your private 
repository
3) git remote add upstream ####@####.####

Each time you have an edit:

3) Find the HOWTO/Guide you'd like to edit
4) git checkout -b MyNewBranch
(MyNewBranch  is a name that can be whatever you want, I usually make 
the name relevant to the changes I'm making)
5) Make the changes you'd like, verify the XML is valid, etc.
6) git diff .
(verify the files and changes you're proposing)
7) git add changedfile.xml
(you can list multiple files here)
8) git commit -m "I modified these files in this way"
(if you just say 'git commit' you'll be dropped into a text editor)
9) git push -u upstream MyNewBranch
(this pushes your changes to your Forked copy of LDP)
10) From the GitHub website, you'll see that you have a new branch on 
your Fork and a button for generating a pull request.  Clicking that 
will generate a request to the LDP staff to review and approve the 
change.  You'll get an e-mail when the pull request is approved

Once the change is approved, you now need to clean up and update your 
repositories:

11) From the GitHub website, you can now delete the MyNewBranch branch
12) git branch -d MyNewBranch
(deletes the local copy of your branch)
13) git pull origin master
(update your local master branch with what's on the LDP github)
14) git push upstream master
(update your forked copy)

This is what has been working for me, if anyone sees obvious flaws or 
improvements I'm happy to accept them.

-Mark

You are going to really turn off people if you want contributors to
understand how github works.  In order to upload a file of about 100K
bytes I have to first download a file of 500 MB or download 5000 times as
much as I upload!  I've only got a dialup modem on this PC of 28k bps.  It
will only take 50 hours to download if there is no congestion.

I will have some files to upload when submit is implemented.  Two are by
someone who refused about 15 years ago to submit them to LDP due to his
dislike of LinuxDoc (It couldn't print italics where he wanted it).  And
when it was suggested he use docbook, he became outraged after looking at
docbook complications.  I've put his files on my website and they get high
traffic.  They are on programming the serial port which is widely used
today for imbedded devices.  I'm not taking over maintenance of these
files and am not submitting them in my own name.  We will then have 2
howtos of the same name except I'll ask to add "-old" to the old one which
has some important info not in the newer how-to (but overall, the newer
one is better).  The author told me in an email to go ahead and submit
them to LDP if I wanted to.  Someone needs to merge them who understands
serial programming.

Also, I want to mention that the above paragraph which discusses
individual howtos, doesn't belong on the discuss list.  The high traffic
on the discuss list in the past that was not related to ldp policy and
progress turned off a lot of contributors from subscribing to it or
reading it.  I hope the same mistake isn't made again.  One person should
handle details on individual documents unless there is controversy about
the document.

			David Lawyer

> On Feb 6, 2016, at 8:48 PM, David Lawyer ####@####.#### wrote:
> 
> You are going to really turn off people if you want contributors to
> understand how github works.  In order to upload a file of about 100K
> bytes I have to first download a file of 500 MB or download 5000 times as
> much as I upload!  I've only got a dialup modem on this PC of 28k bps.  It
> will only take 50 hours to download if there is no congestion.

There is compression, and it’s only the first time that you’re downloading the entire repository.  I just did a git clone and I downloaded just shy of 150MiB (148.79 to be precise).  After that, you’re only sending and receiving deltas so your 100k upload will be ~100k.

git is used by a large number of projects that are far larger than tLDP so I don’t think that using it will be too much overhead for prospective contributors.  Though there’s no requirement to use git or github to contribute….

> I will have some files to upload when submit is implemented.  Two are by
> someone who refused about 15 years ago to submit them to LDP due to his
> dislike of LinuxDoc (It couldn't print italics where he wanted it).  And
> when it was suggested he use docbook, he became outraged after looking at
> docbook complications.  I've put his files on my website and they get high
> traffic.  They are on programming the serial port which is widely used
> today for imbedded devices.  I'm not taking over maintenance of these
> files and am not submitting them in my own name.  We will then have 2
> howtos of the same name except I'll ask to add "-old" to the old one which
> has some important info not in the newer how-to (but overall, the newer
> one is better).  The author told me in an email to go ahead and submit
> them to LDP if I wanted to.  Someone needs to merge them who understands
> serial programming.

If there’s someone on the list with this experience that is willing to do the merge, here’s a task for you.  Probably needs a review to make sure it’s still technically current.

> Also, I want to mention that the above paragraph which discusses
> individual howtos, doesn't belong on the discuss list.  The high traffic
> on the discuss list in the past that was not related to ldp policy and
> progress turned off a lot of contributors from subscribing to it or
> reading it.  I hope the same mistake isn't made again.  One person should
> handle details on individual documents unless there is controversy about
> the document.

Sounds fair.  I envision that once you get in touch with someone who can do the merge for you that this discussion can take place off list.  No need for the entire discuss list to see it.

-Mark

For what it's worth, I've had David's frustration with downloading
massive archives just to look at a couple files. I've found that doing
shallow copies (that is, appending "--depth 1" to "git pull")
significantly speeds up the process by only downloading the last N
commits, so I don't need to download everything going back to 2008 if
I just want to see how the repo looks today. I'm not sure if that's
what David meant by having to download 500 MB of files. I'm pretty
sure that you can get even more fine-grained by telling git pull to
download only a folder if that's all you want to read, but I haven't
played with it.

I'm a fan of git myself.

By-the-by, I'm fond of Pro Git by Scott Chacon which is freely
downloadable at http://www.git-scm.com/book/en/v2

On 6 February 2016 at 21:54, Mark Komarinski ####@####.#### wrote:
>
>> On Feb 6, 2016, at 8:48 PM, David Lawyer ####@####.#### wrote:
>>
>> You are going to really turn off people if you want contributors to
>> understand how github works.  In order to upload a file of about 100K
>> bytes I have to first download a file of 500 MB or download 5000 times as
>> much as I upload!  I've only got a dialup modem on this PC of 28k bps.  It
>> will only take 50 hours to download if there is no congestion.
>
> There is compression, and it’s only the first time that you’re downloading the entire repository.  I just did a git clone and I downloaded just shy of 150MiB (148.79 to be precise).  After that, you’re only sending and receiving deltas so your 100k upload will be ~100k.
>
> git is used by a large number of projects that are far larger than tLDP so I don’t think that using it will be too much overhead for prospective contributors.  Though there’s no requirement to use git or github to contribute….
>
>> I will have some files to upload when submit is implemented.  Two are by
>> someone who refused about 15 years ago to submit them to LDP due to his
>> dislike of LinuxDoc (It couldn't print italics where he wanted it).  And
>> when it was suggested he use docbook, he became outraged after looking at
>> docbook complications.  I've put his files on my website and they get high
>> traffic.  They are on programming the serial port which is widely used
>> today for imbedded devices.  I'm not taking over maintenance of these
>> files and am not submitting them in my own name.  We will then have 2
>> howtos of the same name except I'll ask to add "-old" to the old one which
>> has some important info not in the newer how-to (but overall, the newer
>> one is better).  The author told me in an email to go ahead and submit
>> them to LDP if I wanted to.  Someone needs to merge them who understands
>> serial programming.
>
> If there’s someone on the list with this experience that is willing to do the merge, here’s a task for you.  Probably needs a review to make sure it’s still technically current.
>
>> Also, I want to mention that the above paragraph which discusses
>> individual howtos, doesn't belong on the discuss list.  The high traffic
>> on the discuss list in the past that was not related to ldp policy and
>> progress turned off a lot of contributors from subscribing to it or
>> reading it.  I hope the same mistake isn't made again.  One person should
>> handle details on individual documents unless there is controversy about
>> the document.
>
> Sounds fair.  I envision that once you get in touch with someone who can do the merge for you that this discussion can take place off list.  No need for the entire discuss list to see it.
>
> -Mark
> ______________________
> http://lists.tldp.org/
>

Hi Paul,

I've been using https://git-scm.com/book/en/v2 as my guide for Git. 
It's very well written even for the newbie like me.

Jason

On 4.2.2016 00:11, Paul Hendricksen wrote:
> Hi everyone,
>
> How can I start submitting to Git? Is there a getting started guide I can
> read?
>

Le 07/02/2016 03:54, Mark Komarinski a écrit :

> git is used by a large number of projects that are far larger than
> tLDP so I don’t think that using it will be too much overhead for
> prospective contributors.

yes it is.

There are too many git, cvs, svn and not two project use the same. I 
never could work with it, specially when the use is once on a while, you 
have then lost your data...


jdd

On Saturday, February 06, 2016 09:54:54 PM you wrote:
> > On Feb 6, 2016, at 8:48 PM, David Lawyer ####@####.#### wrote:
> > Also, I want to mention that the above paragraph which discusses
> > individual howtos, doesn't belong on the discuss list.  The high traffic
> > on the discuss list in the past that was not related to ldp policy and
> > progress turned off a lot of contributors from subscribing to it or
> > reading it.  I hope the same mistake isn't made again.  One person should
> > handle details on individual documents unless there is controversy about
> > the document.
> 
> Sounds fair.  I envision that once you get in touch with someone who can do
> the merge for you that this discussion can take place off list.  No need
> for the entire discuss list to see it.

Interesting.  I feel just the opposite, I'll discuss why below.

Maybe we need two mailing lists, one for ldp policy (possiby to be named 
####@####.#### and one for discussion (perhaps of documents??), maybe 
named ####@####.#### ;-)

My arguments may start out a little disjointed / disorganized, maybe just some 
bullet points at first:

   * how will anyone know something is controversial before the publication of 
a howto (or other document) unless some of the points of contention 
(discussion) between a reviewer and a writer are publicized to some degree?

That's all I'll say for now.  A;though I may add more later.  I (we) don't 
want to see a repetition of the C++ Howto which was written by one author and 
apparently never reviewed by anyone until I tried reading it to learn 
something.  It was ridiculous.  (I apologize in advance--I might be mis-
remembering, it might have been the (or a) C howto.)

Randy Kramer

Hello and good morning all,

David> Also, I want to mention that the above paragraph which discusses
David> individual howtos, doesn't belong on the discuss list.  The high traffic
David> on the discuss list in the past that was not related to ldp policy and
David> progress turned off a lot of contributors from subscribing to it or
David> reading it.  I hope the same mistake isn't made again.  One person should
David> handle details on individual documents unless there is controversy about
David> the document.

Mark> Sounds fair.  I envision that once you get in touch with someone who can do
Mark> the merge for you that this discussion can take place off list.  No need
Mark> for the entire discuss list to see it.

Randy>Interesting.  I feel just the opposite, I'll discuss why below.
Randy>
Randy>Maybe we need two mailing lists, one for ldp policy (possiby to be 
Randy>named ####@####.#### and one for discussion (perhaps of 
Randy>documents??), maybe named ####@####.#### ;-)
Randy>
Randy>My arguments may start out a little disjointed / disorganized, 
Randy>maybe just some bullet points at first:
Randy>
Randy>   * how will anyone know something is controversial before the 
Randy>     publication ofa howto (or other document) unless some of the 
Randy>     points of contention (discussion) between a reviewer and a 
Randy>     writer are publicized to some degree?
Randy>
Randy>That's all I'll say for now.  A;though I may add more later.  I 
Randy>(we) don't want to see a repetition of the C++ Howto which was 
Randy>written by one author and apparently never reviewed by anyone until 
Randy>I tried reading it to learn something.  It was ridiculous.  (I 
Randy>apologize in advance--I might be mis- remembering, it might have 
Randy>been the (or a) C howto.)

OK, no objection here.  Idea of separating the realms seems sound, 
although at our current amount of list traffic and discussions, I 
wonder about the need.  But, it doesn't hurt, I don't think to 
create a new mailing list.

My one thought is that ####@####.#### has been the main place 
for overall policy, procedure, license and what-should-we-do 
conversations in the past.  I have a slight preference to retain 
that function of this list.  It's still open to all.

Here's my proposal (along with some implicit volunteering):

  * create ####@####.#### as a mailing list for anybody
    interacting with TLDP who wants or needs support or help of any 
    type; clearly this would often be authors [if people would 
    prefer to call it ####@####.#### that's fine with me]

  * retain ####@####.#### and use it as it has always been used

  * forward ####@####.#### to me (and anybody else who wants 
    it); submit@ would be used to accept documents and patches 
    outside of the GitHub system.

  * forward ####@####.#### me (and anybody else who wants 
    it) [if we want to continue using that address...I'm not sure 
    why it existed initially]

-Martin

-- 
Martin A. Brown
http://linux-ip.net/