Show HN: Learn to use email with Git | Hacker News Reader

Show HN: Learn to use email with Git

git-send-email.io

170 pointsddevault71 comments

No JS - I was baffled - did not know about `<label for="<target here>">`. Nice.

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/la...

IMHO, the single-most underused HTML attribute. I get annoyed when I have to aim for the tiny box, instead of the nice long string of text next to it. Although, I can't count the number of times I was guilty of omitting it many moons ago.

I'm not sure how "proper" this is, but you can also put the checkbox inside the label, turning the whole thing into one big clickable area.

<label style="padding:5pt"><input type=checkbox> this is label</label>

Isn't it better to nest the checkbox inside the label? Then you don't need the for attribute nor an id.

That works nicely for checkboxes, but sometimes you want the form field and label to be in (say) different cells of a table row or something.

You still have to do the complementary for= and id=, but I am also a proponent of nesting, though I have not solicited public opinion on it until just now.

Here is how I started doing it:

<label for=abc><input type=checkbox id=abc ...> display alphabet<label>

What do you mean by “have to”? The whole point of nesting is that the association is implicit.

labels should always be to the right of the checkbox/radio controls. never nest them. nesting is ok for other form controls in some instances, but you'll run into issues with various screen readers if you apply the for attribute while nesting. on that note, always nest when possible; the ux benefits make it crazy not to take advantage of it.

Is there a reason to not nest the checkbox inside the label? I have always put them next to the checkbox until very recently, when I was trying to increase clickable area. I've found it ends up working much better than putting it beside, covering the area around the checkbox, too! Is this "improper HTML"?

It seems to have a cost though, how do I link to a specific page?

Anti-snark edit: what's the URL to a specific step?

Just merged this patch which makes each page linkable :)

https://lists.sr.ht/~sircmpwn/public-inbox/%3C20190404212127...

? https://git-send-email.io/#step-2

Could have used `:target` instead then.

You can't.

Well, it takes some form & css trickery as well. I'd call this more hacky than anything. It doesn't let you link to a specific step.

https://git-send-email.io/index.css

It does now, after a small patch: https://git-send-email.io/#step-2

I wanted so much to like this. The evolution of SirHat (better name :) is entertaining, and never leaving the cmdline would be great! And I was on board until encountering this type of tedium:

  Find the message ID to reply to.
  Don't stress too much about getting
  this step right, but it's a nice
  Courtesy for the people receiving
  your patch. On the mailing list
  Archives, look up the latest email
  In your thread and expand "Details"
  to find the Message ID. Copy this
  for the next step.

IMHO, needing to lookup email header IDs for each patch revision is an insane and terrible workflow! (At least, compared to gitbucketlabhub.)

I've configured my email client (Thunderbird) to display it when viewing an email. I can simply right-click on the message-id value and get a context-menu with a "copy message-id" option.

Other mail clients should have something similar.

One thing a lot of email providers (at least gmail and fastmail) do is let you create application passwords that you can use for specific purposes. So if you're at all queasy about having your password in plain text on the hard drive, you can create a special password just for git.

Edit: you don't have to set up a terminal email client at this point, but if you figure out how to use git-send-email, you're just inches away from using mutt.

The Google implementation of application specific passwords is horrible. There's nothing application specific about it -- it's valid for at least mail, calendar, and contacts, with no way to limit the scope. It ends up being a password that effectively bypasses all MFA on your Google account. Where do you store such a password? That's a powerful credential to be regularly unlocking.

I should be able to create a credential that's valid for just SMTP, with no IMAP or cal/card access at all.

If you want that level of granularity then you pretty much have to write an app but it's absolutely possible.

https://developers.google.com/gmail/api/auth/scopes

Even creating an app, the hoops are non-trivial. Due to the scope required (gmail.send), app verification and approval is required.

I've been toying with writing a credential helper to obtain the oauth bearer token, but Authen::SASL::XOAUTH2 still needs to be written so that git-send-mail knows how to use it.

That magic password is somewhat restricted as in you can only link an application with it once (which then should get an infinite token). It's mildly better. Last time I used it there were scoping options, but I might be mistaken

Huh?

The magic password is the token. The "scoping" options are just a label (I suppose this might have recently changed), mostly targeting folks who are looking at using legacy mail/cal/card clients with only user/pass support, and are unsure what's going on.

edit: Just triple checked -- the 16 character string returned when creating a "Calendar on iPhone" password works perfectly for SMTP via PLAIN over TLS.

I haven't set this up, but looking at the manpages, it seems you can set git to obtain the password from your password manager (which should keep your password encrypted). From gitcredentials(7):

> Without any credential helpers defined, Git will try the following strategies to ask the user for usernames and passwords:

> 1. If the GIT_ASKPASS environment variable is set, the program specified by the variable is invoked. A suitable prompt is provided to the program on the command line, and the user’s input is read from its standard output.

> 2. Otherwise, if the core.askPass configuration variable is set, its value is used as above.

> 3. Otherwise, if the SSH_ASKPASS environment variable is set, its value is used as above.

> 4. Otherwise, the user is prompted on the terminal.

So, for example, if you're using `pass`, the password-store, you can just set one of these to `pass smtp/me@example.com`, and pass will prompt you for your decryption password for your smtp password.

> having your password in plain text on the hard drive

That's not necessary for git. git has a facility called git credential that can allow it to cache the password (or other piece of information) for a given period of time[1]. So, when you use git send-email, it will prompt you for the the password.

[1] https://git-scm.com/docs/git-credential-cache

You can also omit it and type it in each time you use git send-email, or you can set it up with your on-site keyring using git-credential:

https://git-scm.com/docs/gitcredentials

Ah, that's quite nice. I like the ability to strike your own balance between convenience and paranoia afforded by git-credential-cache.

They're getting closer to public-key authentication, I guess that's good.

Ooooooo.

Is there such a thing as SSMTP/SIMAP (i.e. something that is to SMTP/IMAP as SFTP is to FTP - i.e. an SSH-based thing that sends and/or receives mail to/from a mail server)? It'd be badass to be able to literally just use my SSH keys to authenticate when sending/receiving mail.

I'm using a setup similar to the described one, though without SMTP or IMAP: a MUA is set to use `ssh <host> sendmail` instead of a local sendmail, and `doveadm sync sh -c ... "ssh <host> doveadm dsync-server"` for retrieval/synchronization. It's indeed nice and handy.

Edit: My setup with mu4e is described in more detail at https://defanor.uberspace.net/notes/email.xhtml

You can literally invoke imapd over ssh and it will preauthenticate as the user that invoked imapd. I used to do this with PINE 20 years ago. Good luck getting any of the big MSPs to support it, though.

I used elm back in the day. Was excited and confused when I started seeing all sorts of articles about elm, until I realized it was a different elm.

I'll have to give that a whirl. This would be with my own mailserver, so whether or not the MSPs support it is irrelevant :)

That does sound perfect. Don't know if it exists.

Can only speak for myself, but I didn't understand enough context to get much out of the site. I'm used git for small, personal collaborations, so I don't know why it sends email or when you would want it to do that. I don't know what a "patch" means here and why you use email with them.

If I'm not your target audience, then that's fine, but it might be helpful to have some background on this.

Otherwise, the site and layout look great to me. It is a little tricky to have step 1 be installation, because someone who just wants to find out more without installing might stop there (I was a little deterred, then I just picked a random OS and clicked through the instructions).

>I'm used git for small, personal collaborations

This is a great reason to use email! You don't need a platform at all, you can use the tools presented in this tutorial to email your work directly to your collaborators.

Outside of that, email is used for collaboration with many large and important projects, such as Linux, PostgreSQL, and git itself. I have some writings about why I think this workflow is nice:

https://drewdevault.com/2018/07/23/Git-is-already-distribute...

https://drewdevault.com/2018/07/02/Email-driven-git.html

(forgive the formatting on the latter, fix is being deployed now)

Thanks for the reply. I'll explain why I'm still confused/unsure what is going on, hope it is useful feedback.

My understanding of git is that there is a server, and users push/pull to the server.

So from an initial look at everything you provided, it sounded to me like git-send-email gives people email notifications to know what has been changed on the server, for example. I don't know what "email-driven workflow" means and that was my best guess.

But from someone else's reply, it sounds like you are discussing an alternative to the server model, where there is no server at all and pushes and pulls are communicated completely via email. This seems consistent with your 2018-07-02 post, but honestly I didn't really get it from there the first time. Is it correct?

> My understanding of git is that there is a server, and users push/pull to the server.

Git is a distributed VCS and so doesn't need a (centralised) server to share code.

Sites like GitHub, GitLab or SourceHut let you host a git repository that you can push/pull from. It's a convenient way of sharing code, and collaborating with others.

But you can also apply changes to a repo using patches prepared by email.

> ....where there is no server at all and pushes and pulls are communicated completely via email.

I'd emphasise that changes to a repo can come from diffs or patches as well, not just pushes/pulls from another repository.

FWIW, Git book has details about how one might make use of patches received by email. https://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a... https://git-scm.com/book/en/v2/Appendix-C%3A-Git-Commands-Em...

That's right. git stores all of the data that could be on the server on your local machine. Every clone of a git repository contains the full history of that repo. git send-email allows you to send commits to other people over email.

Okay, thanks! I am finally getting it.

The idea is that in order for multiple people to collaborate, most of the time you will need a service like Github, Bitbucket or perhaps something you can run yourself.

This is a different workflow. Instead of staying in sync via a hosted service, people stay in sync and send 'pull requests' via email.

Thanks, this response starts to remove some of my confusion. So it's git without the server, communicating pushes over email instead. (I guess you automatically pull whatever is in the emails you get?)

You get a patch file as an attachment to the email, which you can then apply to any branch on your local copy that you'd like.

git itself includes at least 2 methods of running that server itself....

``git daemon`` is entirely self-contained and permits the git:// protocol for clones/push/pull etc

``git instaweb`` will piggyback a simple git web service on top of a number of httpd's including lighttpd.

I'm sure that git's homepage used to use instaweb for it's repo access, but it seems they've switched to github :(

Before GitHub and other UIs exposing the "Git*" experience of merge/pull requests, etc there was only git and email.

I think the author of this is the same one who has pushed back against ForgeFed and is now tackling some of the criticisms shared in response to his "git is already decentralized" piece (namely, git over email being too hard or not well known enough).

Something this reminded me of: in the tutorial it is mentioned to check the project README for possible emails to send patches to, but darcs had a nice config option (pref) [1] to suggest a repository's default TO email address when `darcs send` sending an email patch. It's a small papercut in the `git send-email` workflow, but providing an automated way for a git repo to suggest its patch email list would simplify the workflow and maybe encourage more users to try it.

[1] http://darcs.net/Using/Configuration#email

This is actually something I plan on adding to git sooner or later.

Step one would be improved with a small bit of JavaScript to sniff the platform and expand the most likely section (and ideally even move it to the top). Please don’t be allergic to small snippets of JavaScript that optionally enhance things.

Keyboard and screen-reader accessibility of the radio button accordion technique is completely ruined by the use of `display: none` on the radio buttons. That could be remedied by zero-sizing them instead in one of quite a few ways. Note however that this will make Up/Down arrows switch section instead of scroll as a user might expect—that’s part of why radio buttons are not a good match for this type of widget (to say nothing of improper exposure to accessibility tech).

Keyboard accessibility is also poor due to weak and missing focus indication.

I would strongly recommend replacing the magic radio button technique with semantically and functionally appropriate <details> elements; then, if you want opening one to close the rest, add a small snippet of JavaScript to that effect. (Then users with JS disabled will be able to open multiple sections, and that’s fine.)

The use of various CSS tricks has the side-effect that scroll position doesn’t always act in the way you might expect. I recommend augmenting such cases with small JS snippets to enhance the behaviour.

Maybe I missed it, but I think it would be great to also explain what happens on the other end of this process. What does someone do when they receive a patch?

git apply filename.patch

It's a little more involved than that depending on what mail client you use. There is no git-get-email command that would standardize the experience.

The mobile version has some issues

https://m.imgur.com/a/YYnHXeM

This is great for small one-off projects, but I don't know why anyone would want to promote the usage of mailing lists in general. The industry moved on to more centralized solutions like github for a reason - mailing lists are clunky, intuitive, and simply horrible for large discussions. Because old and large projects are using them doesn't mean it's a good reason for new projects to use them today.

If anyone has problems with using closed-source platforms like github, there are open-source alternatives like gogs/gitea so you're fully in charge. Abandoning the openness of such platforms in favor of mailing lists would be a big step backwards.

One thing that mailing lists (and newsgroups) have over platforms like Github is threaded discussions. It's similar to comparing reddit and HN to facebook and github.

But email lists (and newsgroups) have one thing that even HN and reddit do not. That is, the ability to quickly see new posts. In HN, I have to search through the entire thread to find new posts when I refresh the page. It's the same issue with reddit unless you're a subreddit moderator or have a reddit gold subscription.

> mailing lists are clunky, intuitive, and simply horrible for large discussions

On the contrary, I largely prefer mailing lists for non-code discussions (i.e. things that are not code review or filing bugs). When Swift's mailing lists moved to Discourse I realized that I stopped interacting with it as much because it was more inconvenient to work with (especially on mobile).

If you self-host your own git service, you could email everyone e.g. in a specific organization very easily. On something like GitHub it's nearly impossible, but when you own your data its just a database query + email away.

You can write a web hook that'll be called by Github (authenticated with a shared secret) to do that job. Unless I don't understand the use case.

Small, one-off projects like Linux, postgres, git?

What makes mailing lists worse for large discussions? Decent mail readers support threaded conversations and decent mailing list participants know how to quote properly. This has been around for decades and I don't think github discussions add anything except more noise maybe.

Yeah, I think it's more a cultural problem than technical limitation of email system. Even many technical users nowadays lack email skills.

>Decent mail readers and decent mailing list participants

the first is rare(in that no one bothers using mail readers) and the latter is non existent in the current generation - which you do have to interact with.

Great tutorial. You may want to add a section about using git-format-patch to allow one to see the emails on disk and using git-send-email with those files. You may also want to add a caveats section about certain email providers.

In my experience, any Microsoft Exchange/O365 server will most likely mangle the email server side (introducing quoted-printable encoding characters or changing the message-id field. Gmail will require that you enable insecure application access in order to use git-send-email. If you don't do that, then using git-send-email will result in a authentication failure error (which you can see if you use the --debug flag).

Great guide but there seems to be a typo/mistake regarding how to save the smtp password in step 2/gmail: should use sendemail.smtpPass instead of the non existing sendemail.password.

Good catch! Want a chance to try out your email skills and send a fix to ~sircmpwn/public-inbox@lists.sr.ht? The git repo is here: https://git.sr.ht/~sircmpwn/git-send-email.io. If you're not interested, I'll push the fix, but figured I'd give you a chance to get credit for it.

In the e-mail reply that you get when following the guide you get something to copy paste that looks like this:

    git send-email -v2 ...

I tried to find documentation regarding the -v[0-9]+ parameter but couldn't find it at all. What am I missing in the docs? Seems a lot of guides recommend people to use this feature, however there is not a word regarding it in the git docs. It seems that it takes a positive integer as a parameter and adds it to the [PATCH v1] prefix in the subject.

This is a parameter that gets passed to git format-patch. Any parameters git send-email doesn't directly recognize are passed along to format-patch.

Aha! Makes sense. The docs are usually great for git, but it wasn't clear to me that the args were passed on to git format-patch, where the -v parameter indeed is properly documented.

The page sets a background color, but not text color. With system theme, I get white text on white background.

Looks like it'd be enough to add a "color: black;" right after the "background: white;" on line 13. I'm sure the page author would appreciate you emailing them a patch :)

I love the little avatar they have for the site. Little touches like thatare really underrated.

Reply on news.ycombinator.com