I like to post new articles and solutions when I think they are ready. Production tested and stable. Well thought and tested … or at least trying to make things as good as possible in the available time window. Perfectionism definitely does not help making often articles on the blog.
Today’s solution is not perfect but I will ‘ship it’ anyway because good and done is better then perfect. I wanted to rework it so many times that I stopped counting … and I really would like to continue the series – thus I have made a conscious decision to finally release it and hope that maybe someone else will have better ideas to make it better. I really wanted to provide pixel perfect solution with as much screen space used as possible but to deliver it as it is I tested it only on the resolution I use the most – the FullHD one with 1920×1080 pixels.
You may want to check other articles in the FreeBSD Desktop series on the FreeBSD Desktop – Global Page where you will find links to all episodes of the series along with table of contents for each episode’s contents.
Aero Snap
Today I would like to share with You what I call Aero Snap Extended. The original Aero Snap was introduced in Windows 7 and this is how it is described in the Wikipedia page – “Dragging a window to the right or left side of the desktop causes the window to fill the respective half of the screen. Snapping a window to the top of the screen maximizes it. Windows can be resized by stretching them to touch the top or bottom of the screen, which fully increases their vertical screen estate, while retaining their width, these windows can then slide horizontally if moved by the title bar, or pulled off, which returns the window to its original height. In spite of the “Aero” moniker, this feature is available if one uses the Classic theme. This feature is also available on Windows 10.”
This is like the original Aero Snap looks like.
The idea behind original Aero Snap was pretty simple. Its basically these four shortcuts.
[WIN] + [LEFT] – will place window on the left half of the screen.
[WIN] + [RIGHT] – will place window on the right half of the screen.
[WIN] + [UP] – will maximize the window.
[WIN] + [DOWN] – will minimize the window.
Aero Snap Extended
Mine Aero Snap Extended is … well more extended
As usual its just a small POSIX /bin/sh compatible shell script. There are only two dependencies for it – the /usr/local/bin/xdpyinfo from xdpyinfo package and /usr/local/bin/wmctrl from wmctrl package. At the beginning of the script you will find several ‘settings’ that you may find needed to be tuned to your needs. Most important ones are MARGIN_TOP/MARGIN_LEFT/MARGIN_RIGHT options. Unfortunately MARGIN_BOTTOM is not implemented. Sorry.
Here are the shortcuts that I use for mine version but You may of course use other key then [WIN] for it.
(L) [WIN] + [LEFT] – will place window on the left half of the screen.
(R) [WIN] + [RIGHT] – will place window on the right half of the screen.
(U) [WIN] + [UP] – will place window on the upper half of the screen.
(D) [WIN] + [DOWN] – will place window on the lower half of the screen.
Here is ASCII diagram for its graphical visualization.
+------+------+ +-------------+ | | | | (U) | | | | | | | (L) | (R) | +-------------+ | | | | | | | | | (D) | +------+------+ +-------------+
… and also a live screenshots.
(SL) [WIN] + [SHIFT] + [LEFT] – will place window on the left half of the screen taking 2/3 space of the screen.
(SR) [WIN] + [SHIFT] + [RIGHT] – will place window on the right half of the screen taking 1/3 space of the screen.
(SU) [WIN] + [SHIFT] + [UP] – will place window on the upper half of the screen taking 2/3 space of the screen.
(SD) [WIN] + [SHIFT] + [DOWN] – will place window on the lower half of the screen taking 1/3 space of the screen.
Here is ASCII diagram for its graphical visualization.
+--------+----+ +-------------+ | | | | (SU) | | | | | | | (SL) |(SR)| | | | | | +-------------+ | | | | (SD) | +--------+----+ +-------------+
… and also a live screenshots.
The above shortcuts are quite simple and easy to remember.
Now here comes when this is more interesting.
Most keyboards – at least those with the best possible keyboard layout in the world – the ANSI standard keyboard (includes 7-row ThinkPad keyboards – have these three keys one next to another – [CTRL] [WIN] [ALT] – some call the [WIN] key as [SUPER] instead. I use [WIN] as it takes shorter to write and it shows where this key came from.
The 87 keys ANSI stand alone keyboard.
The ThinkPad T420s keyboard.
Now back to topic.
How to use these three keys to send windows to various places of the screen to make it easy to memorize and also not to break existing shortcuts … I think I found a way.
{ [CTRL] [WIN] } [ALT] – these two will send windows to the left side of the screen.
[CTRL] { [WIN] [ALT] } – these two will send windows to the right side of the screen.
Now to the point …
(Q1) [CTRL] + [WIN] + [UP] – will take window to the left and upper part of the screen – taking 1/4 of its space.
(Q2) [CTRL] + [WIN] + [DOWN] – will take window to the left and lower part of the screen – taking 1/4 of its space.
(Q3) [WIN] + [ALT] + [UP] – will take window to the right and upper part of the screen – taking 1/4 of its space.
(Q4) [WIN] + [ALT] + [DOWN] – will take window to the right and lower part of the screen – taking 1/4 of its space.
Now for some the exact 1/4 screen for each of these windows may be not suitable.
Thus I also added a modified versions with [SHIFT] key.
(S1) [SHIFT] + [CTRL] + [WIN] + [UP] – will take window to the left and upper part of the screen – taking 2/3 of horizontal and 2/3 vertical space of the screen.
(S2) [SHIFT] + [CTRL] + [WIN] + [DOWN] – will take window to the left and lower part of the screen – taking 2/3 of horizontal and 1/3 vertical space of the screen.
(S3) [SHIFT] + [WIN] + [ALT] + [UP] – will take window to the right and upper part of the screen – taking 1/3 of horizontal and 2/3 vertical space of the screen.
(S4) [SHIFT] + [WIN] + [ALT] + [DOWN] – will take window to the right and lower part of the screen – taking 1/3 of horizontal and 1/3 vertical space of the screen.
Here is ASCII diagram for its graphical visualization.
+------+------+ +--------+----+ | (Q1) | (Q3) | | (S1) |(S3)| | | | | | | +------+------+ | | | | | | +--------+----+ | (Q2) | (Q4) | | (S2) |(S4)| +------+------+ +--------+----+
… and also a live screenshots.
Now you have about 95% variations of needed windows places in the keyboard shortcuts.
There are also several complementary addons like making the window centered on the screen but without making it cover the whole screen. As I already use other originated from Windows [ALT] + [ESC] shortcut to send the current windows to the ‘back’ I also added [WIN] + [ESC] for this feature.
(C) [WIN] + [ESC] – place current window centered on screen covering about 2/3 of its space.
As it was relatively easy and fast I also added fullscreen option.
(F) [CTRL] + [ALT] + [F] – make current window go fullscreen
+-------------+ +-------------+ | | | +---------+ | | | | | | | | (F) | | | (C) | | | | | | | | | | | +---------+ | +-------------+ +-------------+
… and also a live screenshot.
Usage
The Aero Snap Extended has the following options.
% aero-snap.sh usage: aero-snap.sh OPTION OPTION(s): L - place window on left half of screen R - place window on right half of screen T - place window on upper half of screen B - place window on lower half of screen SHIFT-L - place window on left half of screen taking 2/3 space SHIFT-R - place window on right half of screen taking 1/3 space SHIFT-T - place window on upper half of screen taking 2/3 space SHIFT-B - place window on lower half of screen taking 1/3 space TL - place window to left/upper part of screen TR - place window to left/lower part of screen BL - place window to right/upper part of screen BR - place window to right/lower part of screen SHIFT-TL - use left/upper part with 2/3 of H. and 2/3 V. space SHIFT-TR - use left/lower part with 2/3 of H. and 1/3 V. space SHIFT-BL - use right/upper part with 1/3 of H. and 2/3 V. space SHIFT-BR - use right/lower part with 1/3 of H. and 1/3 V. space C - center window covering about 2/3 of screen F - make current window go fullscreen Q - remove fullscreen property from window
The Aero Snap Extended can be downloaded from here – aero-snap.sh – the usual place for my scripts.
Openbox Integration
Because of WordPress limitation I will not post Openbox configuration here but You will also find a link to that content in the text form below.
Here is this configuration in text form – rc.xml.openbox.aero.config – from the same location.
More then a year after I implemented this way of tiling on Openbox I found out that its also possible to use that ‘natively’ on Openbox using ‘direct’ Openbox configuration rules.
It definitely should be faster and easier to implement – not to mention that external dependencies will not be available – but a script allows more tuning and flexibility.
Other Window Managers
If you are not into Openbox then you may create these shortcuts using xbindkeys for example.
Future Work
Mine Aero Snap Extended could use some polish and especially testing in the other resolutions the the well tested 1920×1080.
Regards.
FreeBSD git Primer for Users
Today's blog is actually a preview of a git primer I'm writing for the FreeBSD project. It covers what a typical user will need, including those relatively rare users that may have some changes to the base. Please let me know what you think, and ways it can be improved. I'm keen on especially clear and useful pointers for the topics as well.
Also note: The cgit-beta mirror mentioned below is currently for testing purposes only.
If you have a lot of suggests, you can make them directly on the original for this on hackmd.
Scope
If you want to download FreeBSD, compile it from sources and generally keep up to date that way, this primer is for you. If you are looking to do more with the tree, contribute back, or commit changes, then you will need to wait for a later blog where I cover that. It covers getting the sources, updating the sources, how to bisect and touches briefly on how to cope with a few local changes. It covers the basics, and tries to give good pointers to more in-depth treatment for when the readers finds the basics insufficient.
Keeping Current With FreeBSD src tree
First step: cloning a tree. This downloads the entire tree. There’s two ways to download. Most people will want to do a deep clone of the repo. However, there are times that you may wish to do a shallow clone.
Branch names
The branch names in the new git repo are similar to the old names. For the stable branches, they are stable/X where X is the major release (like 11 or 12). The main branch in the new repo is ‘main’. The main branch in the old github mirror is ‘master’. Both reflecting the defaults of git at the time they were created. The main/master branch is the default branch if you omit the ‘-b branch’ or ‘–branch branch’ options below.
Repositories
At the moment, there’s two repositories. The hashes are different between them. The old github repo is similar to the new cgit repo. However, there are a large number of mistakes in the github repo that required us to regenerate the export when we migrated to having a git repo be the source of truth for the project.
The github repo is at https://github.com/freebsd/freebsd.git
The new cgit beta repo is at https://cgit-beta.freebsd.org/src.git
These will be $URL in the commands below.
Note: The project doesn’t use submodules as they are a poor fit for our workflows and development model. How we track changes in third-party applications is discussed elsewhere and generally of little concern to the casual user.
Deep Clone
A deep clone pulls in the entire tree, as well as all the history and branches. It’s the easiest to do. It also allows you to use git’s worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository.
is how you make a deep clone. ‘branch’ should be one of the branches listed in the previous section. It is optional if it is the main/master branch. dir is an optional directory to place it in (the default will be the name of the repo you are clone (freebsd or src)).
You’ll want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch. It’s the easiest to keep up to date as well. If you are interested in the history, but are working with only one branch and are short on space, you can also use --single-branch to only download the one branch (though some merge commits will not reference the merged-from branch which may be important for some users who are interested in detailed versions of history).
Shallow Clone
A shallow clone copies just the most current code, but none or little of the history. This can be useful when you need to build a specific revision of FreeBSD, or when you are just starting out and plan to track the tree more fully. You can also use it to limit history to only so many revisions.
This clones the repository, but only has the most recent version in the respository. The rest of the history is not downloaded. Should you change your mind later, you can do ‘git fetch --unshallow’ to get the old history.
Building
Once you’ve downloaded, building is done as described in the handbook, eg:
so that won’t be coverd in depth here.
Updating
To update both types of trees uses the same commands. This pulls in all the revisions since your last update.
will update the tree. In git, a ‘fast forward’ merge is one that only needs to set a new branch pointer and doesn’t need to re-create the commits. By always doing a ‘fast forward’ merge/pull, you’ll ensure that you have an identical copy of the FreeBSD tree. This will be important if you want to maintain local patches.
See below for how to manage local changes. The simplest is to use --autostash on the ‘git pull’ command, but more sophisticated options are available.
Selecting a Specific Version
In git, the ‘git checkout’ command can not only checkout branches, but it can also checkout a specific version. Git’s versions are the long hashes rather than a sequential number. You saw them above in the conflict when it said it couldn’t apply “646e0f9cda11”.
When you checkout a specific version, just specify the hash you want on the command line (the git log command can help you decide which hash you might want):
and you have that checked out.
However, as with many things git, it’s not so simple. You’ll be greeted with a message similar to the following:
where the last line is generated from the hash you are checking out and the first line of the commit message from that revision. Also, a word about hashes: they can be abbreviated. That’s why you’ll see them have different lengths in different commands or their outputs. These super long hashes are often unique after 6 or 10 characters, so git lets you abbreviate and is somewhat inconsistent about how it presents them to users.
Bisecting
Sometimes, things go wrong. The last version worked, but the one you just updated to does not. A developer may ask to bisect the problem to track down which commit caused the regression.
If you’ve read the last section, you may be thinking to yourself “How the heck do I bisect with crazy version numbers like that?” then this section is for you. It’s also for you if you didn’t think that, but also want to bisect.
Fortunately, one uses the ‘git bisect’ command. Here’s a brief outline in how to use it. For more information, I’d suggest https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination or https://git-scm.com/docs/git-bisect for more details. The man page is good at describing what can go wrong, what to do when versions won’t build, when you want to use terms other than ‘good’ and ‘bad’, etc, none of which will be covered here.
‘git bisect start’ will start the bisection process. Next, you need to tell a range to go through. ‘git bisect good XXXXXX’ will tell it the working version and ‘git bisect bad XXXXX’ will tell it the bad version. The bad version will almost always be HEAD (a special tag for what you have checked out). The good version will be the last one you checked out.
A quick aside: if you want to know the last version you checked out, you should use ‘git reflog’:
shows me moving the working tree to the master branch (a816…) and then updating from upstream (to 5ef0…). In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165. As you can see from the output, HEAD@{1} also often works, but isn’t foolproof if you’ve done other things to your git tree after updating, but before you discover the need to bisect.
Back to git bisect. Set the ‘good’ version first, then set the bad (though the order doesn’t matter). When you set the bad version, it will give you some statistics on the process:
You’d then build/install that version. If it’s good you’d type ‘git bisect good’ otherwise ‘git bisect bad’. You’ll get a similar message to the above each step. When you are done, report the bad version to the developer (or fix the bug yourself and send a patch). ‘git bisect reset’ will end the process and return you back to where you started (usually tip of main). Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases.
Ports Considerations
The ports tree operates the same way. The branch names are different and the repos are in different locations.
The github mirror is at https://github.com/freebsd/freebsd-ports.git
The cgit mirror is https://cgit-beta.freebsd.org/src.git
As with ports, the ‘current’ branches are ‘master’ and ‘main’ respectively. The quarterly branches are named the same as in FreeBSD’s svn repo.
Coping with Local Changes
Here’s a small collections of topics that are more advanced for the user tracking FreeBSD. If you have no local changes, you can stop reading now (it’s the last section and OK to skip).
One item that’s important for all of them: all changes are local until pushed. Unlike svn, git uses a distributed model. For users, for most things, there’s very little difference. However, if you have local changes, you can use the same tool to manage them as you use to pull in changes from FreeBSD. All changes that you’ve not pushed are local and can easily be modified (git rebase, discussed below does this).
Keeping local changes
The simplest way to keep local changes (especially trivial ones) is to use ‘git stash’. In its simples form, you use ‘git stash’ to record the changes (which pushes them onto the stash stack). Most people use this to save changes before updating the tree as described above. They then use ‘git stash apply’ to re-apply them to the tree. The stash is a stack of changes that can be examined with ‘git stash list’. The git-stash man page (https://git-scm.com/docs/git-stash) has all the details.
This method is suitable when you have tiny tweaks to the tree. When you have anything non trivial, you’ll likely be better off keeping a local branch and rebasing. It is also integreated with the ‘git pull’ command: just add ‘–autostash’ to the command line.
Keeping a local branch
It’s much easier to keep a local branch with git than subversion. In subversion you need to merge the commit, and resolve the conflicts. This is managable, but can lead to a convoluted history that’s hard to upstream should that ever be necessary, or hard to replicate if you need to do so. Git also allows one to merge, along with the same problems. That’s one way to mange the branch, but it’s the least flexible.
Git has a concept of ‘rebasing’ which you can use to avoids these issues. The ‘git rebase’ command will basically replay all the commits relative to the parent branch at a newer location on that parent branch. This section will briefly cover how to do this, but will not cover all scenarios.
Create a branch
Let’s say you want to make a hack to FreeBSD’s ls command to never, ever do color. There’s many reasons to do this, but this example will use that as a baseline. The FreeBSD ls command changes from time to time, and you’ll need to cope with those changes. Fortunately, with git rebase it usually is automatic.
The commit will pop you into an editor to describe what you’ve done. Once you enter that, you have your own local branch in the git repo. Build and install it like you normally would, following the directions in the handbook. git differs from other version control systems in that you have to tell it explicitly which files to use. I’ve opted to do it on the commit command line, but you can also do it with ‘git add’ which many of the more in depth tutorials cover.
Time to update
When it’s time to bring in a new version, it’s almost the same as w/o the branches. You would update like you would above, but there’s one extra command before you update, and one after. The following assumes you are starting with an unmodified tree. It’s important to start rebasing operations with a clean tree (git usually requires this).
This will bring up an editor that lists all the commits in it. For this example, don’t change it at all. This is typically what you are doing while updating the baseline (though you also use the git rebase command to curate the commits you have in the branch).
Once you’re done with the above, you’ve move the commits to ls.c forward from the old version of FreeBSD to the newer one.
Sometimes there’s merge conflicts. That’s OK. Don’t panic. You’d handle them the same as you would any other merge conflicts. To keep it simple, I’ll just describe a common issue you might see. A pointer to a more complete treatment can be found at the end of this section.
Let’s say the includes changes upstream in a radical shift to terminfo as well as a name change for the option. When you updated, you might see something like this:
which looks scary. If you bring up an editor, you’ll see it’s a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted):
The new code is first, and your code is second. The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes:
save the file. The rebase was interrupted, so you have to complete it:
which tells git that ls.c has changed and to continue the rebase operation. Since there was a conflict, you’ll get kicked into the editor to maybe update the commit message.
If you get stuck during the rebase, don’t panic. git rebase --abort will take you back to a clean slate. It’s important, though, to start with an unmodified tree.
For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ provides a rather extensive treatment. It goes into a lot of cases I didn’t cover here for simplicity that are useful to know since they come up from time to time.
Updating to a New FreeBSD Branch
Let’s say you want to main the jump from FreeBSD stable/12 to FreeBSD current. That’s easy to do as well, if you have a deep clone.
and you are done. If you have a local branch, though, there’s one or two caveats. First, rebase will rewrite history, so you’ll likely want to do something to save it. Second, jumping branches tends to encounter more conflicts. If we pretend the example above was relative to stable/12, then to move to main, I’d suggest the following:
What the above does is checkout no-color-ls. Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it. Then you rebase onto the main branch. This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will replay them onto the main branch creating a new no-color-ls branch there (which is why I had you create a place holder name).