cli &mdash; csantosb https://infosec.press/csantosb/tag:cli Random thoughts Fri, 17 Apr 2026 04:58:18 +0000 git best practices https://infosec.press/csantosb/git-best-practices <![CDATA[img br/ We said #git, then. How to use git as efficiently as possible in #modernhw ? We know the answer, using a front end. Right, but then ? Following a set of simple principles and best practices that will make your life simpler. Follow me on this trip. !--more-- br/ read a couple of good references Pragmatic Version Control Using Git, Version Control with Git, 3rd Edition and Pragmatic guide to git are good examples, but there are many more around. Use them as a reference and as a starting point, and try to go beyond following your needs. br/ Check the official doc. And remember you have man git-log, man git-config, etc. at your disposal. br/ use a front end Yes, again. br/ Avoid the #cli. And try to make your text editor and your front end as good friends as possible. br/ coding Format your code properly, otherwise, diffing becomes useless, and your code diffs will be hidden by formatting diffs. Even worst, people you collaborate with will be unable to read your history. Comply to language standards. br/ changes If possible, ask your text editor to have some kind of visual hints on what you have changed, added or removed. br/ Learn how to inspect diffs between working copy and staging area, between working copy and last commit, and the contents of a commit. Learn how to discard changes. br/ commits Commits are lightweight diffs. A commit has one or two parent commits, and is identified by a unique hash. br/ Stage your changes first, commit them then. Learn how to stage chunks of changes, not all of them. br/ Remember to commit early, commit often: git is a CVS, not an archival, not a backup system. Never commit binaries (except artifacts: pdf, etc.). br/ Authentify who authors your developments and gpg-sign your commits. br/ Group changes in meaningful commits, and remember git history must be read as a novel: write meaningful commit messages. Consider that people spend much more time reading git history than writing it. br/ branches, tags and releases A branch is a pointer to a commit, and if your remove the pointer to a commit, you won’t be able to access it anymore. Branches are free (as in beer !), so branch as much as your need. br/ Tags are fix pointers (labels) to commits (aliases) They identify stages, or important hints in development. br/ Remember to always store your work hash/tag along with your results, you’ll know what you’re doing, you’ll know which version of your submodules you’re using, and you’ll be able to compare your results. br/ Releases are numbered tags, identifying accomplishments. Be familiar with semantic versioning br/ Before merging branches, understand the differences between fast-forward (advance the pointer) and non fast-forward (keep branch history in a feature branch). And learn how to resolve merge conflicts with your frontend ! br/ logs Check frequently where you are in the log history, you may get backwards in history by just moving a pointer. br/ Learn to search (and filter searches) in the log messages br/ workflows Remember local is decoupled from remote, and that git doesn’t impose any workflow, so everything is possible. br/ Learn the advised workflow in collaborative development: gitflow, and consider merge / pull requests are just artificial standards of a #gitforge. br/ At a minimum, use: br/ main, stable branch (releases only) br/ devel, working branch (commit here) br/ feature, topic-specific branch (spin-off) br/ locally Everything may be fixed while working locally. br/ Use .gitignore., locally at $GITDIR/info/exclude and at global level at ./.gitignore. For lazy people you have gitignore.io br/ git-config your environment before anything else, globally at ~/.gitconfig, at project local at $GITDIR/config. br/ You’ll find more details about all the previous here. br/]]> img
We said #git, then. How to use git as efficiently as possible in #modernhw ? We know the answer, using a front end. Right, but then ? Following a set of simple principles and best practices that will make your life simpler. Follow me on this trip.

read a couple of good references

Pragmatic Version Control Using Git, Version Control with Git, 3rd Edition and Pragmatic guide to git are good examples, but there are many more around. Use them as a reference and as a starting point, and try to go beyond following your needs.
Check the official doc. And remember you have man git-log, man git-config, etc. at your disposal.

use a front end

Yes, again.
Avoid the #cli. And try to make your text editor and your front end as good friends as possible.

coding

Format your code properly, otherwise, diffing becomes useless, and your code diffs will be hidden by formatting diffs. Even worst, people you collaborate with will be unable to read your history. Comply to language standards.

changes

If possible, ask your text editor to have some kind of visual hints on what you have changed, added or removed.
Learn how to inspect diffs between working copy and staging area, between working copy and last commit, and the contents of a commit. Learn how to discard changes.

commits

Commits are lightweight diffs. A commit has one or two parent commits, and is identified by a unique hash.
Stage your changes first, commit them then. Learn how to stage chunks of changes, not all of them.
Remember to commit early, commit often: git is a CVS, not an archival, not a backup system. Never commit binaries (except artifacts: pdf, etc.).
Authentify who authors your developments and gpg-sign your commits.
Group changes in meaningful commits, and remember git history must be read as a novel: write meaningful commit messages. Consider that people spend much more time reading git history than writing it.

branches, tags and releases

A branch is a pointer to a commit, and if your remove the pointer to a commit, you won’t be able to access it anymore. Branches are free (as in beer !), so branch as much as your need.
Tags are fix pointers (labels) to commits (aliases) They identify stages, or important hints in development.
Remember to always store your work hash/tag along with your results, you’ll know what you’re doing, you’ll know which version of your submodules you’re using, and you’ll be able to compare your results.
Releases are numbered tags, identifying accomplishments. Be familiar with semantic versioning
Before merging branches, understand the differences between fast-forward (advance the pointer) and non fast-forward (keep branch history in a feature branch). And learn how to resolve merge conflicts with your frontend !

logs

Check frequently where you are in the log history, you may get backwards in history by just moving a pointer.
Learn to search (and filter searches) in the log messages

workflows

Remember local is decoupled from remote, and that git doesn’t impose any workflow, so everything is possible.
Learn the advised workflow in collaborative development: gitflow, and consider merge / pull requests are just artificial standards of a #gitforge.
At a minimum, use:

main, stable branch (releases only)
devel, working branch (commit here)
feature, topic-specific branch (spin-off)

locally

Everything may be fixed while working locally.
Use .gitignore., locally at $GITDIR/info/exclude and at global level at ./.gitignore. For lazy people you have gitignore.io
git-config your environment before anything else, globally at ~/.gitconfig, at project local at $GITDIR/config.
You’ll find more details about all the previous here.

]]> https://infosec.press/csantosb/git-best-practices Mon, 02 Dec 2024 20:27:56 +0000 sourcehut crash course https://infosec.press/csantosb/sourcehut-crash-course <![CDATA[img br/ Everything you need to get started with sourcehut, an original and interesting #gitforge . !--more-- br/ #Sourcehut is organized in independent, closely related services. #Git repositories, #maillists, #wiki pages, #bug trackers, etc. belong to different domains, see below. They cooperate to provide a pleasant and practical experience when doing #modernhw. br/ Check the official documentation for details in all that follows. br/ Each user is given a ~alias. Each user’s service will appear under the SERVICE.sr.ht/~user domain, and are accessible in the top panels of the web interface. br/ Main services are: br/ git git.sr.ht/~user/project, #git repositories. br/ There are no groups to combine them. I use dot notation to group my projects git.sr.ht/~user/group1.prj1. br/ builds builds.sr.ht/~user, task building service, with the list of builds by the user, with user’s recent activity. br/ builds.sr.ht, similar to the previous. br/ Builds are trigger by a .build.yml manifest, or by a .build folder folder with up to 4 manifest files, at the root of a project. br/ It is also possible to automatically submit builds when a patch to a repo with build manifests is sent to a mailing list. This is achieved by appending the project name as a prefix to the subject of the message, for example [PATCH project-name]. br/ Check doc for details. br/ hub The main tab, sourcehut, gives access to the hub hub.sr.ht/~user (identical to sr.ht/~user). br/ The hub displays user’s projects. br/ Projects are groups of git repositories, #maillists and bug trackers. There may be any of them in a project. br/ Sourcehut itself is organised as a project here https://sr.ht/~sircmpwn/sourcehut, and may be used as an example. br/ todo todo.sr.ht/~user, ticket tracking service, with the list of trackers created by the user, with user’s recent activity br/ todo.sr.ht, similar to the previous br/ man man.sr.ht/~user/NAME, #wiki service to create documentation, with the wikis created by the user br/ man.sr.ht, sourcehut documentation br/ man.sr.ht/builds.sr.ht, builds service documentation br/ man.sr.ht/hub.sr.ht, hub service documentation, etc. br/ lists lists.sr.ht/~user/NAME, #email #maillists service, with the list created by the user, with user’s recent activity br/ lists.sr.ht, lists the user follows, with recent activity br/ Extra services are alse provided: br/ chat chat.sr.ht, without the user alias, is a paid service. It provides a bouncer to save history of IRC channels while not connected, and may be used from another IRC client. br/ paste.sr.ht Paste hosting service. br/ srht.site Once again, the official documentation gives in depth details about the previous. And remember, there is also hut to operate from the #cli. br/]]> img
Everything you need to get started with sourcehut, an original and interesting #gitforge .
#Sourcehut is organized in independent, closely related services. #Git repositories, #maillists, #wiki pages, #bug trackers, etc. belong to different domains, see below. They cooperate to provide a pleasant and practical experience when doing #modernhw.
Check the official documentation for details in all that follows.
Each user is given a ~alias. Each user’s service will appear under the SERVICE.sr.ht/~user domain, and are accessible in the top panels of the web interface.
Main services are:

git

git.sr.ht/~user/project, #git repositories.
There are no groups to combine them. I use dot notation to group my projects git.sr.ht/~user/group1.prj1.

builds

builds.sr.ht/~user, task building service, with the list of builds by the user, with user’s recent activity.
builds.sr.ht, similar to the previous.
Builds are trigger by a .build.yml manifest, or by a .build folder folder with up to 4 manifest files, at the root of a project.
It is also possible to automatically submit builds when a patch to a repo with build manifests is sent to a mailing list. This is achieved by appending the project name as a prefix to the subject of the message, for example [PATCH project-name].
Check doc for details.

hub

The main tab, sourcehut, gives access to the hub hub.sr.ht/~user (identical to sr.ht/~user).
The hub displays user’s projects.
Projects are groups of git repositories, #maillists and bug trackers. There may be any of them in a project.
Sourcehut itself is organised as a project here https://sr.ht/~sircmpwn/sourcehut, and may be used as an example.

todo

todo.sr.ht/~user, ticket tracking service, with the list of trackers created by the user, with user’s recent activity
todo.sr.ht, similar to the previous

man

man.sr.ht/~user/NAME, #wiki service to create documentation, with the wikis created by the user
man.sr.ht, sourcehut documentation
man.sr.ht/builds.sr.ht, builds service documentation
man.sr.ht/hub.sr.ht, hub service documentation, etc.

lists

lists.sr.ht/~user/NAME, #email #maillists service, with the list created by the user, with user’s recent activity
lists.sr.ht, lists the user follows, with recent activity

Extra services are alse provided:

chat

chat.sr.ht, without the user alias, is a paid service. It provides a bouncer to save history of IRC channels while not connected, and may be used from another IRC client.

paste.sr.ht

Paste hosting service.

srht.site

Once again, the official documentation gives in depth details about the previous. And remember, there is also hut to operate from the #cli.

]]> https://infosec.press/csantosb/sourcehut-crash-course Fri, 29 Nov 2024 14:33:48 +0000 git https://infosec.press/csantosb/git-ytbn <![CDATA[img br/ Once upon a time, in digital electronics design, we were used to moving huge zip files around including project data, code and all ancillary stuff along with it. We were doing backups, snapshots and versioning our code with help of compressed files. That’s the way it was, I knew that time, and you, young reader, would not believe me if I told you about the whole picture. This is not acceptable anymore. !--more-- br/ Today we have (well, we already did 20 years ago, but, you know, we were electronic engineers, not coding experts after all) tools to handle the situation. We have control version, we have git, and this more than we need to follow changes in our code (and our documentation, bibliography, etc.). Sure, we need a bit of discipline to use it in meaningful way, writing clear commit messages, committing correctly, creating clean histories, using the right branching model and learning how to use #git in a collaborative way. Following best practices is something that, as for today, should be accessible to any engineer, provided he is using the right tools. br/ The point here is how to interface git. In my experience, most hardware engineers (but not only) just do basic clone, push and pull, creating linear histories. Simply put, they use git as a backup system, with huge unrelated commits. They use git because they must use git, as anyone else is doing, but without any of the associated benefits. No history read, no diffs, no topic branches, no rebasing, no merging, no nothing. The reason is they’re using the command line interface (#cli) to git. Using git in the command line is fine, provided you’re fluent with clis, with a good shell and its plugins, and you have a very good long term memory. No one remembers how to interactively rebase 10 last commits on top of another branch, squashing history. Full stop. And no one will commit every 30 seconds if it takes one minute. Forget about. This brings to the clone/pull/push/that’s it step slope most people is faced to when they use git. And, unfortunately, this is the end of using git proper. br/ Now, what to do about ? #modernhw requires using a GUI to manipulate your git repositories. This will provide you with a lot of benefits, among them, a clear overview of where you are in your git history, your current status, and most importantly, where you’re going from this point. Which GUI to use ? Don’t expect an answer from me. The one you feel more comfortable with is the right choice. No matter what, provided it is #freesoftware. Spend as many time as you need mastering its usage, you’ll be rewarded afterward. br/ Personally, as I’m using #emacs, my not that original choice goes to using #magit. Magit is a front end application to the command line git, closely embedded within the rest of my workflow. As usual, once one gets used to its way of doing things, it’s really fast to perform any git operation in a few seconds. Within a few keystrokes, it is possible to get the status, log, remotes, branches and doing the difference between to different versions. It gives access to complete much more sophisticated manipulations in less time that it takes to tell about. Try to achieve the same using the command line (you will, but it will take ages). The key here is the time it takes: if you need longer to git than what it takes to think about, you’re using git the wrong way. You’ve been advised. br/]]> img
Once upon a time, in digital electronics design, we were used to moving huge zip files around including project data, code and all ancillary stuff along with it. We were doing backups, snapshots and versioning our code with help of compressed files. That’s the way it was, I knew that time, and you, young reader, would not believe me if I told you about the whole picture. This is not acceptable anymore.
Today we have (well, we already did 20 years ago, but, you know, we were electronic engineers, not coding experts after all) tools to handle the situation. We have control version, we have git, and this more than we need to follow changes in our code (and our documentation, bibliography, etc.). Sure, we need a bit of discipline to use it in meaningful way, writing clear commit messages, committing correctly, creating clean histories, using the right branching model and learning how to use #git in a collaborative way. Following best practices is something that, as for today, should be accessible to any engineer, provided he is using the right tools.
The point here is how to interface git. In my experience, most hardware engineers (but not only) just do basic clone, push and pull, creating linear histories. Simply put, they use git as a backup system, with huge unrelated commits. They use git because they must use git, as anyone else is doing, but without any of the associated benefits. No history read, no diffs, no topic branches, no rebasing, no merging, no nothing. The reason is they’re using the command line interface (#cli) to git. Using git in the command line is fine, provided you’re fluent with clis, with a good shell and its plugins, and you have a very good long term memory. No one remembers how to interactively rebase 10 last commits on top of another branch, squashing history. Full stop. And no one will commit every 30 seconds if it takes one minute. Forget about. This brings to the clone/pull/push/that’s it step slope most people is faced to when they use git. And, unfortunately, this is the end of using git proper.
Now, what to do about ? #modernhw requires using a GUI to manipulate your git repositories. This will provide you with a lot of benefits, among them, a clear overview of where you are in your git history, your current status, and most importantly, where you’re going from this point. Which GUI to use ? Don’t expect an answer from me. The one you feel more comfortable with is the right choice. No matter what, provided it is #freesoftware. Spend as many time as you need mastering its usage, you’ll be rewarded afterward.
Personally, as I’m using #emacs, my not that original choice goes to using #magit. Magit is a front end application to the command line git, closely embedded within the rest of my workflow. As usual, once one gets used to its way of doing things, it’s really fast to perform any git operation in a few seconds. Within a few keystrokes, it is possible to get the status, log, remotes, branches and doing the difference between to different versions. It gives access to complete much more sophisticated manipulations in less time that it takes to tell about. Try to achieve the same using the command line (you will, but it will take ages). The key here is the time it takes: if you need longer to git than what it takes to think about, you’re using git the wrong way. You’ve been advised.

]]> https://infosec.press/csantosb/git-ytbn Tue, 31 Jan 2023 23:00:00 +0000