39 how to write a good commit message

site/_freeze/posts/how-to-commit/index/execute-results/html.json

@@ -0,0 +1,11 @@
+{
+  "hash": "ccf061c41b5f1bf5bea49a93e2685063",
+  "result": {
+    "markdown": "---\ntitle: \"How to write a good commit message\"\nsubtitle: \"Keep easy trackchanges history for your project\"\nauthor: \"alex\"\ndate: \"2025-08-22\"\ncategories: [git, version-control, revision-history]\n# image: \"thumb.png\"\ntoc: TRUE\ntoc-title: \"Table of contents\"\ntoc-depth: 5\n---\n\nThis blog post covers the topic of Git commits, how it is working, and how to use them in an efficient way.\n\n## What is a commit?\n\nA commit is a snapshot of a Git repository at a specific time that will show all the changes made to the content of the repository.\n\nA commit will capture the followings:\n\n-   The author's name or ID of the commit\n\n-   The list of modified files and the comparison with the files (if any) of the source branch\n\n-   The date/time of the commit\n\n-   A message that will clearly describe (and possibly detail) the reason of the files' update.\n\nEach commit is associated to a specific identifier code.\n\n## Benefits of commits\n\nDespite the fact that making commit is mandatory when working on a Git repository to update files, there are a lot of benefits in using Git commits.\n\n### Keep clear history of changes\n\nCommonly, each program has a header that contains a *\"Revision history\"* part. Git commits can easily replace this part because it contains the main information of a classic revision history message (author, date and reason for change), associated to the full files comparisons, such as a before/after view.\n\nAll the changes of a single commit are stored in the same place. It means if you work on a single task that request to modify several programs, you can summarize the changes within one message. You do not need to open each separated files one by one to look at what was done, when, and by who.\n\n::: callout-tip\n#### Consolidate all commits of a branch\n\nEven with several commits, you can have a clear view of all the changes when merging to the source branch.\n:::\n\n### Backup save\n\nAs Git is a version control software, and each commit is a snapshot done at a current state, it is easy to go back to a previous version of a branch using commit IDs.\n\n::: callout-caution\n#### Need feedbacks - hash\n\nI think talking about `git checkout` and `git reset` here is not useful. Maybe another blog post could be interesting. What do you think?\n:::\n\n## When to commit?\n\n### Commit one file at a time or several?\n\nThe choice depends on the context and what you want to show. Generally, each commit should be dedicated to a single purpose.\n\nIf the task or feature to add is isolated to a single file, one commit message done at the end of the update can be easily readable and integrated to the history trackchange.\n\nIn the case of a debugging task over several files, one commit message per file could also be useful, or when there is a need to track the evolution of a specific dataset.\n\nWhen a change on a program affects the behavior of other programs that also needs to be updated, one commit for all the modifications can be done. Also when you decide to modify both a program and the associated documentation.\n\n::: callout-caution\n#### Need feedbacks.\n\nNeed feedbacks.\n:::\n\n## How to write a good commit message\n\nAs a history tracking, a commit message should be concise and clearly explain **what** was done and **why**.\n\n### Title\n\nThe title should be very short (around 50 characters) and explain **what was done** on which file(s) (if relevant).\n\nStarting the title with a verb is very useful to explain what was done, for instance:\n\n::: note \n`Add TRTEMFL in adae.R`\n:::\n\n\n\n```{bash}\nAdd TRTEMFL in adae.R\n```\n\n\nA naming convention can be defined at sponsor level to identify keyword, such as `Add`, `Fix`, `Remove`, `Update`, etc. The keyword can also be separated form the rest of the title using symbols such as `:` or `!` (for major or breaking changes). For instance:\n\n\n```{bash}\nAdd: TRTEMFL in adae.R\n```\n\n```{bash}\nUpdate! prim endpoint logic in efficacy (adre.R)\n```\n\n\nUsing tags that to identify the location of changes can also be an option, such as `SDTM:`, `ADAM:` or `TLF:` for instance.\n\n\n```{bash}\nTLF: create overview of AEs\n```\n\n",
+    "supporting": [
+      "index_files"
+    ],
+    "filters": [],
+    "includes": {}
+  }
+}