1. 64
  1.  

  2. 10

    Glad that this exists. Making the tutorial interactive is a great idea. A couple of things that could be improved:

    • The zoom level is all over the place on mobile (iPhone) and even when zoomed out it looks slightly wrong: https://imgur.com/a/HLbCd92
    • Navigating between sections breaks the back button (at least on my phone). The URL doesn’t change with each step and pressing back leaves the site entirely (returning to Lobsters in my case)
    1. 4

      I see the same problems with the zoom level and the back button in Firefox for Android.

    2. 8

      Find the message ID to reply to. [switch to a browser, navigate to the archives page, find the thread in question, expand the details section, select the ID, copy it, and paste it into your terminal]

      It seems like the whole point of sourcehut is to allow for a collaborative flow with git which lets you stick with your comfortable tools instead of having everything center around a web application. This section (apart from being very tedious) seems to imply the opposite.

      Meanwhile:

      Some people think that they can get away with sending patches through some means other than git send-email, but you can’t.

      You know what mail clients are really good at? Saving you the hassle of having to track down message IDs manually like some kind of cave-person! Instead of stating that it’s completely impossible to use a real mail client to send a patch (which is obviously not true) why not explain why most mail clients are bad at it?

      1. 8

        The web interface is my comfortable tool. I had a patch for Sourcehut and I literally just gave up on submitting it because of how big a PITA it was to submit. Email is terrible, I really don’t want a workflow based on email.

        1. 8

          I literally just gave up on submitting it because of how big a PITA it was to submit

          That’s probably why SirCmpwn made a tutorial. ;P

          I personally agree with you about GUIs. I think terminals are garbage for any kind of low cardinality discovery-based workflow. If I know where I’m going and what I’m doing, terminal. If I’m looking through a few different things, or I’m not quite sure what I’m looking for, GUI. If I’m looking for / operating on a gajillion things, back to the terminal.

          By most metrics I’m a terminal power user, but “fear of mice” is not one of them. If you’re fast and accurate with a mouse, no reason not to use one.

          1. 5

            That’s probably why SirCmpwn made a tutorial. ;P

            A tutorial is nice, but what I really dislike is that I’ll do the configuration once then not touch it for months (and forget how it works) until one day it breaks as I’m trying to use it. It’s the same reason I don’t run my own web or email server: I really, really don’t want to increase my “sysadmin” burden.

            That being said, kudos to him for making it easier for people who were more “on the fence” than myself. But personally I’ll wait for the web interface :-)

            1. 4

              “By most metrics I’m a terminal power user, but “fear of mice” is not one of them. If you’re fast and accurate with a mouse, no reason not to use one.”

              Now that’s a great philosophy for UI’s. :)

          2. 1

            This section (apart from being very tedious) seems to imply the opposite.

            It doesn’t imply the opposite, it’s basic awareness by the author. Those instructions are universal and easy, all kinds of readers will follow along just fine. If you care deeply about avoiding a web interface, you probably know how to find the Message-ID header in your mail client on your own. If you don’t, figure it out on your own. It’s not important to this tutorial.

            You know what mail clients are really good at? Saving you the hassle of having to track down message IDs manually like some kind of cave-person!

            What’s your point? Does your mail client automatically populate replies to threads with your updated commits? No. So why complain about git send-email not automatically populating Message-ID? You’re copying something somewhere either way. Between the two, copying Message-ID is a lot less error prone.

            Instead of stating that it’s completely impossible to use a real mail client to send a patch (which is obviously not true) why not explain why most mail clients are bad at it?

            Okay again, this is a tutorial. And the implication here is obvious too. If you are reading a beginner tutorial about mailing patches, you clearly don’t know anything so just use the damn tool that stops you from mailing malformed garbage to a ton of people. It’s way out of scope and anyone that cares can easily go read more elsewhere.

            For anyone who actually does want to know, instead of just bitch: a mailed git patch isn’t just a diff, it’s an entire commit serialized into an email. That serialization is extremely fragile since leading whitespace and single newlines have meaning for patches, but for email they don’t.

            When you say “most” mail clients are bad at it, you’re probably thinking of Gmail, Apple Mail, Outlook, and so on. And yes, it is literally impossible to make the Gmail web interface handle patches correctly. But you probably didn’t guess that neither Alpine nor Mutt handle patch emails correctly without multiple configuration changes. All mail clients screw it up.

            All. Of. Them.

            Use git send-email.

            1. 1

              All mail clients screw it up.

              All. Of. Them.

              Had no problems generating a patch with git am, copying it with xclip and pasting it into Thunderbird. As long as you make sure word-wrap is off everything is fine.

              1. 5

                I don’t think this is actually true; I imagine that even tho it worked in some cases it doesn’t guarantee it will work in others, and that further configuration is required for it to work consistently. (For instance, for some patches it’s important that the MUA preserve trailing whitespace.)

                But that just illustrates my point: if you tell people something that’s obviously false like “you cannot send patches with a MUA” without giving any details, they’re going to ignore you.

                I’m a big kid. I can configure my MUA.

                1. 1

                  Exactly, it’s about the edge cases.

                  I’m a big kid. I can configure my MUA.

                  The point is you shouldn’t until you have a meaningful understanding of the issues, and some actual experience with emailed patches. Because big kid or no, there’s still a nontrivial chance you’ll screw it up. There’s no edit button on an email blasted out to everyone on a mailing list, it’s a hassle for everyone else.

                  1. 3

                    I think that’s a reasonable stance; what I disagree with is the wording on the site and on sr.ht proper.

                    It’s like the author has never interacted with children. If you tell a kid “don’t touch the stove” they’re going to touch it. You tell the kid “if you touch the stove, you will get burned because it’s hot” and then they’ll actually listen. Hackers are a lot like children in that way.

                    1. 4

                      I apologize for being so harsh in my earlier comments. My frustration stems from experience with people who don’t actually listen. People who insist on using their favorite workflow at the expense of everyone else, and have the entitled audacity to complain when other people won’t go out of their way to support them. When you replied in that way, it reminded me of that kind of person. But I’m happy to explain things to people who ask nicely.

                      I’m extremely biased in favor of people who generously give up their time to write documentation and tutorials. I don’t think they deserve criticism for deciding something is out of scope, it’s much better than writing nothing at all. They already deal with so much crap from selfish needy people, they’ve earned some slack in my book.

                    2. 0

                      I use Thunderbird for all my email accounts and to keep track of my RSS feeds. I have filters set up to automatically categorize mailing lists. I can send and view mail in plain-text, or properly signed and/or encrypted with pgp. Assuming the world of mail clients consists solely of gmail/apple mail/outlook and telling people never to send mail outside of git send-email is bogus. I will continue to use my fully-featured, properly-configured MUA to send patches, tyvm.

                      1. 2

                        Cool. I recommend that you continue to use Thunderbird for all your email accounts, RSS feeds, filters, and categorization, exactly as you are now. And copy the Message-ID into git send-email. It breaks literally nothing in your workflow.

                        When you copied git format-patch output into Thunderbird, did you copy the entire git format-patch output into the message body? If you did, you did it wrong. Or did you correctly delete the first line, part of the mbox format, and copy the subsequent header lines out of the message body and into Thunderbird? If you sent multiple commits, did you ensure each commit was sent as its own email, each email subject properly used [PATCH n/m] format, and patches n>0 were all In-Reply-To patch 0?

                        Did you perform all of these manual steps perfectly without fail, and will you perform them perfectly without fail every time in the future? Did you find all of that easier than copying the Message-ID to git send-email?

                        And when you verified your patch sent properly, did you test by sending the patch to a different email address via a forwarding address a la mailing lists, copy the entire raw message source received into a file (not the message body), git am that file to a different repo clone with different name and email configured, and verify the authorship, timestamps, and all other commit metadata was perfectly preserved?

                        If not, your test was worthless. And if you did, can you prove it works for all variety of edge case patches, like patches with extremely long lines, non-ASCII characters, patches received from someone else and modified by you, and so on and so forth?

                        Assuming the world of mail clients consists solely of gmail/apple mail/outlook

                        Yes, that was clearly my assumption when I also specifically addressed Alpine and Mutt in the same paragraph. Good catch.

                  2. 1

                    Since git am doesn’t generate patches, I’m skeptical.

                    1. 1

                      Sorry, I meant git format-patch

                  3. 0

                    If you are reading a beginner tutorial about mailing patches, you clearly don’t know anything so just use the damn tool that stops you from mailing malformed garbage to a ton of people.

                    Or you’re used to sending patches via PRs or whatever other method, and come across a project that wants patches via email. You might be a git wizard otherwise, but if you haven’t used git send-email, a beginner tutorial can be helpful.

                    Does your mail client automatically populate replies to threads with your updated commits?

                    Yes. It did need a bit of configuration, but then, git send-email requires a tutorial. Thus, if an email client requires configuration to do things correctly, I’d still consider that a viable thing to do.

                    And yes, it is literally impossible to make the Gmail web interface handle patches correctly.

                    You can attach patches, and it won’t mungle them. It won’t be inline, but any reasonable e-mail client will be able to show you the patches in a reasonable manner whether attached or inlined. It’s only impossible if you aim at the lowest common denominator: terrible email clients. (Not saying anyone should use Gmail’s web interface for sending patches, but it is possible to do that.)

                    1. 0

                      You can attach patches

                      No you can’t, those emails aren’t valid patch emails.

                      but any reasonable e-mail client

                      Literally irrelevant. Does not matter at all. This is about tooling and conventions.

                      The tutorial literally says “some people think that they can get away with sending patches through some means other than git send-email,” that’s you.

                      But you can’t. You’re flat out wrong and that’s exactly why the tutorial tells you you’re flat out wrong.

                      1. 1

                        No you can’t, those emails aren’t valid patch emails.

                        But they are. That you don’t like them, or can’t work with them, that’s your and your tooling’s problem. There’s tooling that works just fine with attached patches. They may not be acceptable for git am, but git am is not the only tool. It is if you stick to core git, but if you do that, you’re limiting yourself unnecessarily. Mind you, you can always filter the mails through a filter from your MUA first, and pass the attachment as inline patches to git aim, it’s not even hard.

                        Besides, like I mentioned in my previous comment, you literally can send valid, inline patch emails, with correct threading without git send-email. Your e-mail client may need a bit of configuration, but so does git send-email.

                        This is about tooling and conventions.

                        You may be surprised, but there are communities where the convention is sending patches attached, because those are far harder to mungle, and you don’t need to send a gazillion mails for a longer branch, just one larger mail. This makes it easier to review and reply to multiple commits at the same time, which can be very useful when they’re closely related (but still separate enough to warrant being separate commits).

                        Inline patches are not the only way to email patches around. It’s the only way stock git supports, and as we can see from this discussion, also the most fragile one.

                        1. 1

                          They may not be acceptable for git am

                          This tutorial and discussion is about using the core git email workflow.

                          It’s the only way stock git supports

                          This tutorial and discussion is about using the core git email workflow.

                          you can always filter the mails through a filter from your MUA first, and pass the attachment as inline patches to git aim, it’s not even hard

                          Alright, send a patch to the LKML, and when they reject it be sure to tell them “it’s not even hard,” I’m sure that will clear everything up!

                          You may be surprised

                          Shocker, I’m not.

                          there are communities where the convention is sending patches attached

                          Communities irrelevant to this tutorial and discussion about the core git email workflow.

                          To be clear, this tutorial and discussion are about the core git email workflow. See the very first sentence of the post, a website called git-send-email.io:

                          Git ships with built-in tools for collaborating over email.

                          1. 1

                            This tutorial and discussion is about using the core git email workflow.

                            git does not include a MUA, or any other tool to fetch email, which you will still need for the workflow, and the tutorial hints at this too, with “Check your email”. It already goes beyond core git email workflow. I wasn’t criticising the tutorial either, I was criticising your comments related to it, namely to give up on one’s usual MUA in favour of git send-email, just because without configuration they screw things up.

                            Alright, send a patch to the LKML, and when they reject it be sure to tell them “it’s not even hard,” I’m sure that will clear everything up!

                            I did, way back when, it was accepted.I sent plenty of patches by email over the years, none of them were rejected on the grounds of bad formatting/threading/whatever. None of them were sent using git send-email.

                            Git ships with built-in tools for collaborating over email.

                            No, it does not. It ships with tools to send email, that’s only one part of collaboration. Besides, what I was replying to is this assertion:

                            All mail clients screw it up. All. Of. Them.

                            Which is incorrect.

                            1. 1

                              Fine. All mail clients in popular or semi-popular use, in default configuration, or configured by those who don’t know what they’re doing, will not get it right 100% of the time. Happy?

                              1. 1

                                Yes, thank you.

                2. 12

                  This is very well done, and +1 for no javascript!

                  1. 3

                    Hmm… not a huge fan of the JavaScript nav with no URL bar changing or way to link to a sub-step. As a side-effect of this, if I hit the “next” button at the bottom of a long step, the next step appears already scrolled to the bottom so I have to manually scroll up to read it.

                    Update: Showing this to macOS users at work, the first question I got was if the git from homebrew has git-send-email or not, since that’s the preferred way to install tools.

                    1. 4

                      It’s actually not JavaScript - there’s no JavaScript on this page. That was a deliberate design decision, and the tradeoff is that I can’t scroll the page up when you switch through the steps.

                      1. 4

                        Could it just be normal links instead of whatever it is?

                        1. 3

                          Maybe… I’ll look into updating that later. Would also accept a patch.

                          1. 2

                            You can use :target selectors to control visibility depending on what the document fragment is

                      2. 4

                        git-send-email is all kinds of broken on OSX because the perl dependencies get very messed up, and the problems change over time (i’ve had multiple problems with it before, each time new ones)

                      3. 2

                        Nice work. I find this email based patch workflow appealing somehow.

                        1. 2

                          There is no chance that I’m letting git know my email password.

                          With this guide, you’ll be contributing to email-driven projects like […] PostgreSQL […]

                          I suggest you don’t post your patches inline in emails to pgsql-hackers.

                          1. 2

                            What always irritated me about git and mail is the lack of good integration with magit. But I have to say that the “training mail list” is a very good idea. I just hope it won’t get abused.

                            1. 1

                              Where is this software?

                              1. 1

                                The code is here, if that’s what you mean:

                                https://git.sr.ht/~sircmpwn/git-send-email.io

                                1. 1

                                  I mean the code for git-email. I don’t see it in /bin/ in any of my distros offerings.

                                  1. 1

                                    What’s your distro? The first page should help you get the package right. Then it’ll install git send-email. Note the space - this is a subcommand of git, and won’t directly be found in /bin.

                                    1. 1

                                      What’s the binary name that ends up being called?

                                      Void Linux.

                                      1. 1

                                        It’ll probably end up in /usr/lib/git-core/git-send-email. Once you figure it out can you send a patch adding Void to the list of distros at the start?

                                        1. 1

                                          Funnily enough it’s in the default git package, so that’s good. I can test then send a PR your way.

                                          1. 2

                                            The actual git-send-email executable isn’t a binary, it’s a perl script. At one point Void had a separate git-perl package, but it was all integrated to one package a year ago. So xbps-install -S git should be all you need.

                                            1. 1

                                              Are you a Void user? You know more about this than most

                                              1. 1

                                                I used to be. I contributed to void-packages a little bit too, so that’s why I’m especially familiar with the packaging system. But I use Debian for work now, so I just switched my personal computers to Debian out of laziness. ZFS on Linux for my file server was a nice bonus.

                                                1. 1

                                                  Well, you know that Void has ZFS on Linux too, in fact that’s what my file servers are!

                                                  I use Debian for work too. Only distro I particularly like (doesn’t invisibly get in my way with SELinux) on Lightsail. It’s not so bad, so long as my directly used machines are still Void.

                                                  1. 1

                                                    Oh that’s great to hear! At the time it didn’t.

                                                    I just don’t do enough at home to justify running something different than what I work with, otherwise I’d still be running Void.

                                                    1. 1

                                                      Wow, you quit using Void before I started, my first Void install was with ZFS as root. Edit: Looking at timestamps, you contributed after zfs was quite stable, just FYI But I hear the work primacy argument.

                                                      1. 1

                                                        I installed Void sometime in early 2016 and used that same install the whole time. I remember Ubuntu had just started shipping with ZFS, so ZoL was just beginning it’s journey into the mainstream. If there was some polished Void installer supporting ZFS around that time, I wasn’t aware of it.

                                                        Still, it’s a great distro and I’m glad you’re enjoying it!

                              2. 1

                                Is in-reply-to supported by Gmail? I heard the threads are grouped by subjects.

                                1. 2

                                  Yes, it is. They also have some subject line heuristics in case a broken email client does not set in reply to.

                                  1. 3

                                    Email message threading is a sort of notoriously hard problem. See:

                                    https://www.jwz.org/doc/threading.html

                                    1. 1

                                      Nice, thanks!

                                  2. 1

                                    Nit: On step three, the link text in “feel free to email us for help” includes a trailing space.

                                    1. [Comment removed by author]

                                      1. 2

                                        Might I suggest fully reading the above website? The last item in step 5 outlines how to store your SMTP password in your .gitconfig!