For the English part of the blog, see Content AND Presentation.

2024-05-27 Git mailmap file

As everybody knows, Git has a lot of obscure commands and options. Today I’d like to write about one of them (which incidentally I mentioned two weeks ago). You can put a file named .mailmap at the top level of your Git repository, and have various names and/or email addresses mapped to a “canonical” names and addresses.

In my experience, people often have their name or email set up incorrectly. Perhaps they switch the email provider mid-project. Perhaps they get married and change their last name. Perhaps they sometimes commit from another machine where hey have their private email set up in Git.

Having commits done by the same person under different email/name combinations is sometimes a pain. I might want to look for something in commits by a given person. (I search Git histories of various repos pretty often, and the --author= option to git log is pretty useful.) I might want to gather statistics about some Git repo.

Every non-empty, non-comment line of the .mailmap file consists of the “canonical” email and/or name followed by the one(s) used in actual commits. It can be either just a “name – email” pair (in that case, the email given is mapped to the name given), or an “email – email” pair (where the second email is mapped to the first one), or an “name – email – email” sequence (where the email at the end is mapped to the name/email pair given first), or finally “name – email – name – email”, where the second pair is mapped to the first one.

See the manpage of gitmailmap to see an example. You can also check whether your .mailmap file does what you think it does using the git check-mailmap command. You can also configure Git to look for the .mailmap file under some other name, though I doubt whether it is a good idea.

And while at that, let me remind you that every Git commit has two people associated with it – the author and the committer, and that distinction can be pretty useful. Both are subject to mappings described in .mailmap, of course.

That’s it for today, see you next time!

CategoryEnglish, CategoryBlog, CategoryGit

Comments on this page

2024-05-20 Org-clockify

A long time ago I mentioned that we use Toggl in the company I work for. Being the (sole) Emacs user in the company, I (of course) use Org mode clocking features, so I wrote a simple integration for Toggl.

In the last few weeks, I played around with another time-tracking tool, Clockify. (Don’t get me started on the name, which is horrible to search for.) Of course, again I decided that I need to bridge the gap between Org mode and Clockify, and a simple global minor mode was born. It is rather bare-bones, but this is exactly what I needed. Feel free to expand it if your needs are greater.

To set Org-clockify up, you need to set org-clockify-api-key to the API key you can get from the web app. (There are a few more variables available, but you probably don’t need to bother with those. Customize the “Org Clockify” group to see all of them.)

When you say M-x org-clockify-mode, every time you stop an Org clock, assuming the headline clocked has a Clockify project associated with it (see below for how to do that), it will be submitted to Clockify. You don’t have to do anything else!

The mode has three commands in addition to the mode switching command. org-clockify-set-workspace shows a list of workspaces and lets the user select one as the default workspace. With a prefix argument, it downloads the list of available workspaces from the server first. Alternatively, you may customize the option org-clockify-workspace-id (which is what org-clockify-set-workspace sets internally). The assumption here is that you don’t switch workspaces – you set the workspace once and use it.

In a similar vein, org-clockify-set-project lets you choose the project from the default workspace. That project’s data are then put into Org properties of the current headline. The idea is that you can create an Org headline corresponding to a task, and use org-clockify-set-project to associate that task with a project.

The third command is org-clockify-submit-time-entry-at-point. It does exactly what it says on the tin, and lets you submit a time entry you clocked outside Org Clockify mode.

Happy clocking!

CategoryEnglish, CategoryBlog, CategoryEmacs, CategoryOrgMode

Comments on this page

2024-05-13 Git quick stats

A few years ago I took part in a project with a few collaborators, and I had a slightly atypical question. I wanted to know (approximately) how much each of the participants contributed to the final product. Since we tracked it in Git, the information is obviously there – for example, I can run git blame on every file in the project and see which line was contributed by who. (Important caveat: in reality, it’s “last touched” instead of “contributed”. If someone commits the line saying console.log("Hello world!") and then I run Eslint on it and change it to console.log("Hello world!");, the line counts as “mine”. This simple example shows that all statistics extracted from Git history must be taken with a solid grain of salt.)

Happily, someone created git-quick-stats, a tool which enables just that. When you install it and run git quick-stats in your repo, you are presented with a menu of about a dozen choices. I have to admit that I’m not sure about the meaning of some of them, but I still find a few of them very interesting. Of course, there is the first one – Contribution stats (by author) – which is pretty self-explanatory (and very detailed). There is also All branches (sorted by most recent commit), which can be pretty useful to determine which branches are safe to delete. You can also list all the contributors alphabetically. I found this especially useful when I wanted to clean up the authors’ names using the mailmap file. Another fascinating thing to see is the Git commits per hour chart – for example, at my day job all the contributors live in the same timezone, so the chart looks slightly boring, but it’s pretty nice to see that we seldom finish work at home;-). I also took a peek at my personal distribution of commits per hour using Git commits by author per hour (note: you apparently need to type in the email then) and saw a funny pattern of over 30 commits done between 5 and 6 am (my favorite time to work on my hobby projects, but also the job project from time to time).

That’s it for today!

CategoryEnglish, CategoryBlog, CategoryGit

Comments on this page