On Git

Git is a communication mechanism first and a code archive mechanism second.

or something to that effect. Origin unknown

You can argue about it as part of a code sharing (in addition to communicating about the code) mechanism second, a deployment solution third, and so on, but the above is the essence. Git is the content that you communicate over email, SSH/GitHub/GitLab/SourceHut/Bitbucket/whatever, git-svn, whatever, so communicate the right thing and well. Do not treat it as a dumping ground.

You can use Git GUIs and TUIs if you like, but those aren’t excuses for not generating exactly the same quality product. Understand what result you need in Git then figure out how to do it in your UI, not let the UI/UX create some result.

Git is not GitHub and GitHub is not Git

GitHub and GitLab especially encourage some specific bad practices and encourage complacency:

• Reviewing whole MRs instead of commit by commit
  • Especially since you cannot comment on commits, only lines of code
• Trusting the forge, not the (signed) commit
  • Especially if you let the forge rebase or squash on your behalf.
• Reviewing commits alphabetically instead of top-down (directory structure or meaningfully)
• Treating Git as a linear set of changes rather than a subset of a graph
  • There is nothing like git log --graph --oneline --all in GitHub or GitLab.
• Using slow, mediocre, and inflexible JS-heavy diff views within already slow Chrome/Edge/Blink on your underpowered netbook
  • The reference Git implementation has supported detecting moved lines of code for years. Still no sign or mention of it in GH or GL.
  • Character-only diffs and word-only diffs (with sensible defaults or custom patterns) are not a thing.
  • Following the changes to a particular file or function quickly, especially without having to wait for a page navigation or AJAX/fetch() call to load more data or the next item in the history.
  • Searching for commits that introduce a substring is impossible and unheard of.
• And more I’ll think of later

On the other hand, git forges have done some public good, but you must not use them dogmatically their way just because ‘everybody else’ does.

Please see the How the [Linux kernel] development process works and open your mind to the possibilities of Git regardless of the transport. Git is about the content, not where it is hosted.

Recommended reading

• How to write a Git commit message, by Chris Beams

  • I CANNOT STRESS ENOUGH HOW MUCH YOU SHOULD READ THIS.
  • Good English is also de rigeur, and not just the grammar, orthography, etc. but effective communication… in English. And yes, I know I could take my own advice.
  • pjreddie/darknet is funny for pjreddie and pjreddie alone. It is not appropriate in a shared collaborative space, contractual deliverable, or even a non-collaborative public good project where people need to know why you did something so they can use it, extend it correctly, fix it, know if it’s still relevant, etc.
    • 🔥🔥🔥🔥🔥🔥🔥
    • what’s everyone’s favorite dubstep artists? i like skrillex and knife…
    • I don’t know what you’re talking about Alexey…
    • guys one of my beehives died :-( 🐝 💀 Beehive deaths are in fact sad though. And to hell with you if you’re that neighbour who reported a beehive to bylaw.

• Submitting patches: the essential guide to getting your code into the kernel

  Especially:

  • § Describe your changes
  • § Separate your changes
  • § Style-check your changes
  • § Select the recipients for your patch
  • § No MIME, no links, no compression, no attachments. Just plain text
    • Recontextualise to git forges too!
  • § Respond to review comments
  • § Use trimmed interleaved replies in email discussions
    • Recontextualise to git forges too! Use proper style, and not TOFU, but with just enough proper quoting, when responding to comments in whatever UI you use, whether Quilt/Patchwork or GitHub.
  • § Don’t get discouraged - or impatient
  • § When to use Acked-by:, Cc:, and Co-developed-by:
    • Git has no inherent notion of multi-authorship, approver/sign-off, etc. Document these manually were appropriate, and configure your Git forge to add these automatically to merge commits. GitLab can do so with merge commit templates.
  • § Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes
    • Same as above.
  • § Backtraces in commit messages

  See also related docs:

  • Modifying patches

  • Rebasing and merging

    • For real-world advice on when each is appropriate, especially in a large repo.

  • Creating pull requests

    • Even if email and fetch/merge-oriented, this is still almost entirely relevant to code forges. Communicate. The dev process is a human problem as much as it is a technical one.

  • HOWTO do Linux kernel development

    Specifically only:

    • § Break up your changes
    • § Justify your change
    • § Document your change

    which apply to all projects, not just the kernel.

  • Andrew Morton’s The Perfect Patch

  • Kernel maintainer PGP guide

    Specifically only:

    • § Move the subkeys to a dedicated crypto device

  In general, many of the official documents on Linux kernel development process are worth reading, not just seeing, because they have analogues in your programming language, open-source community, or even your corporate world.