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: 3, Insightful) by FatPhil on Sunday August 22 2021, @05:14PM (2 children)

    by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Sunday August 22 2021, @05:14PM (#1169628) Homepage
    Agreed. Histories must be linear, as you must always be able to bisect to find a first bad commit. In a merge workflow, that's not always possible, as there's no strict order. It's entirely that there's no "first bad commit" except for the merge itself, and that doesn't even need to be one that required fixups. You just need two commits on different branches to have different locally-correct-but-globally-not assumptions. Git cannot decide which of the two is making the globally-correct assumption and which one is making the globally-incorrect assumption. They're both equally right and equally wrong. Rebasing solves this by giving primacy to one over the other. Whoever's later is definitionally the bad one, and bisect will find this trivially.

    Worst, merge-loons almost always use a logically fallacy to justify their case - they construct an example where merges do work with bisect. Which proves nothing. No number of working examples can counter one example of it failing, such as the above.

    Oh - all commits testable - never break the build.
    --
    Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves
    Starting Score:    1  point
    Moderation   +1  
       Insightful=1, Total=1
    Extra 'Insightful' Modifier   0  
    Karma-Bonus Modifier   +1  

    Total Score:   3  
  • (Score: 0) by Anonymous Coward on Monday August 23 2021, @09:53AM (1 child)

    by Anonymous Coward on Monday August 23 2021, @09:53AM (#1169807)

    I don't get your example. You are saying that Git can't decide which is correct, but then using rebasing it somehow can? Sounds more like flipping a coin than solving to me.

    • (Score: 2) by FatPhil on Tuesday August 24 2021, @09:22AM

      by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Tuesday August 24 2021, @09:22AM (#1170227) Homepage
      At least you are honest in admitting that you don't get it. Work for half a decade as a linux kernel maintainer with up to a hundred devs under you, and you might eventually get it.

      It's not that git can't decide which is (in)correct, it can't even *detect* which is incorrect. The problems can appear *only* at the final merge, possible dozens or hundreds of commits away from the ones that contradict each others assumptions (e.g. new caller assumes old helper function still can't fail on one branch, helper function starts to return error values on the other branch). But I've explained that already. Reread for comprehension, please.
      --
      Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves