Stories
Slash Boxes
Comments

SoylentNews is people

posted by janrinok on Sunday August 22, @11:42AM   Printer-friendly [Skip to comment(s)]
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.
(1)
  • (Score: -1, Offtopic) by Anonymous Coward on Sunday August 22, @12:14PM (1 child)

    by Anonymous Coward on Sunday August 22, @12:14PM (#1169570)

    Little Shop of Horrors - Feed Me (Git It) Lyrics
    ==========================================

    Feed me, feed me, feed me
    Feed me Seymour
    Feed me all night long

    That's right, boy!
    You can do it

    Feed me, Seymour
    Feed me all night long
    'Cause if you feed me Seymour
    I can grow up big and strong

    Would you like a Cadillac car
    Or a guest-shot on Jack Paar?
    How about a date with Heady Lemarr?
    You gonna get it
    If you want it, baby

    How would ya like to be a big wheel?
    Dinning out for every meal
    I'm the plant that can make it all real
    You're gonna get it

    Hey, I'm your Gennie
    I'm your friend
    I'm your willin' slave
    Take a chance, feed me yeah

    You know what kinda eats
    The kinda red hot treats
    The kinda sticky licky sweets I crave

    Ow! Come on, Seymour
    Don't be a putz
    Trust me and your life will surely
    Rival King Tuts
    Show a little initiative, boy
    Work up some guts
    And you'll get it

    I don't know, I don't know
    I have so, so many strong reservations
    Should I go and perform mutilations?

    Think about a room at the Ritz
    Wrapped in velvet, covered in glitz
    A little nookie gonna clean up those zits
    And you'll get it, uh huh

    Gee I'd like a Harley machine
    Take it around like I was James Dean
    Makin' all the guys on the corner turn green
    So go get it, woo woo woo

    If you wanna be profound
    If you really gotta justify
    Take a breath and look around
    A lot of folks deserve to die

    {Stupid woman!
    Crashed one of freakin' scatter brains
    I'm sorry, [Incomprehensible]
    Files of the murder [Incomprehensible]}

    If you want a rationale
    It isn't very hard to see, no, no, no
    Stop and think it over pal
    The guy sure looks like plant food to me
    The guy sure looks like plant food to me
    The guy sure looks like plant food to me

    He's so nasty treatin' her rough
    Smackin' her around, and always talkin' so tough
    You need blood and he's got more than enough
    I need blood and he's got more than enough
    You need blood and he's got more than enough
    So go get it

    • (Score: 2, Touché) by sgleysti on Sunday August 22, @03:54PM

      by sgleysti (56) on Sunday August 22, @03:54PM (#1169608)

      Had you modified the phrase "get it" to "git it" throughout the lyrics, I would have modded up.

  • (Score: 0) by Anonymous Coward on Sunday August 22, @12:15PM (12 children)

    by Anonymous Coward on Sunday August 22, @12:15PM (#1169571)

    The git documentation always seemed sketchy to me, and while I was able to get through some of it, tags and branches always seemed to run into cornercases especially in the old days. I mostly haven't been doing advanced activities with with git in the years since as my code development has waned, but this looks to be a good read wen I have more time to do more than skim.

    P.S. Thank you very much for keeping to CSS and HTML. I am getting tired of every site and web page requiring javascript just to read the static elements, nevermind the dynamic ones. It gets quite tiring having my browser lag from all the crap javascript running in the background and sucking up memory.

    • (Score: 1, Informative) by Anonymous Coward on Sunday August 22, @12:23PM (4 children)

      by Anonymous Coward on Sunday August 22, @12:23PM (#1169573)

      P.S. Thank you very much for keeping to CSS and HTML. I am getting tired of every site and web page requiring javascript just to read the static elements, nevermind the dynamic ones. It gets quite tiring having my browser lag from all the crap javascript running in the background and sucking up memory.

      This.... and those youtube videos that say they explain a thing, so you have to watch the whole thing to learn that the info you're looking for isn't in them.

      • (Score: -1, Flamebait) by Anonymous Coward on Sunday August 22, @05:03PM

        by Anonymous Coward on Sunday August 22, @05:03PM (#1169624)

        That's all youtube videos. They're just a vehicle for "personalities".

      • (Score: 2) by Lester on Monday August 23, @07:28AM (2 children)

        by Lester (6231) on Monday August 23, @07:28AM (#1169774) Journal

        Yeah. People seem to have forgotten how to read.

        A web page with a few screenshots can be skimmed in a minute, so you find the point where the information you are looking for is. With a video you must go through 10 minutes to reach the same point... if it has ever been there.

        And I really don't think that making a video requires less effort than a web page.

        • (Score: 0) by Anonymous Coward on Monday August 23, @01:14PM (1 child)

          by Anonymous Coward on Monday August 23, @01:14PM (#1169843)

          And I really don't think that making a video requires less effort than a web page.

          This is where you're wrong. Video is an opportunity for the duckspeaking social idiots to social duckspeak to other duckspeaking social idiots, all of whom have no depth of understanding of the topic. It requires way less effort than learning the topic in the amount of detail required to commit something to writing.

          You might think you'd at least need an outline or a script to make a video? Nope lol! You just put your smrtfone on a selfie stick and hit record and duckspeak your superficial rituals at the camera, then hit upload. Only takes a few more seconds to upload, and saving time is important in today's increasingly increasing world.

          I might just be jaded because I'm trying to learn Blender and Unity to make a VRChat avatar, and I am going to scream if I watch one more video that goes, "Check this box and this box, no idea what these do lol, but it doesn't work without these checked."

          • (Score: 2) by Common Joe on Monday August 23, @02:09PM

            I'll say this: The big glossary page I made took a tremendous amount of my time. I wouldn't be surprised if I spent nearly 50 man hours just to create all the links on that one page alone. I'm not talking about layout or deciding how to better word something. I'm talking about literally deciding which word gets linked, typing <a href="blahblahblah">Something</a>, and verifying it opened up to the proper term. (I usually did that after I already typed in what I wanted to say for a term. I'd put links in for a single term all at once.)

            I knew either I put in the work, or the reader would put in work to hunt down the proper link. I decided to make it convenient for the reader. (Believe me, it was mind numbing work.)

    • (Score: 5, Informative) by Common Joe on Sunday August 22, @12:25PM (3 children)

      It is sketchy. I tried hard to iron out corner cases with some creativity, but there are places where there are gaping holes in the original documentation. No amount of creativity on my part can fix that. However, I think I got tags and branches pretty well ironed out. It was not obvious, though. The extra detail I wrote about tags shows why original documentation looks so sketchy.

      And yeah, I think one of the best parts about my glossary is keeping it pure HTML/CSS. If this ever takes off, I'd like to be an example / reminder of what people can do without the unnecessary fluff.

      • (Score: 1, Informative) by Anonymous Coward on Sunday August 22, @01:42PM (2 children)

        by Anonymous Coward on Sunday August 22, @01:42PM (#1169585)

        but there are places where there are gaping holes in the original documentation

        In common with a lot of new/emerging/recent technologies.
        This glossary is useful. It's doing some of the most important work in computer science : putting (the right) names on things.
        If nothing else it will help clarify what people mean when they talk about things.

        • (Score: 2, Interesting) by Anonymous Coward on Sunday August 22, @03:33PM (1 child)

          by Anonymous Coward on Sunday August 22, @03:33PM (#1169600)

          In common with a lot of new/emerging/recent technologies.

          It's been around for more than 16 years. That is definitely NOT new/emerging/recent tech.

          There's obviously a serious impedence missmatch between git and what most projects actually need or these problems would have been sorted out long ago.

          Git was supposed to be a replacement for the closed source version control software Linus was using. As such, it obviously suffers from the Second System effect.

          https://en.m.wikipedia.org/wiki/Second_system_effect [wikipedia.org]

          • (Score: 3, Interesting) by weilawei on Sunday August 22, @05:26PM

            by weilawei (109) Subscriber Badge on Sunday August 22, @05:26PM (#1169631) Homepage

            The problem is that people expect CVS, and get git.

            Git is far more flexible, and allows you to pick the type of workflow you need, distributed or not. Most people want it to support only the centralized workflow promoted by GitHub, and don't understand why it does anything else. To them, this is bad and confusing.

            To anyone who actually learns which parts of it are what internally, it's fairly easy to identify which parts you need to make use of, in which ways.

            The former is the Windows philosophy. The latter is the UNIX philosophy.

    • (Score: 2) by FatPhil on Sunday August 22, @05:20PM (1 child)

      by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Sunday August 22, @05:20PM (#1169630) Homepage
      What he said. I came to git from having used "enterprise" VCSs that used completely contradictory terminology, and that was a major part of the steepness of the learning curve.

      As a quick test of sanity, see what "check out" means to different VCSs. Conclusion - no powerful-enough-to-be-useful VCS is sane.
      --
      I know I'm God, because every time I pray to him, I find I'm talking to myself.
      • (Score: 2) by Common Joe on Sunday August 22, @05:27PM

        "Check out" is a good term that I hadn't thought to add to the glossary because the term is so different in Git compared to the other VCSs. I'll give some thought about if I should add it and how to add it.

        I'd love to find time to add a section that deals with the Git commands themselves (and ties into the glossary I've made). Something would definitely have to be written about "git checkout" at that point.

    • (Score: 0) by Anonymous Coward on Monday August 23, @07:10PM

      by Anonymous Coward on Monday August 23, @07:10PM (#1169975)

      Get noscript or some similar JS blocker that lets you temp or permanently allow some scripts while blocking the rest. Usually enabling the domain's own JS is enough, if not then fuck their site! I don't see a simple way past JS though, the overwhelmingly vast majority of users have it enabled so there is no negative feedback for making your browser build the site.

  • (Score: 3, Interesting) by Anonymous Coward on Sunday August 22, @12:24PM (1 child)

    by Anonymous Coward on Sunday August 22, @12:24PM (#1169574)

    Definition, Formal:
    An index or pointer that points to collection of staged files (stored in the staging area) that will probably later be committed to the local repository; The staging index is part of the staging area

    An index is an order list of pointers, list of columns with associated pointers...
    A pointer is simple "tag" or "reference" to a single item. Where an item is a row, index,....

    And just a pointer points. But that is using the same term to define the term.

    "staging part is part of staging area". Very helpful??
    A structure reffer to as "staging area" contains a pointer referred to by "staging part" that points to... Better??

    META Issue: A term being used in way that does not fit the universal meaning of the term, then clearly show / define the difference.

    Again back to "index":
    1) an array of pointers, in a given order.
    2) a free standing table with a list of pointers in a given order
    3) an ordered table refering to and is made from a data table, continaing columns from and pointer original row in data table.

    IF you are creating to give clarity. Then please give clarity. So terms based on true dictionary meaning, The show how this term is liek or not like true meanings.

    PS: even dictoionaries this last part wrong. Beucase they assume you have learned fundimental concepts. I once looked the word "two" --> "one more than one". Then looked up "one" --> "unity". Then looked up "unity" --> "one". loops forever.

    • (Score: 3, Interesting) by Common Joe on Sunday August 22, @12:39PM

      From my glossary:

      An index or pointer that points to collection of staged files

      Good catch. I've been looking at this stuff for so long, that one escaped me. I'll fix it soon.

      As for the rest of your reply: the original Git terminology (which I tried very hard to stick with and not change) backed me into a wall -- especially with index, staging index, etc. I have an entire article dedicated to this. It becomes difficult to figure out better terminology to use when Git abused the terminology this bad. I started using "pointer" a lot since it didn't seem to be used by Git yet, but I admit it can make what I wrote a bit wonky.

      If someone else has some input about how to better this area, I'm open to suggestions.

  • (Score: 0) by Anonymous Coward on Sunday August 22, @12:28PM (11 children)

    by Anonymous Coward on Sunday August 22, @12:28PM (#1169577)

    Quickly reading through parts, I find this very usefull. You mention that even the official documentation is sometimes wrong or incomplete... have you considered taking things to the official git developers and offer pull requests to improve the official documentation?

    • (Score: 3, Interesting) by Common Joe on Sunday August 22, @12:52PM (10 children)

      I have considered this. There are rumors that the Git team can be difficult to work with because they have a "learn Git in its entirety" attitude. Well, using the infamous car analogy, there's no reason for me to understand how to design the pistons in an engine if all I want to do is drive the vehicle.

      In another forum, I also encountered an attitude from a couple of others who know Git much better than me. They thought there was nothing was wrong with the Git man pages. (If you're a beginner, the man pages are no place to visit.) I wrote my four articles to combat this attitude which I'm likely to encounter with the Git team. I'm not an expert in Git and I wanted feedback from others before talking to the maintainers.

      And as a last thought, I can't do pull requests because Git doesn't have a terrible glossary. This means a person can't make changes gradually in the documentation. A new Git glossary would have to be built from scratch and if it's done right, it will force the complete rewrite of the man pages at the same time. It's a massive undertaking. My glossary is actually the first step in this process. (Identify the problem, then plan out how to solve the problem, then fix the problem. My glossary is the "identify the problem" stage.)

      • (Score: 2) by Common Joe on Sunday August 22, @01:02PM (1 child)

        Typo: "because Git doesn't have a terrible glossary" = "because Git has a terrible glossary"

        • (Score: 0) by Anonymous Coward on Sunday August 22, @07:20PM

          by Anonymous Coward on Sunday August 22, @07:20PM (#1169667)

          it so needs a thesaurus, too. "you keep using that word. I do not think it means what you think it means..."

      • (Score: 2) by RS3 on Sunday August 22, @06:43PM (7 children)

        by RS3 (6367) on Sunday August 22, @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.

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

          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, @03:17AM (5 children)

          by coolgopher (1157) Subscriber Badge on Monday August 23, @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, @06:21AM (4 children)

            by RS3 (6367) on Monday August 23, @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, @09:02AM (3 children)

              by coolgopher (1157) Subscriber Badge on Monday August 23, @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, @05:20PM (2 children)

                by RS3 (6367) on Monday August 23, @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, @11:34PM (1 child)

                  by coolgopher (1157) Subscriber Badge on Monday August 23, @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, @12:24AM

                    by RS3 (6367) on Tuesday August 24, @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.

  • (Score: 0) by Anonymous Coward on Sunday August 22, @12:29PM (10 children)

    by Anonymous Coward on Sunday August 22, @12:29PM (#1169578)

    If it's that overwhelming just to use version control, what's the point? As said by many, Linux kernel probably has reasons why Git has some concepts that generally just makes it complicated to work with it on other projects. And people just use what the most famous whatever is, instead of the tools that fit the job the best ( like Slack, buaaargh ).

    I don't plan to learn Git more than Clone, Commit, Push, Pull. Other's can manage it, if i'm forced to use it. And i definately am not interested in rebasing. It's just wrong.

    Fossil is my choice. It fits my purposes and probably most projects out there.

    • (Score: 2) by coolgopher on Sunday August 22, @01:01PM (3 children)

      by coolgopher (1157) Subscriber Badge on Sunday August 22, @01:01PM (#1169582)

      Rebasing is life and sanity. Also, rebasing is hell, sometimes.

      • (Score: 3, Insightful) by FatPhil on Sunday August 22, @05:14PM (2 children)

        by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Sunday August 22, @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.
        --
        I know I'm God, because every time I pray to him, I find I'm talking to myself.
        • (Score: 0) by Anonymous Coward on Monday August 23, @09:53AM (1 child)

          by Anonymous Coward on Monday August 23, @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, @09:22AM

            by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Tuesday August 24, @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.
            --
            I know I'm God, because every time I pray to him, I find I'm talking to myself.
    • (Score: 0) by Anonymous Coward on Sunday August 22, @07:33PM

      by Anonymous Coward on Sunday August 22, @07:33PM (#1169670)

      it seems that way. until using a "normal" vcs, and running into fun like only one person can have a block-of-work checked out at a time, etc.

      but imo no VCS is really good with sql code, except as a tracker of edits. yet here some of us live, with dogmatic people who quite insist otherwise... merging sql changes is hell...sometimes even with your own codebases...

    • (Score: 2) by hendrikboom on Monday August 23, @02:11AM (4 children)

      by hendrikboom (1125) on Monday August 23, @02:11AM (#1169737) Homepage Journal

      git is complicated because it was hacked and debugged into existence.
      There is no shortage of distributed revision control systems that were designed and have comprehensible user stories.
      Some of them are older than git.

      • (Score: 2) by Lester on Monday August 23, @07:54AM (3 children)

        by Lester (6231) on Monday August 23, @07:54AM (#1169778) Journal

        In fact, most. Mercurial, fossil...

        Rebase is seen as a betrayal to what a version control is. You should never be able to re-write history.

        It is git what is an special case. Even git developers admit that there are inconsistencies and collisions in parameters.
        Git was thought overnight by Linus Torvalds and written very fast. The result is that git is a great piece o software with a few glitches. And it only has a few glitches because was designed by a genius like Linus Torvalds, that is able to keep 10 balls in the air.

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

          by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Tuesday August 24, @09:24AM (#1170228) Homepage
          You're equivocating on "rebase". Rebasing a single user's branch (which ain't in the history yet) is completely different from rebasing the shared common tree (which is the history).
          --
          I know I'm God, because every time I pray to him, I find I'm talking to myself.
          • (Score: 1, Redundant) by Lester on Tuesday August 24, @10:32AM (1 child)

            by Lester (6231) on Tuesday August 24, @10:32AM (#1170244) Journal

            rebasing is removing pages of the history. It is making changes so that you can't return to the previous state, there is no version that gets you to the precious changes.

            You are not registering changes and the repository has the full history, you are rewriting history to make it more beautiful and lineal, but loosing history steps. A bank doesn't deletes entries of your account log even if it was an error and the final balance is the same.

            It doesn't mind in which repository you do it

            • (Score: 2) by FatPhil on Tuesday August 24, @10:41AM

              by FatPhil (863) <pc-soylentNO@SPAMasdf.fi> on Tuesday August 24, @10:41AM (#1170246) Homepage
              > rebasing is removing pages of the history.

              Debunked in the post you are responding to. Rest of post unread, as it started so pitifully.
              --
              I know I'm God, because every time I pray to him, I find I'm talking to myself.
  • (Score: 2) by Mojibake Tengu on Sunday August 22, @01:17PM (4 children)

    by Mojibake Tengu (8598) on Sunday August 22, @01:17PM (#1169584) Journal

    There are at least two git-based matured wiki projects out there: ikiwiki and gitit.

    Their difference from "normal" wikis which use database backends is obvious: those above use version control system as backends.
    Technically, they are wiki compilers (static generators). That makes doing wikiing things more difficult for normal people but very easy for programmers.

    That model benefits both large projects with many people as good principle of distributed documentation and tiny one man projects as good principle of simplest as possible.
    It's trivial to integrate wiki documentation into project.

    So, instead of pure html/css website you could make your documentation to anything (git including) a full wiki.

    https://en.wikipedia.org/wiki/Ikiwiki [wikipedia.org]
    http://ikiwiki.info/ [ikiwiki.info]

    https://en.wikipedia.org/wiki/Gitit_(software) [wikipedia.org]
    https://github.com/jgm/gitit [github.com]

    --
    The edge of 太玄 cannot be defined, for it is beyond every aspect of design
    • (Score: 2) by Common Joe on Sunday August 22, @02:18PM (3 children)

      I use Git as I make changes to the glossary and push the changes to GitLab.

      I looked at several Markup languages just before I started writing div tags left and right, but they didn't have the power that I was looking for. Nevertheless, I'm unfamiliar with Ikiwiki and Gitit, so I'll take a closer look at them to see if they would helpful or not. Thanks for the tip.

      • (Score: 2) by bloodnok on Sunday August 22, @06:21PM (2 children)

        by bloodnok (2578) on Sunday August 22, @06:21PM (#1169652)

        I looked at several Markup languages just before I started writing div t...

        First off, I think this is great. Good documentation always makes things better.

        As for markup languages I tend to use docbook. It's huge and horrible to learn but it has all the power you need, and the rendering engines are eminently hackable.

        As a way of getting started, you can use pandoc (https://pandoc.org) to convert from markdown for your initial docbook layout. For me the joy of docbook is in semantic markup. I write what I mean with no concern for rendering and then let the rendering engines turn it into something more beautiful.

        I'm not suggesting that you rewrite what you already have, but if you want to get away from caring about the rendering there are worse tools and it might be worth a look. My veil project
        https://github.com/marcmunro/veil2 [github.com] uses docbook if you'd like an example with a documented build (see the docs target in GNUmakefile)

        __
        The major

  • (Score: 3, Insightful) by JoeMerchant on Sunday August 22, @07:08PM (1 child)

    by JoeMerchant (3937) on Sunday August 22, @07:08PM (#1169664)

    git is powerful. There are a LOT of different ways to use git, and many of them are "proper," without necessarily being consistent with one another.

    I knew a (certifiably insane, for other reasons) dev who insisted his local bare repositories not end in .git, because they're not required to, even though that's a convention I've seen used literally everywhere else I've ever used git and bare repositories.

    I know a certain culturally sensitive development group who feels that the term "master" is inappropriate to use in a professional setting.

    I know developers who almost never tag, but branch at the drop of a hat.

    I know (too many) developers who put a lot of big binaries in working repositories - this is the only common git practice I have encountered that I would categorically label as "poor form." We can all see why it is convenient, but it's just the wrong way to use the tool, find another place to store your big artifacts and point to them from the git repo. Your clone operations across slow connections will thank you.

    Basically, I have developed my own "git groove" of things I commonly do which meshes more or less with the people I work with. When I need to do something a little outside that groove, I google for a how-to.

    --
    John Galt is a selfish crybaby [huffpost.com].
    • (Score: 2) by wirelessduck on Tuesday August 24, @03:44AM

      by wirelessduck (3407) on Tuesday August 24, @03:44AM (#1170145)

      I know a certain culturally sensitive development group who feels that the term "master" is inappropriate to use in a professional setting.

      Git will be changing the default branch name to 'main' in an upcoming release. https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/ [kernel.org]

      Gitlab, Atlassian, and Github have already made the change for their products. https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/ [gitlab.com]

      I know (too many) developers who put a lot of big binaries in working repositories - this is the only common git practice I have encountered that I would categorically label as "poor form." We can all see why it is convenient, but it's just the wrong way to use the tool, find another place to store your big artifacts and point to them from the git repo. Your clone operations across slow connections will thank you.

      Is git-lfs the right solution to this problem? https://git-lfs.github.com/ [github.com]

  • (Score: 2) by krishnoid on Sunday August 22, @08:45PM (1 child)

    by krishnoid (1156) on Sunday August 22, @08:45PM (#1169677)

    When looking at Git beforehand, and considering the local/remote repositories and staging area and how the terminology is, er, lacking, it seems like pictures (or even animations) attached to the various terms would really help visualize what's going on.

    I had to assemble a bunch of Git aliases ('create-branch', 'commit-files', etc.) just as a reference for what the comand-line option combinations did, even when I didn't use the aliases themselves. I couldn't really understand what was going on behind the scenes until I had a better visualization of the underlying structure [youtu.be] (in this case, using tinkertoys).

    • (Score: 4, Interesting) by Common Joe on Monday August 23, @01:25AM

      I didn't want to bog down my glossary in the history of how it came to be, but it actually started out years ago as me trying to draw pictures of what was happening. It should have been a sure-shot to understanding Git, but instead I just got more confused. That ended up as one of my four articles: Is a Staging Area Part of a Repository? [gitlab.io].

      I still can't answer that simple question. And without an answer I can rely on, the idea of drawing pictures falls apart unless I'm willing to go through a massive re-write if someone can point me to a section of official documentation that shows I'm wrong. Or if the Git team decides to re-define stuff.

      There are some good pictures out there already. As much as the book sucks in certain places, Pro Git has some good pictures in there which help a lot with understanding. I like Atlassian's style [atlassian.com] of pictures the best. For some reason I don't understand yet, their pics seem easy for me to grasp.

      I do have pictures planned for the future (because I think I can produce pictures that no one has drawn yet), but it's a distant future at this point. I need to be sure about the terminology before I invest a ton of time into pictures. (I spent hundreds and hundreds of man hours on the glossary. I can foresee pictures would be very time consuming too.) There's also a section for commands I'd like to invest time into before pictures. That will take a lot of work because I'd have to get much more heavily into refspecs [gitlab.io] which will be a huge time consumer.

  • (Score: 1, Informative) by Anonymous Coward on Sunday August 22, @09:33PM (1 child)

    by Anonymous Coward on Sunday August 22, @09:33PM (#1169683)

    Nice - thanks! I had never before seen the discrepancy between annotated tags and lightweight tags. I will return to this.

    I don't see any immediate errors but I'm not a git expert.

    Also, +1 for html/css. If it was in JS I'd have never read any of it.

    • (Score: 2) by Common Joe on Monday August 23, @01:49AM

      Tags are just the tip of the iceberg. It's a great example because that bit can be quickly read, understood, and absorbed. But the other stuff I uncovered? There are really awful discrepancies that I talk about that make tags look like the mature kid on the block.

      Seriously, if you like that, wait until you read my article on Tracking [gitlab.io]. I start off with the claim that the idea of tracking doesn't actually exist in Git (despite the term showing up everywhere in Git documentation and within Git commands) and then systematically dismantle that insanity. I spent a lot of time trying to understand that mess so I could write my article. For some reason, I found writing ending of that article quite cathartic: I explain how the term "tracked file" has zip-zero-zilch to do with the terms "tracking", "remote-tracking branches", and "tracking branches".

      [Face palm] No, really. "Tracked file" has nothing to do with the other terms about tracking. I can't make this stuff up. And I can't believe I haven't seen any other articles highlighting this particular discrepancy.

      And if you just start scrolling through my glossary, you'll find descriptions about plenty of other discrepancies I found. Plenty.

  • (Score: 0) by Anonymous Coward on Tuesday August 24, @06:37AM (1 child)

    by Anonymous Coward on Tuesday August 24, @06:37AM (#1170177)

    thank you, this may be useful in the future.

    a comment on your editing process: why not write the documentation in rst/md format, and then use sphinx to generate the html version?
    editing would be trivial.

    • (Score: 2) by Common Joe on Wednesday August 25, @03:46AM

      That's an excellent question. There are several reasons.

      First of all, the bulk of the editing work would not be affected by whether I chose a markdown language. Most of the editing work was deciding what words to choose, how to arrange the sentences, deciding when terms should be quoted or linked, etc. The format which markdown would help provide was very trivial compared to the rest of the work. It's not a lot of work to write <p>BlahBlah</p> than it is to hit the enter key twice.

      Second, a huge amount of work was adding links. With a good IDE, Markdown does not reduce he amount of work it takes to add links. Often, I would write the information for a term, walk away for a while, come back to the term, edit the information, (repeat walking away and editing again as needed), then add links. The links! That was a lot of boring work. I often thought about how I could automate that, but in the end, there was no good way. I even thought about writing my own markdown language and writing a parser, but even that would have been more work.

      Third, the output must always be strictly html. I thought about whether other kinds of output would be advantageous. Splitting the glossary to LaTeX or plain text would rob the glossary of its greatest advantages -- the format and the links. Really, one of the greatest assets of the glossary is the ability to just scroll through the entire glossary, browse, and discover.

      Finally, I wrote extra div tags in the html so I could specifically format the glossary with css a particular way. If I chose Sphinx or another output generator, I would have to conform the glossary to another type of formatting. Doing so would rob the glossary of how easy it is to scroll quickly to find what you're looking for. Go look at the output of Python or Java or any other pre-formated output and see if there anything which would compare to what I have. I use font sizes, color contrast, and multiple levels of indent to indicate information. Like an old time paper dictionary, this glossary is built to scroll. There is no way I could create an entry for a term in the glossary with the level of information I provide without those extra div tags. I would have had to write them manually in the markup language... and if I did that, then the markup was really useless to me.

      Markup and Sphinx is great for simple stuff. While not obvious, my glossary formatting goes a level beyond that.

(1)