Cerise Norling

Recovering From a Botched Git Rebase

Mon, 27 Mar 2023 10:00:00 -0600

When rebasing, it’s inevitable that you will delete something you didn’t intend to, or finish a rebase before you’re actually done. When this happens, the best thing you can do is take a step back and truly evaluate the current state of the remote repository and your local repository.

Is the content actually deleted?
Have I pushed my changes out yet?
Could someone else have a copy of the content I deleted?

Even if you’ve already force pushed out your changes, there are ways to recover deleted content.

Check if there’s anything in git reflog

Git Reflog is a referential log of all the states your local git repository has been in. Every removed branch, deleted commit, unsigned commit, previously squashed commits, even viewing a specific commit SHA is logged and recorded. Reflog is a local only thing, so if you delete a local git repository and clone it down again you’ll lose all your reflogs.

You can access your referential logs by running git reflog. By default, it retains the last 90 days of git activity. Every time you run a git specific action, git runs a garbage collector that discards anything outside the defined retention period. If you wanted to, you could increase this threshold by running git config gc.reflogExpire 120. Don’t forget to pass --global if you want it to apply to all repositories.

Accessing reflogs

All reflogs are dynamic and measured according to an offset from your latest action. To access reflogs, first you need to identify which reflog to examine. Run git reflog to identify the state you want to examine. Then run git checkout HEAD{23} where 23 is the number offset from git reflog.

In this state, you can poke around and look at the file content to confirm that it is what it should be.

Accessing git logs within reflogs

Reflogs are really just a reference to a specific commit SHA. The content of that SHA also happens to include the historical revisions at that point in time. That includes the historical output from git log. If you need to identify a commit SHA that’s no longer in git log, you can checkout an earlier reflog and run git log to browse commits that were associated with your branch at that point in time. It’s very useful for identifying deleted content.

What if I don’t have reflogs?

Even if your reflogs are empty, if you know the commit SHA or have tagged a specific commit you can perform a git reset --hard $SHA to reset to that point in time. The trick there is to know the SHA since if there’s no reflog, you’re going to have a hard time finding the SHA if it’s just local.

Examples

Completely undoing a git rebase

Undoing a rebase completely actually isn’t that bad. The process is simply to identify the commit SHA or reflog before the rebase started, then perform a git reset --hard $REF like so

Cherrypicking deleted commits

If you need to be more selective about what you do and don’t recover, cherrypicking commit SHAs might be a good option for you.

The hard part is knowing and discovering the commit SHA you intend to recover. Even after you delete commits, they still exist both locally and (maybe) remotely. If you’re trying to recover a deleted commit and you know the commit SHA, you can run git cherry-pick $SHA to get that commit back. After the cherrypick, the commit SHA might change since it’s now incorporating the changes between how far back from head it was and where it is now.

(unless the deleted commit was the latest one, then it will be the same)

Summary

Unless you’ve configured your git garbage collector to discard reflogs, you definitely have everything you need to fix a messed up git rebase. I hope you learned something from this article!

If you enjoyed this article, have any questions, noticed something inaccurate, or you just want to say hi feel free to drop a comment below or send an email to me@norling.io

Writing my Resume in LaTeX

Sat, 18 Mar 2023 10:00:00 -0600

Writing LaTeX sucks, but the results are undeniably better than anything else. This article is a brief introduction into LaTeX, the basic prerequisites to writing documents, what the ecosystem is like, and what it was like writing my resume in LaTeX.

Dark Times Before LaTeX

I am very picky about resume formatting. If things aren’t perfectly aligned, it bothers me on a spiritual level. Before LaTeX, my solution for writing my resume was to make a table in Google Docs, organize the content into columns, and set the table line width to 0 so it would be transparent. This setup worked for quite some time, but it had drawbacks.

Changing the column width for one cell had implications for other cells
The witdth of each cell was independent from other similar cells. This led to inconsistent spacing on the headers and sections
Content would shift between when the table was set to 1 or 0 line width
A lot of cells had to be merged together
Content had to be manually shuffled around for appropriate page balancing

I felt really good about the results, but over time as I would make modifications the pain points started to wear on me. I asked my friend Dakota Clark about his resume, and he said he wrote his in LaTeX. I didn’t know much about LaTeX at the time. I knew it was frequently used for academic papers and was developed as an easier way to express mathematical equations.

My interest was piqued, and I decided to give it a shot. He gave me a copy of his resume, and I scanned over it to try and learn LaTeX. I also looked on Overleaf for public LaTeX resumes, but I didn’t see anything that really looked like what I wanted. I ended up writing my own from scratch!

LaTeX Concepts

Environments

When you declare things like font, size, color, and other text modifiers, you’re applying it to an environment. Think of an environment as something like a title, paragraph, footer, or table; A subsection of things that needs to be handled in a certain way. You can create your own environments, or you can use pre-made ones included in libraries. You can use a pre-made an environment like so

1
2
3


\begin{environmentName}
 I'm in the environment!
\end{environmentName}

Any text alterations you make inside that codeblock will only apply to that subset of text. You can declare your own custom environment like so

1
2
3
4
5
6
7
8


\newenvironment{foo}{
 % executes as the top portion of the environment
 \color{Green}
 \begin{list}{x}{\raggedright}
}{
 % executes as the bottom portion of the environment
 \end{list}
}

You can also have environments within environments

1
2
3
4
5
6


\begin{environmentName}
 I'm in the environment!
 \begin{foo}
 I'm in the custom environment!
 \end{foo}
\end{environmentName}

Packages

TeXLive has a large number of default document classes and packages that are immediately available at your disposal, and you’ll have to use a lot of them. Set a page’s margins? Use geometry. Merge cells in a table? Use multirow or multicol. Color something? Use xcolor. Want to add a hyperlink? Use hyperref.

Package discovery largely entails scrawling through StackOverflow or Overleaf for threads where people talk about how to do things. Overall, the ecosystem is well documented with most LaTeX libraries choosing to document their programs in PDFs on CTAN. You can find an example of the geometry package here.

You can import a package like so

1

\usepackage{fontawesome}

Text Sizing

Because of how LaTeX handles text, you are limited to a small range of predetermined sizes that should meet most people’s needs. If you want to go larger or smaller, you’ll need to find a package with different supported sizes. Overleaf has some excellent docuemntation on font sizing you can read here.

Fonts

Using a specific font isn’t as easy as you might think it would be. To use a font, you first have to identify what the font’s name as it’s defined in LaTeX. Once you have that name, you can apply it to an environment like so

1
2
3


\begin{foo}
 \fontfamily{<familyname>}\selectfont
\end{foo}

Packages like fontenc make using fonts much easier. To look at fonts online, I’d recommend reading over the tug.org font catalogue https://tug.org/FontCatalogue

Tolerance

Whenever a line of text is justified, LaTeX must make a determination on how much whitespace spread between words can be tolerated without looking weird. It also decides just how much you can go past a margin before it puts the next word on a newline. Tolerance is an integer set between 0 and 10000. It’s easiest to understand in a picture

Document Classes

There are many different types of documents, and all those documents have things in common regardless of who wrote the document. Classes are a collection of common parameters and characteristics in a document that should apply to all documents of that type. TeXLive includes a few document classes that you can use like report, book, article, or letter. Article is a good class to use if you want a blank template to work with.

Functions and Variables

You declare a variable the same way you declare a function; Just create a function that returns the value you want assigned to the variable. You can then use that function wherever you want to.

Drawing Things

There are a million ways to do what you probably want, and 50% of those ways will probably involve using TikZ. TikZ allows you to draw pictures in LaTeX. The way you draw pictures might be appealing to mathemeticians, but it’s not a very enjoyable experience otherwise. There are a lot of packages that utilize TikZ to draw things for you in a more easy to write format.

I use a package called mdframed that uses TikZ to outline text boxes around words and color them.

Writing the Resume

It can be very helpful to observe a project from creation to completion, so I’ve added a step by step example on github you can inspect to compare. A picture of the PDF output is included in the README.md of the repository so this blogpost doesn’t get too long. You can find it here

File Setup

I start by defining a document and a document class. resume.cls is the class and resume.tex is the document. I put shared functions and formatting related things in resume.cls. The content of the resume itself goes in resume.tex. I add some content to resume.cls to declare its parent document class, and link resume.tex to that class. I also add a special environment named document to resume.tex and put my name in it.

Content

When working with a document that requires a lot of formatting, it can be helpful to have all your content already on the page so you can observe how the text will behave as you make changes. For this example, there’s a mix of real text and fake text. I’ll use the lipsum package and add it to resume.cls. After it’s imported, I can use the \lipsum function to get some example content.

Some of the content needs to be handled differently from the others though. I’ll declare a list environment for the qualifications and skills, then add some placeholder items to it.

Heading

The first formatting thing I want to tackle is the page margins. I like my resume to have short vertical margins and wider horizontal margins. I can use the geometry package to setup page margins like so

1
2
3
4
5
6
7
8


\usepackage{geometry}
\geometry{
 a4paper,
 left=20mm,
 right=20mm,
 top=8mm,
 bottom=8mm,
}

The second formatting thing I want to tackle is the heading. Before I can do that, I need to add some variables so that I can use their content in resume.cls. After adding them with \newcommand{\functionName}{string} I can then call \functionName to access their output.

My heading isn’t something that’s really going to change, so the strategy I use for my heading is a function that takes no parameters that pulls from the variables we just declared. I define a heading command and add the content we have in our header like so

1
2
3
4
5
6
7
8


\newcommand{\heading}{
 \name
 \github
 \website
 \email
 \phone
 \address
}

I want things roughly aligned with where they need to go, and I can do that with an environment called a tabular. Table declarations in LaTeX are very finnicky. They look best as code when their content is kept simple and straightforward. We pass a few parameters to indicate how many cells we want, how wide those cells should be, and how they should align. We’ll also want to use the package tabularx since it fixes some issues that native LaTeX tabulars have. Here’s an example

1
2
3
4
5
6


\begin{tabular}{p{200pt} p{120pt} p{120pt}}
 % define the table content and separate cells with &
 % newlines in tables are declared with \\ at the end
 \name & \github & \website \\
 & \email & \phone
\end{tabular}

The document is already looking much better! The next thing I want to do is increase the size of my name and capitalize it as well as the sections. For that, we can use \MakeUppercase{} and \huge. I also want the things on the right side of the heading to align to the right side of the page; We can do that by applying the >{\raggedright\arraybackslash} directive to the column in question.

1
2
3
4
5
6


\newcommand{\heading}{
 \begin{tabular}{p{200pt} p{120pt} >{\RaggedLeft}p{120pt}}
 \MakeUppercase{\huge\name} & \github & \website \\
 & \email & \phone
 \end{tabular}
}

My name looks bigger, but now the table’s content isn’t aligned. To fix this, I merge the empty cell below my name with the multirow package. It’s at this point that I give up keeping rough cell alignment since the cast name is so long.

1
2
3
4
5
6


\newcommand{\heading}{
 \begin{tabular}{p{200pt} p{120pt} >{\RaggedLeft}p{120pt}}
 \multirow{2}{200pt}{\MakeUppercase{\huge\name}} & \github & \website \\
 & \email & \phone
 \end{tabular}
}

Okay my name is vertically aligned now, but that line to print my name is absurdly long and makes the table illegible from a code standpoint. I’m going to obfuscate how my name’s casted with another command.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


\newcommand{\heading}{
 \begin{tabular}{p{200pt} p{120pt} >{\RaggedLeft}p{120pt}}
 \multirow{2}{200pt}{\printName} & \github & \website \\
 & \email & \phone
 \end{tabular}
}

\newcommand{\printName}{
 \MakeUppercase{\huge\name}
}

Definitely better than before, but there’s room for improvement.

Formatting

Paragraph Indentation

To fix the paragraph indentation on this resume, I use the parskip package. I don’t have the capability to fix the heading indentation at this time, but it won’t be a problem with the styling we’ll do later.

Hyphenated Linebreaks

Some of the words are spread across multiple lines, so I’ll want to configure the page’s tolerance and disable hyphenation with the hyphenat package.

Bullet Points

I’d prefer to use a nicer icon than just an asterisk. The favicon LaTeX library has a lot of good icons to use. I like \faCheckSquare. I want the bullet points to be in-line with the left side of the page, so I’ll have to edit the list’s parameters. I also want to change the separation between items to be tighter like so

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


 \begin{list}{\faCheckSquare}{
 \setlength{\leftmargin}{15pt}
 \setlength{\itemsep}{0pt}
 \itemsep -0.5em \vspace{-0.5em}
 \raggedright
 }
 \item foo
 \item bar
 \item baz
 \item biz
 \item boz
 \item buz
 \item bez
 \end{list}

Multiple Column List

I’d like the skills and tools to be spread out across the page. A package called multicol lets me spread a single list across multiple columns like so

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


 \begin{multicols}{4}
 \begin{list}{\faCheckSquare}{
 \setlength{\leftmargin}{15pt}
 \setlength{\itemsep}{0pt}
 \itemsep -0.5em \vspace{-0.5em}
 \raggedright
 }
 \item foo
 \item bar
 \item baz
 \item biz
 \item boz
 \item buz
 \item bez
 \item fiz
 \item faz
 \item fox
 \item foz
 \item fyz
 \end{list}
 \end{multicols}

Some of the formatting has leaked into the resume.tex file with how things are setup now. To fix this, I’ll create a custom environment that declares the list as well as a few other options. The skills environment will have one parameter that we declare with \newenvironment{envname}[3]{}{} where the integer is how many arguments we want the function to have. Values from those parameters are used by referencing their integer in the position prefixed by a pound like this: #1

When you use the environment, you add a set of curly brackets after the environment’s name with your input like this: \begin{envname}{foo}{bar}{baz}. Our use-case is much simpler though since we only have one parameter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


% resume.cls
\newenvironment{skills}[1]{
 \begin{multicols}{#1}
 \begin{list}{*}{
 \setlength{\leftmargin}{15pt}
 \setlength{\itemsep}{0pt}
 \itemsep -0.5em \vspace{-0.5em}
 \raggedright
 }
}{
 \end{list}
 \end{multicols}
}

% resume.tex
\begin{skills}{4}
 \item foo
 \item bar
 \item baz
 \item biz
 \item boz
 \item buz
 \item bez
 \item fiz
 \item faz
 \item fox
 \item foz
 \item fyz
\end{skills}

Vertical Padding

At this point, the spacing between the list we have for qualifications vs skills and tools is different, so I’ll have to tweak the qualifications environment a bit with some padding to even things out. I can do this with the \vspace*{8pt} command.

What’s that asterisk mean? Well, to be honest a lot of the default behaviors of LaTeX are inconsistent and sometimes undesirable. Rather than update the package, newer packages by maintainers are added to TeXlive to fix these issues. But now there are package naming conflicts. The solution is to change the case sensitivity of the package or suffix an asterisk at the end. \vspace and \vspace* are both different packages with different behaviors. If you see a package with an asterisk, you should use that over the default package because it’s more likely up-to-date.

Font

We’ll want to set the font too. I like comfortaa, so I’ll set it globally with the comfortaa package.

Text Color

Black on white is very harsh on the eyes, so changing the text color will help. I can do that by configuring a default color in the class like this \color{darkgray}.

I’d like to also organize the job content similar to how the header is handled. I’ll create a new environment that takes 3 parameters with a 2x2 table. To format the text, I’ll bold the job and date, italicize the title, and capitalize the date. With this table, I’ll need some more advanced formatting utilities so I’ll use a tabularx instead.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


% resume.cls
\newenvironment{job}[3]{
 \vspace{5pt}
 \begin{tabularx}{1\textwidth} {
 @{}>{\hsize=1\hsize\linewidth=\hsize\raggedright\arraybackslash}X@{}
 @{}>{\hsize=1\hsize\linewidth=\hsize\raggedleft\arraybackslash}X@{}
 }
 \textbf{\large #1} & \MakeUppercase{\textbf{#3}} \\
 \textit{#2}
 \end{tabularx}
}{}

% resume.tex
\begin{job}{job name}{job title}{12-2021 - present}
\end{job}

Styling

Now I want to add some style to the page to make it less plain.

Favicons and Hyperlinks

With the favicon package I imported earlier, I can add some cool icons to the header. I’ll need to expand the table width and add a few more helper functions and packages to setup hyperlinks and size the icons; The hyperref package lets me setup hyperlinks. I’ll also configure a color variable globally and use that later on.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


\newcommand{\heading}{
 \begin{tabular}{ p{200pt} >{\raggedleft\arraybackslash}p{30pt} p{90pt}>{\raggedleft\arraybackslash} p{90pt} >{\raggedright\arraybackslash} p{30pt} }
 \multirow{2}{200pt}{\printName} & \icogithub & \github & \website & \icowebsite \\
 & \icophone & \phone & \email & \icomail
 \end{tabular}
}

\newcommand{\printName}{\MakeUppercase{\huge \name}}
\newcommand{\ico}[2]{{\large\href{#1}{#2}}}
\newcommand{\icogithub}{\ico{https://github.com/\github}{\faGithub}}
\newcommand{\icomail}{\ico{mailto:\email}{\faEnvelope}}
\newcommand{\icophone}{\ico{tel:\phone}{\faPhone}}
\newcommand{\icowebsite}{\ico{https://\website}{\faGlobe}}
\newcommand{\setcolor}{\color{\colour}}

Text Boxes

I found a package called mdframed that lets me draw boxes around text. It works by allowing you to declare a type of environment that’s specific to the mdframed package. I declare a positive and negative variant for some variety on the page like so

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


\newmdenv[
 middlelinewidth=0pt,
 backgroundcolor=\colour,
 roundcorner=2pt,
 fontcolor=White,
 innerleftmargin=5pt,
 innertopmargin=-8pt,
 userdefinedwidth=150pt
]{infobox}

\newmdenv[
 userdefinedwidth=\textwidth,
 linecolor=\colour,
 linewidth=1pt,
 backgroundcolor=White,
 roundcorner=2pt,
 fontcolor=\colour,
 innerleftmargin=5pt,
 innerbottommargin=2pt
]{infoboxinvert}

I use the infobox like I would any ordinary environment. For the header, I’m going to override a few settings on the infobox. I’ll also tweak the name to be splayed across two lines by adjusting the multirow cell width like so

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


\newcommand{\heading}{
 \begin{infobox}[
 innertopmargin=4pt,
 innerbottommargin=25pt,
 innerleftmargin=0pt
 ]
 \begin{tabular}{ p{200pt} >{\raggedleft}p{30pt} p{90pt}>{\raggedleft} p{90pt} >{\raggedright\arraybackslash} p{30pt} }
 \multirow{2}{150pt}{\printName} & \icogithub & \github & \website & \icowebsite \\
 & \icophone & \phone & \email & \icomail
 \end{tabular}
 \end{infobox}
}

Now I’ll wrap the job environment in the inverted infobox.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


\newenvironment{job}[3]{
 \vspace{5pt}
 \begin{infoboxinvert}[]
 \begin{tabularx}{1\textwidth} {
 @{}>{\hsize=1\hsize\linewidth=\hsize\raggedright\arraybackslash}X@{}
 @{}>{\hsize=1\hsize\linewidth=\hsize\raggedleft\arraybackslash}X@{}
 }
 \textbf{\large #1} & \MakeUppercase{\textbf{#3}} \\
 \textit{#2}
 \end{tabularx}
 \end{infoboxinvert}
}{}

For the sections, I’ll declare a function that uses the infobox environment and accepts a parameter for the section name. I’ll configure the width of the boxes to be static so they all align down the page.

1
2
3
4
5


\newcommand{\sector}[1]{
 \begin{infobox}[userdefinedwidth=143pt]
 \section*{\MakeUppercase{#1}}
 \end{infobox}
}

I’ll set the color of the checkboxes as well with the \setcolor command I defined earlier.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


\newenvironment{skills}[1]{
 \vspace*{-5pt}
 \begin{multicols}{#1}
 \begin{list}{\setcolor\faCheckSquare}{
 \setlength{\leftmargin}{15pt}
 \setlength{\itemsep}{0pt}
 \itemsep -0.5em \vspace{-0.5em}
 \raggedright
 }
}{
 \end{list}
 \end{multicols}
 \vspace*{-5pt}
}

I’ll also update some of the placeholder content to be more like an actual resume.

Ending Notes

LaTeX is a very old language with a lot of inconsistencies, weird syntax, and small issues that can make it a frustrating language to work with. That being said, I love the results and will definitely use it going forward. If you’d like to see this resume on github, check it out here! You’re more than welcome to fork it for personal use and tweak it however you like =]

If you enjoyed this article, have any questions, noticed something inaccurate, or you just want to say hi feel free to drop a comment below or send an email to me@norling.io

Easily Resolving Git Merge Conflicts

Mon, 13 Mar 2023 10:00:00 -0600

When it rains it pours

It seems like whenever there’s a merge conflict, it’s rarely just one file in a single commit. It’s always multiple files in multiple commits, and that’s where the endless stream of pain comes when you do things like cherry pick multiple commits or run git pull origin main.

Merge conflicts in git are a necessary evil because of the nature of git. Git has zero insight into which changes precede over eachother, and it relies on the user to make those informed decisions.

Making things easier with merge strategy options

Any command that involves a merge conflict is also going to include the optional parameter for specifying a merge strategy. -X ours and -X theirs are two neat ways to say

If there are conflicts, prefer these changes over those

In Practice

If you want to try it for yourself, run this shell script!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


git branch a
git branch b

git checkout a
echo "a" > foo
git add foo
git commit -m "added a to foo"

git checkout b
echo "b" > foo
git add foo
git commit -m "added b to foo"

git merge a -X theirs

After running this script, foo in branch b will be overwritten with the changes from branch a. You can safely delete both branches a and b without reprecussions (unless for some reason you have a branch that already exists named a or b).

If you enjoyed this article, have any questions, noticed something inaccurate, or you just want to say hi feel free to drop a comment below or send an email to me@norling.io

Rewriting History With Git Rebases

Mon, 06 Mar 2023 10:00:00 -0600

Have you or a loved one ever wanted to:

delete a commit
edit the content of a commit
remove a specific file that was accidentally added to a commit
include missed files in a commit
fix a typo in an old commit message
combine a bunch of commits together

If you’ve worked with git, you’ve likely needed to do at least one of these at some point. And if you’re like me, you’ve probably read over the --help documentation of git to figure out how to do some of these things, and oh boy the docs can be cagey about telling you what exactly to do. This article is a reference on just a few things you can do with git rebases, and how to do it. Here’s the equivalent article directly from the git documentation if you’re interested in further reading.

Rewriting history is controversial

Rebasing involves rewriting history.
Rewriting history involves force pushing to overwrite the remote state of a repository.
Force pushing has the potential to delete others work (if you rebase recklessly).

Rewriting history is controversial. Some say it’s okay to modify history because it’s sometimes necessary and can enhance git history. Others say it’s not okay because git is supposed to be a historical representation of all changes, and you should prefer to roll your fixes forward. In my opinion if your historical modifications don’t impact others, it should be acceptable to rewrite history. It’s important when managing git history to ensure that you aren’t impacting other people’s work. You should follow these general practices:

Always use --force-with-lease when pushing out rebases.
Avoid rewriting history if you’re collaborating with others on the same branch.
If you have to rebase changes while working with others, git pull often to always make sure you’re working with the latest content.
Don’t edit other people’s commits unless they know about and consent to the edits.

So what is a git rebase?

A git rebase is the act of disassembling and reassembling a range of commits. The function’s name comes from its original purpose of changing the forked location of your branch to a different commit or branch. There are two general types of rebases. Ones that require human interaction to complete, and ones that do not. A human interactive rebase would involve doing things like adding, editing, deleting, combining, and splitting commits. A noninteractive rebase would be attaching your base to a different branch.

Interactive rebases are executed by running git rebase --interactive $GITREVISION Non-interactive rebases are executed by running git rebase $GITREVISION

How do I git rebase?

Determine what commits to rebase

You can use most valid forms of gitrevision syntax, but git log --oneline and git reflog are the most common options for discovering historical edits. git log --oneline will only show you commits. git reflog will show you commits in addition to actions you take like checking out branches, other rebases you’ve done, git resets, commit amends, and other historical modifications made to git. The only time I use referential syntax is if I’m recovering a previously deleted commit since git will locally log the commit even after deleting it.

Here’s a table of some gitrevision syntaxes you can use in a rebase, and what they roughly translate to.

syntax	meaning
`016a428`	rebase all commits between HEAD and `016a428`
`HEAD@{5}`	rebase all commits contained in my last 5 git actions
`HEAD~5`	rebase the last 5 commits
`HEAD@{5hr}`	rebase all commits made in the last 5 hours
`':/^Foo'`	rebase all commits made between HEAD and the first commit found with a commit message that matches the regular expression `^Foo`

Edit your git-rebase-todo

A git-rebase-todo file is a manifest containing all the commits in your rebase that you can edit to instruct git on what changes you want to make. It includes the action you want to do, the commit hash, and the commit message for easy identification. An example looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


pick e9f16f3 baz
pick ff783de buz

# Rebase aa7b423..ff783de onto aa7b423 (2 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
# commit's log message, unless -C is used, in which case
# keep only this commit's message; -c is same as -C but
# opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# . create a merge commit using the original merge commit's
# . message (or the oneline, if no original merge commit was
# . specified); use -c <commit> to reword the commit message
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#

The only commands in that list I haven’t used are exec, break, label, reset, and merge.

Start the rebase

As soon as you save the git-rebase-todo file and close it, the rebase will start. The first step git does is it saves all your commits into a staging area for safekeeping if you need to perform any reversions. Then it goes through each commit oldest to newest. Actions like pick, squash, fixup, and drop will be executed automatically. Actions like reword and edit will pause for you to make your requested changes. If it’s a git message change, it will open the commit message file and allow you to make your changes.

Edit steps are a bit more complex. Git has no idea what modifications you intend to make on the edit step, so you need to tell it when you’re finished. You can make any changes you need to the commit, and once you’re finished you run git commit --amend to add your content to the commit. Then run git rebase --continue to tell git you’re done with the current commit.

Push up your rebase

If you’re editing any commits that aren’t strictly local to your machine, you’ll have to instruct your remote git website that yes, you did mean to delete that commit. To do this, run git push --force-with-lease. If you don’t, git will reject your changes when you try and push because it thinks it has content you’re missing that you need to pull down.

--force-with-lease is the same as --force except it has a failsafe to abort if there are remote changes your local git client doesn’t know about. Always use it when force pushing changes.

Deleting commits

Determine what commits you want to delete by running git log --oneline and find the hash of the commit you intend to delete

1
2
3
4
5
6


486f3bf (HEAD -> main) e18155c658
28cabde 0523d2af6c
58098cf 5a0be3f060
add66be 8759405589 # let's delete this commit
76d462d f6ecfd8500
beeef8f (origin/main, origin/HEAD) Initial commit

Go one past that commit and copy its hash
Run git rebase --interactive 76d462d
Modify the git-rebase-todo to delete the commit

1
2
3
4


drop add66be 8759405589 # I've change the action on this commit to drop
pick 58098cf 5a0be3f060
pick 28cabde 0523d2af6c
pick 486f3bf e18155c658

Save and close the git-rebase-todo
Run git push --force-with-lease if working with remote changes to overwrite history

If everything worked, the commit should be gone. You can run git log --oneline to validate its deletion.

1
2
3
4
5
6


6144ecd (HEAD -> main) e18155c658
28971d0 0523d2af6c
ee09104 5a0be3f060
# yay the commit is gone!
76d462d f6ecfd8500
beeef8f (origin/main, origin/HEAD) Initial commit

Editing commit content

Determine what commit you want to edit by running git log --oneline and find the SHA of the commit you intend to modify

1
2
3
4
5
6


2f512ca (HEAD -> main) b8e34da2fb
1daec94 53a8322ae0
49338d3 1890202347 # let's edit this commit
6dd4f4e 3fc41f2708
10b8051 79d8d9fc4b
beeef8f Initial commit

Go one past that commit and copy its commit SHA
Run git rebase --interactive 6dd4f4e
Modify the git-rebase-todo to include your request to edit the commit

1
2
3


edit 49338d3 1890202347 # I've changed the action on this commit to edit
pick 1daec94 53a8322ae0
pick 2f512ca b8e34da2fb

Save and close the git-rebase-todo
Git will pause on the commit you want to edit
Make your changes and run git commit --amend to include the edits
Run git rebase --continue to tell git you’re done making your changes
Run git push --force-with-lease if working with remote changes to overwrite history

1
2
3
4
5
6


2093981 (HEAD -> main) b8e34da2fb
d3ecdd3 53a8322ae0
12d9704 1890202347 # this commit has a new SHA meaning the changes went through!
6dd4f4e 3fc41f2708
10b8051 79d8d9fc4b
beeef8f Initial commit

If everything worked, the commit should be edited with a new SHA. You can run git log --oneline to validate its modification.

Combining commits by squashing

Determine what commits you want to squash by running git log --oneline and find the hash of the oldest commit you want to squash

1
2
3
4
5
6


c3640e6 (HEAD -> main) 7ce9769337
9f2e595 3c8c13dfff # let's squash these two commits
e1fce22 600affbb4a # let's squash these two commits
ed85848 1186105185 # into this commit
64378f8 c8f8d0faf9
beeef8f Initial commit

go one past that commit and copy its hash
run git rebase --interactive 64378f8
modify the git-rebase-todo to include your squashes

1
2
3
4


pick ed85848 1186105185 # this is the commit we're squashing into
squash e1fce22 600affbb4a # these are the commits we're squashing
squash 9f2e595 3c8c13dfff # these are the commits we're squashing
pick c3640e6 7ce9769337

save and close the git-rebase-todo
git will pause on the newly squashed commit and give you an opportunity to modify the commit message if desired
save and close the COMMIT_EDITMSG file to finish the rebase
run git push --force-with-lease if working with remote changes to overwrite history

1
2
3
4


8188e83 (HEAD -> main) 7ce9769337
1b4f942 1186105185 # the commit has a new SHA meaning the commits were squashed in!
64378f8 c8f8d0faf9
beeef8f Initial commit

If everything worked, the commit should be edited with a new SHA. You can run git log --oneline to validate its modification.

If you enjoyed this article, have any questions, noticed something inaccurate, or you just want to say hi feel free to drop a comment below or send an email to me@norling.io

Editing Git Commit Messages

Sun, 26 Feb 2023 10:00:00 -0600

Summary

You can edit your most recent commit message by running git commit --amend.

If you’ve already pushed out your commit, you’ll have to tell the remote git repository that you intend to rewrite history. You can do this by running git push --force-with-lease after amending your commit.

Editing older commit messages

You can edit older commits with an interactive rebase. A rebase is a way to deconstruct and reconstruct older commits. You can modify things like the files changed in a commit, if the commit was signed, when the commit was created, who it was created by, and in our case you can edit commit messages.

The first step of a rebase is identifying the rebase’s span. Run git log --oneline to get a top-down list of your latest commits. Find the commit you want to edit, then select the commit hash after it and run git rebase --interactive $HASH

In the below example, If we want to edit the commit message baz [e9f16f3], we will want to run an interactive rebase on bar [aa7b423]

After you run this command, git will start a rebase and your configured git editor will give you a prompt asking how you want to proceed with the rebase. It’s worth reading this prompt entirely if you’ve never seen it before. I’ll summarize what’s needed for changing the commit message below this codeblock.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


pick e9f16f3 baz
pick ff783de buz

# Rebase aa7b423..ff783de onto aa7b423 (2 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
# commit's log message, unless -C is used, in which case
# keep only this commit's message; -c is same as -C but
# opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# . create a merge commit using the original merge commit's
# . message (or the oneline, if no original merge commit was
# . specified); use -c <commit> to reword the commit message
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#

The file you’re editing is a git-rebase-todo file. It’s used as a catalog of actions you intend to perform with each commit. It includes the action you want to do, the commit hash, and the commit message for easy identification. It’s also bottom-up instead of top-down (your newest commits are at the bottom).

pick is the default action. Commits prefixed with pick are left intact as they were before the rebase began. Since we want to edit the commit message “baz” The action we want to use is reword. Edit your git-rebase-todo file and change the word pick to reword like so

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


reword e9f16f3 baz
pick ff783de buz

# Rebase aa7b423..ff783de onto aa7b423 (2 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
# commit's log message, unless -C is used, in which case
# keep only this commit's message; -c is same as -C but
# opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# . create a merge commit using the original merge commit's
# . message (or the oneline, if no original merge commit was
# . specified); use -c <commit> to reword the commit message
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#

After you’ve made your changes, save the file and close it. Git will then prompt you to edit the commit message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


baz # change this line to anything but baz

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date: Sun Feb 26 00:19:24 2023 -0700
#
# interactive rebase in progress; onto aa7b423
# Last command done (1 command done):
# reword e9f16f3 baz
# Next command to do (1 remaining command):
# pick ff783de buz
# You are currently editing a commit while rebasing branch 'git' on 'aa7b423'.
#
# Changes to be committed:
# new file: baz
#

Once you’ve made your commit message changes, save the file and close it. Git will finalize the rebase, and you can run git log --oneline to inspect the changes. To push your changes to the remote git repository, you’ll have to run git push --force-with-lease here as well

If you enjoyed this article, have any questions, noticed something inaccurate, or you just want to say hi feel free to drop a comment below or send an email to me@norling.io

Good Kyverno Admission Control Patterns

Tue, 12 Jul 2022 16:12:18 -0600

Kyverno is a Kubernetes admission controller used to add policies to your cluster. Admission controllers intercept incoming requests to the Kubernetes api server and check if a field matches a regular expression, then approve or deny the request based on that determination. If you’re not familiar with admission controllers already, I’d recommend reading the official documentation.

If you’re in the process of deciding which admisson controller to use in your environment, consider the background of the team that will be maintaining the policies. Do they all know how to program in Golang? If so, OPA Gatekeeper may be a better choice for you. I personally believe that Kyverno is a better admission controller because the barrier for reading and writing policies is significantly lower than OPA. I haven’t run into a scenario where I need more verbose or complex syntax beyond what ships in Kyverno by default.

Summary

Have some way to whitelist resources
Make all your transformations with JSON patches
Narrow down the scope of your whitelists as much as possible
Configure all policies to accept an array of rules rather than a single ruleset
Have some way to unit test against admission controller policies when working with k8s manifests in a github repository
Separate your Kyverno installation from the underlying policies
Have some way to toggle rule actions between audit and enforcement
Add remote policies using raw.githubusercontent.com rather than copying them locally
When referencing remote policies, target a commit hash or branch version rather than the main branch’s head
Avoid mutating resources with policies when possible

Example Boilerplate

I created this example github repository that illustrates all of the principles in this article https://github.com/salineselin/kyverno-example

Recommendations

The following sections expand on the gists described earlier

Have some way to whitelist resources

It is inevitable that you will have resources in your kubernetes clusters that violate policies. Defining some generic templatized process around how you add exceptions to a whitelist is crucial. You can whitelist resources by using the exclude key like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
 name: disallow-capabilities
spec:
 validationFailureAction: audit
 background: true
 rules:
 - name: adding-capabilities
 exclude:
 any:
 - resources:
 kinds:
 - Pod
 selector:
 matchLabels:
 app: managed-prometheus-collector
 match:
 any:
 - resources:
 kinds:
 - Pod
 validate:
 message: >-
 Any capabilities added beyond the allowed list (AUDIT_WRITE, CHOWN, DAC_OVERRIDE, FOWNER,
 FSETID, KILL, MKNOD, NET_BIND_SERVICE, SETFCAP, SETGID, SETPCAP, SETUID, SYS_CHROOT)
 are disallowed.
 deny:
 conditions:
 all:
 - key: "{{ request.object.spec.[ephemeralContainers, initContainers, containers][].securityContext.capabilities.add[] }}"
 operator: AnyNotIn
 value:
 - SYS_CHROOT

Make all your changes with JSON patches

This applies if you’re using Kustomize to manage your Kyverno transformations. Kustomize overlays are excellent at implicitly overlaying all the necessary parameters, but when you start working with array indexes more, you start wiping data that you don’t intend to and you usually end up repeating yourself a lot. If you make all your transformations with JSON patches rather than overlays, you have a complete list of all your transformations, and debugging those transformations becomes a lot easier when kustomize executes and can explicitly point out a faulty JSON patch.

Narrow down the scope of your whitelists as much as possible

Whitelisting a namespace is a very primitive control for adding exceptions for entities. It’s fast and easy to understand, but is grossly overpermissive. Unless you have your RBAC hardened to a point where clusters users don’t have visibility into what the policy exceptions are, its trivial for an attacker to just use a different namespace that’s been whitelisted.

Configure all policies to accept an array of rules rather than a single ruleset

There are multiple valid syntaxes when defining a policy. You can match according to one object or an array of objects. The preferred method is an array of objects. It’s not mentioned in Kyverno’s documentation, but if you use an any match selector, you also have to use the any selector when creating exclusions. To demonstrate why you want to only work with an array of matches rather than a single defined match, let’s work with the following policy:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
 name: disallow-capabilities
spec:
 validationFailureAction: audit
 background: true
 rules:
 - name: adding-capabilities
 match:
 resources:
 kinds:
 - Pod
 validate:
 message: >-
 Any capabilities added beyond the allowed list (AUDIT_WRITE, CHOWN, DAC_OVERRIDE, FOWNER,
 FSETID, KILL, MKNOD, NET_BIND_SERVICE, SETFCAP, SETGID, SETPCAP, SETUID, SYS_CHROOT)
 are disallowed.
 deny:
 conditions:
 all:
 - key: "{{ request.object.spec.[ephemeralContainers, initContainers, containers][].securityContext.capabilities.add[] }}"
 operator: AnyNotIn
 value:
 - SYS_CHROOT

This policy which you can find in source here is perfectly valid. The problem is when you want to whitelist a particular namespace or add another ruleset with more advanced targeting, you have to heavily modify the underlying ruleset with JSON patches.

Let’s say I wanted to add two exceptions according to a label selector. Instead of a single JSON patch that looks something like the following, you would have to add multiple patches to get your policy into your defined state. Transformations are necessary, but excessive transformations mean you have more code to maintain, and legibility is decreased.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


- op: add
 path: /spec/rules/0/exclude
 value:
 any:
 - resources:
 kinds:
 - Pod
 selector:
 matchLabels:
 # gke's managed prometheus uses the host ports
 app: managed-prometheus-collector
 - resources:
 kinds:
 - Pod
 selector:
 matchLabels:
 # gke's managed prometheus rule evaluator needs them as well
 app: rule-evaluator

This is the desirable syntax

1
2
3
4
5


match:
 any:
 - resources:
 kinds:
 - Pod

And this is the less-than-desirable syntax

1
2
3
4


match:
 resources:
 kinds:
 - Pod

Almost all of the policies you find today in the public Kyverno policies repository now use the array syntax by default, but it wasn’t always that way. In this earlier commit you can find remnants of when the configured rules did not use the array syntax.

Have some way to unit test against admission controller policies when working with k8s manifests in a github repository

Debugging CI sucks. If your CI|CD pipeline is verbose and takes five minutes to deploy something to a cluster, but it fails due to a failed policy check, it chisels at your soul. Feedback loops become repetitive, slow, and unfruitful. If you’re using a CI provider like Github Actions, make a pipeline that runs a unit test using kubectl apply -f /path/to/yaml --dry-run=server. If this method is unpalatable for your use-case, it’s worth looking into tools like Datree that offer admission controller unit testing. I personally don’t use Datree because until they ship their own admission controller, there will always be a lack of parity between the policies Datree provides and the policies you provide in Kyverno.

If that isn’t soon enough and you’re still experiencing pain with iteration, you could potentially use a git hook when you push source control changes to remote (similar to how husky does it) to get that feedback even sooner. I’d recommend only implementing a hook like this if the developers working on kubernetes manifests are acclimated to kubernetes and have their policies pulled down into their local dev cluster, or they’re authenticated into a remote cluster with a context they can use to --dry-run=server against.

Most of the manifests you write are likely written and then rarely touched, so iteration slow and frequent enough to cause admission controller heartache is likely seldom.

Separate your Kyverno installation from the underlying policies

Respect that the policies you install are separate from the application that enforces the policies. They have divergent lifecycles, but should be respected as harmonious companions

Have some way to toggle rule actions between audit and enforcement

If you’re working with remote policies a lot, most of them are usually set to audit rather than enforce, so you’ll need to make a transformation that changes the validationFailureAction value. I use this JSON patch:

1
2
3


- op: replace
 path: /spec/validationFailureAction
 value: enforce

Add remote policies using raw.githubusercontent.com rather than copying them locally

Kustomize allows you to target local as well as remote resources too! Make use of the Kyverno/policies repository and use those instead of rewriting what’s likely already been written. An example kustomize manifest that uses remote resources looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
commonLabels:
 app: kyverno
resources:
 # remote policies
 - https://raw.githubusercontent.com/kyverno/policies/release-1.7/pod-security/baseline/disallow-capabilities/disallow-capabilities.yaml
 - https://raw.githubusercontent.com/kyverno/policies/release-1.7/pod-security/baseline/disallow-host-namespaces/disallow-host-namespaces.yaml
 - https://raw.githubusercontent.com/kyverno/policies/release-1.7/pod-security/baseline/disallow-host-ports/disallow-host-ports.yaml
 - https://raw.githubusercontent.com/kyverno/policies/097ca254c5d52d05bf1aa385d140e8743b9f21ba/best-practices/disallow_default_namespace/disallow_default_namespace.yaml

When referencing remote policies, target a commit hash or branch version rather than the main branch’s head

In the previous example, you can see that explicit commit hashes are targeted rather than the latest and greatest. If you’re using transformations, you’ll likely have to stage the changes and update your patches on major updates.

Avoid mutating resources with policies when possible

You can use an admission controller to mutate offending resources rather than failing them outright. In my opinion this is something you should not do if you can avoid it. It is generally better to correct the resource manifest at its source rather than mutating it. Mutations are excellent for objects like logging sidecars and other container adjacent services.

If you enjoyed this article, have any questions, noticed something inaccurate, or you just want to say hi feel free to drop a comment below or send an email to me@norling.io