Stories
Slash Boxes
Comments

SoylentNews is people

posted by janrinok on Sunday August 22 2021, @11:42AM   Printer-friendly
from the Common-Things-That-Aren't-Common dept.

I'd like some feedback from those on Soylent News about a personal project of mine -- a "unique" Git glossary. (After looking at a few terms, it should be clear what makes it unique from other Git glossaries.)

For those who use Git, it's pretty well known that Git documentation is... how shall I put this nicely? Git documentation is "difficult to understand" at times.

I never learned Git from more experienced people at the places I worked, because the groups in which I worked never used Git. That means I started learning Git on my own at home. This turned into a confusing and frustrating experience because as I tried to learn Git from different online sources and even a couple of books, I noticed a lot of conflicting information. No one seemed to be able to agree what terms to use or what certain terms meant. Turning to more official sources, it didn't get any better. Actually, sometimes it was worse.

I decided to figure out what exact Git terminology is and where things went wrong -- my glossary was born. My glossary is not meant to replace the Git documentation in any way, but to supplement it.

Pulling information from the official Git glossary, man pages, and Pro Git (the book distributed by the Git website for beginners), I realized some things that I'd never seen written down anywhere else. For instance, the term remote reference has two differing definitions, branch has five definitions, and in my detailed version of the definition of tag, I explain that I could never find any clear definition of tag.

The terms remote and tracking were the most challenging. They were so poorly defined and so poorly documented by Git that not only do they have glossary entries, but I wrote complete and highly detailed articles about them. (Links to the articles can be found in the glossary entries.)

Here are my two main links:

  • Glossary -- This is the beginning of the glossary. Under the table of contents, you can pick the term you want. Some terms have a link for "More Details" that goes into more detail about the chosen term.
  • Introduction -- This index.html file gives a link to the glossary plus the four articles that I wrote about Git terminology. It also states my target audience, where I pull most of my information from, which creative common license I use, and one or two other things.

I'd like your feedback: if you know Git well, I'd like to know if I've gone completely off the rails. If you're a casual user of Git, I'd like to know if the glossary is helpful or confusing.

Expect a few rough spots, though. The glossary is still a work in progress. There are typos, terminology that I should probably add (suggestions are welcome), and a few things that are "half baked" (although I think you'll recognize them when you see them). Nevertheless, there should be plenty enough to get a feel for what I'm trying to do.

One other thing that might interest you: The entire thing is written in html and css. There is no javascript. That means no tracking, and the files are small for the large amount of info given.


Original Submission

 
This discussion has been archived. No new comments can be posted.
Display Options Threshold/Breakthrough Mark All as Read Mark All as Unread
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
  • (Score: 2) by RS3 on Sunday August 22 2021, @06:43PM (7 children)

    by RS3 (6367) on Sunday August 22 2021, @06:43PM (#1169659)

    Thank you much for your great efforts. I've only used git a little- never any significant project (because unfortunately I'm not doing much software these days but I'd like to).

    I find most documentation, of anything, lacking. One area of lacking: documentation is written from the standpoint of someone who knows everything about the thing. So like you said, you're expected to learn the whole thing. Well that mindset is idiotic.

    But that said, most of us can't help but write things from our perspective of knowledge of a thing, and the best fix is what you're doing- people coming in from the outside working with the documentation writers. But the writers need to be open to helpful change suggestions, and exert some control over their egos.

    Over the years, "quick start" guides have become more prevalent and are often very helpful.

    In recent years I was doing a lot of Apache and mysql configuration and tuning, and find the documentation is awesome. But, you can change something and not realize the many other things that are affected. One example: you can change a variable, buffer size, etc., and some only affect 1 parent process and RAM consumption, but others are per child worker and suddenly you have dozens of processes eating up all of RAM and you thrash and you have a really hard time stopping the whole process. (I'd love to see a no-thrash code added to Linux. I'm okay with swapping out little used processes, but at some point, disk thrashing brings the whole system down and defeats the very purpose of swapping...)

    I don't know- is there a discussion blog for git? Perhaps there are others like you who are trying to improve things, and you can join them? There's power in numbers.

    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2  
  • (Score: 2) by Common Joe on Monday August 23 2021, @12:47AM

    by Common Joe (33) <{common.joe.0101} {at} {gmail.com}> on Monday August 23 2021, @12:47AM (#1169724) Journal

    I don't know- is there a discussion blog for git? Perhaps there are others like you who are trying to improve things, and you can join them? There's power in numbers.

    I tried the reddit subgroup "r/Git" which looked active on the surface, but my posts didn't seem to elicit much enthusiasm. (Thankfully, there's been a lot more interest on SoylentNews.) There are one or two other groups I am eyeballing, but looking at the frequency of their posts, they seem even more dead than Reddit. I haven't tried IRC channels because I'm in a time zone which isn't great for chatting with other Americans (I live in Europe) plus I have no fixed sleep schedule right now. Work is about to get more active, so it will become more difficult for me to donate so much time to this project.

    I've been avoiding the people who head up the Git project at Google for a few reasons, but the biggest one right now is that it's not the greatest plan to ask the lead programmer noob questions.

    I started talking to one guy who submitted patches to Git and takes the side of revising Git so it's more noob friendly. Unfortunately, not only is he often too busy to respond, but he just got kicked off the Git mailing list for 3 months for reasons he doesn't understand.

    Over the years, "quick start" guides have become more prevalent and are often very helpful.

    This is one of the big reasons I tried hard to stick to the official Git terminology. If I can't get the Git team to work with me, then at least my glossary can be used to better unify the terminology of quick start guides written by others. I didn't want to write yet another quick start guide as there are some nice ones already out there. But the terminology that many of the quick guides and articles use are just plain wrong... ugh, those were so frustrating to read.

  • (Score: 3, Informative) by coolgopher on Monday August 23 2021, @03:17AM (5 children)

    by coolgopher (1157) on Monday August 23 2021, @03:17AM (#1169747)

    (I'd love to see a no-thrash code added to Linux. I'm okay with swapping out little used processes, but at some point, disk thrashing brings the whole system down and defeats the very purpose of swapping...)

    Sounds like you want to look at “sysctl vm.overcommit_memory”.

    • (Score: 2) by RS3 on Monday August 23 2021, @06:21AM (4 children)

      by RS3 (6367) on Monday August 23 2021, @06:21AM (#1169764)

      Thank you, that's awesome. I had seen that somewhere but forgot about it. I don't currently have swapping problems, but years ago one older server that I inherited had some runaway processes that would chew RAM and lock up the server. swapoff -a works too. :)

      • (Score: 3, Informative) by coolgopher on Monday August 23 2021, @09:02AM (3 children)

        by coolgopher (1157) on Monday August 23 2021, @09:02AM (#1169795)

        The overcommit_memory tweak can do more for you than just disabling swap can do. I learned about it the hard way after a ZFS import on a Raspberry stopped working for unknown reason, and would reliably OOM and/or panic the kernel every single boot. After a lot of troubleshooting I narrowed it down to having something to do with memory allocation. It turns out that by default the Linux kernel makes assumptions along the lines of "sure, this program requested 8GB of memory and I only have 4GB available, but it will probably not try to use the full 8GB anyway, so I'll approve the allocation request". Depending on the type of things you run, that may be a valid assumption. For a ZFS import it was absolutely not. Once I disabled the overcommit, the ZFS import got told by the kernel it couldn't have as much memory as it wanted, and it then effectively went "okay, it'll be a bit slower to the import with less memory, but no worries" and finished up successfully.

        TL;DR: Lying about available resources is bad, and Linux does it by default.

        • (Score: 2) by RS3 on Monday August 23 2021, @05:20PM (2 children)

          by RS3 (6367) on Monday August 23 2021, @05:20PM (#1169921)

          Thank you so much! We need a mod for "informative + funny".

          Seems like that setting needs to be default on most systems, maybe just change the default in the kernel configs.

          • (Score: 3, Informative) by coolgopher on Monday August 23 2021, @11:34PM (1 child)

            by coolgopher (1157) on Monday August 23 2021, @11:34PM (#1170060)

            I admit I was quite stunned when I discovered this (default) setting. The old "swap = 2x RAM" adage was, to my knowledge, pretty much the answer to the issue of programs allocating but not actually using all the allocated memory. The swap file was there for when it turns out the programs did in fact use more than estimated. Having something willy-nilly promise that the memory is there even when it's not seemed like a remarkably "brave" thing to do.

            And yeah, for small systems / server systems, vm.overcommit_memory will get set to 2 going forwards for me, thank-you-very-much. Having non-deterministic failure modes is not my idea of fun.

            • (Score: 2) by RS3 on Tuesday August 24 2021, @12:24AM

              by RS3 (6367) on Tuesday August 24 2021, @12:24AM (#1170078)

              This is all excellent, thank you. I typically make swap 1/2 RAM or so. Tough crap to whatever wants more. Too difficult to deal with a swap-thrashed system.

              I'd like to think of swap in 2 ways- processes that have slept for long times, and I notice long-running kernels will swap out such things, even if it doesn't really need to. But I'm okay with that. And of course, RAM overcommits, but I'm not a fan of that behavior, unless the OS can figure out how much interactivity a process needs, IE: will it end up in thrashing, if so, don't allocate from VM. I dunno, just observation over the years. I'd love to truly stop Windows from creating swap files- you probably know that even if you tell Windows to make a zero byte swap file, it'll allocate many just to snub you.