Jogendra

Writing maintainable Go code

Wed, 12 Jan 2022 00:00:00 +0000

Writing maintainable code is essential. Clarity, readability, and simplicity are all aspects of maintainability. It should make the process easy for someone to join your project or maintain it after someone leaves. Maintainability is measured by how effortless it is to introduce changes and the amount of risk associated with those changes. To write Go effectively, it is crucial to understand its properties and idioms and apply the established conventions related to naming, program construction, formatting, etc.

Note: This article was originally published on Deepsource blogs.

Here are some good practices that will help write maintainable Go code.

Keep `main` small

“Tour of Go” reads:

Every Go program is made up of packages. Programs start running in package main.

main package is unique as neither the exported names are exported, nor does the compiler treat it like a regular package; instead, it compiles it to an executable program. Inside main package, main function (main.main) is present, which is the entry point to a Go program. Expectation from the main package and the main function is that they do as little as possible.

main.main acts as a singleton and gets only called once. It is also hard to write tests for the code inside main.main, thus, it is highly recommended to drive the program with main.main but not write the business logic inside main package. Segregating driver and business logic in separate packages improves the program’s structure and maintainability.

Use meaningful names

Naming in Go gives major emphasis to — consistent, short and accurate names as they tend to improve the readability of the code.

Russ Cox’s philosophy on naming:

A name’s length should not exceed its information content. For a local variable, the name i conveys as much information as index or idx and is quicker to read. Similarly, i and j are a better pair of names for index variables than i1 and i2 (or, worse, index1 and index2), because they are easier to tell apart when skimming the program. Global names must convey relatively more information because they appear in a larger variety of contexts. Even so, a short, precise name can say more than a long-winded one: compare acquire and take_ownership. Make every name tell.

There’s a high chance that years of programming experience and naming philosophies of Ken Thompson, Rob Pike, Robert Griesemer, Russ Cox, Ian Lance Taylor, etc. might have inspired the naming conventions in Go. Here’s a slide by Andrew Gerrand which talks about naming in Go in more depth.

Code grouping

Within a function (or method), some statements could be correlated. Therefore, keeping those statements within separate code blocks is recommended, separated by a newline. Grouping makes program construction better and improves readability by segregating the related parts.

// Creating new HTTP request with request body
req, err := http.NewRequest("POST", "https://api.example.com/endpoint", body)
if err != nil {
    // handle err
}

// Setting headers to HTTP request
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer b7d03a6947b217efb6f3ec3bd3504582")

// Executing the request
resp, err := http.DefaultClient.Do(req)
if err != nil {
    // handle err
}

defer resp.Body.Close()

Write meaningful comments

Comments are an excellent way to understand existing code, and it answers what it does and why some piece of code exists and why it was written like this. It is good to write comments while writing the code, but it is more important to update the comments whenever you update the code. Code updates may change the objective of a particular code, so it is crucial to update comments too; otherwise, it will create confusion rather than helping later. It is better not to write comments than comments that contradict the code. You can write block comments or inline comments in Go, whatever suits your code better.

Commenting your code correctly in Go will also allow you to use the godoc tool. godoc will extract comments from your code and generate documentation for your Go program. Comments in Go have several good features, like +build, go:generate, cgo, to name a few. Refer to The Magic of Go Comments to understand in detail.

Knowing what not to write in comments is as important as knowing what to write. It would be best to avoid over-commenting the code and leave it to other programmers to understand Go. You should avoid obvious comments, and if the code is readable enough, it doesn’t need comments. For example:

// Get country code from customer address.
countryCode := getCountryCode(address) {
    // If country code is "IN", assign "India" as
    // country.
    if countryCode == "IN" {
        country = "India"
    }
}

Comments written here are very obvious respective to code and don’t add any value.

Don’t repeat

DRY (Don’t Repeat Yourself) is a principle of software development aimed at reducing duplication of software patterns, replacing it with abstractions to avoid redundancy.

So, what’s the problem with code repetition? Not much until there’s a change. Imagine repeating the same code in 10 places and then changing at all 10 places whenever something small changes. It’s easier to maintain code if it only exists in one place, ensuring consistency. If the code is duplicated, there’s a good chance that you’ll forget to update one of the copies, meaning the bugs you fix in one copy will still be there in the other copy.

If you have to write the same code again, move it into the shared package where most helper functions lie. With the removal of duplicate code, you will have less code that will be clearer and easier to maintain.

The absence of generics (up to Go 1.17) might make Go code look repetitive in some places. But with generics being officially supported from Go 1.18 would make writing generic code a lot simpler, less redundant, and much more maintainable.

But, sometimes repeating code is simpler and easier to understand than trying to force an abstraction to avoid redundancy. So it is more important to know where to apply DRY and where to not because code readability and ease of understanding trumps other concerns.

Linting and style guidelines

Adhering to a coding standard makes the codebase consistent and easy to review and maintain. It makes the coding style consistent. Often, the style guides are opinionated, and the best way to make people adhere to the same guidelines is to create a standard style guideline for the Go code. Having a style guide is not essential, but it is more critical to make your team use it religiously. There are many open-source linting tools and style guidelines out there, and you can take the base from there and modify it to make it works for you.

Go has a code formatting standard generally used and accepted in the community, although it does not require special rules. Go provides the gofmt tool to encourage and safeguard that the Go code is formatted with established conventions.

Many editors that support integration with gofmt format the file upon saving the file. Alternatively, gofumpt, a stricter version of gofmt can be used as well. The tool is a modified fork of gofmt, which can be used as a drop-in replacement. Also, these tools do support custom source transformations and the addition of custom rules.

If you want to follow Go’s community-style guidelines, you can use golint. The tool gives helpful hints on code style and can also help review the Go’s recognized conventions. This will dramatically help onboard each new developer added to the project.

Avoid deep nesting

Excessive nesting bothers everyone. Deep nesting makes it hard to follow logic. If you’re doing code reviews or revisiting your old code, oversized functions (or methods) with lots of nesting become a mess of logical workflows. Also, nested code is hard to read; the lesser the nesting, the lesser is the cognitive load on the reader.

if condition1 {
    if condition2 {
        if condition3 {
            // ...
        } else {
            // ...
        }
    } else {
        if condition5 {
            // ...
        }
    }
}

There are several ways developers can avoid it. Here is a good read about it.

Write better functions

Avoid writing longer functions; smaller functions are better. Longer functions can be hard to read, test, and maintain. Longer functions often have bigger responsibilities, so it is recommended to break them into smaller functions. More callers can use shorter functions created from breaking down the longer functions as they now serve more managed, independent tasks.

Doug McIlroy, the inventor of Unix pipes and one of the founders of the Unix tradition, said (Unix Philosophy):

Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new features.

So breaking down function to do one thing well does resonate well with the Unix Philosophy.

As discussed earlier, naming is crucial to readability. Good function names are better than comments, and they can be just as helpful in aiding the understanding of code as a well-written comment or API documentation. Try to keep fewer function parameters; they are always better.

Avoid package level state

In Go, only one instance of a package exists for any given import path. This means that there is only one instance of any variable at the package level. Package level variables are shared across the global level, which means that all accessors will share the same instance. Function X can modify the variable, and function Y can read the modified value.

The use of package-level variables can have many implications:

It’s hard to trace where the variable got modified and where it got accessed to make any decision.
Package-level variables cause tight coupling; change in one corner of code may require a modification in another corner of code, making it tougher to read, modify, and unit test the code.
It may cause problems such as race conditions.

However, the use of package-level constants is excellent. So it is always recommended to avoid using the package-level states as much as possible. To reduce the coupling, move the relevant variables as fields on structs that need them. Defining dependencies and configuration in a struct makes it easy. The use of interfaces is also quite helpful.

Return early and use conditions wisely

Conditional statements are something that we have to write a lot. It plays a massive role in whether the code is clean or messy. For example:

func do(n int) bool {
    if n > 12 {
        return false
    } else {
        return true
    }
}

The problem with this code is that the else statement is not helping here; rather, it makes the code messy and less readable. Instead, write it like:

func do(n int) bool {
    if n > 12 {
        return false
    }
    return true
}

We often see whole functions being wrapped in if statements like this:

func do(n int) {
    if n > 12 {
        sum()
        subtract()
        multiply()
    }
}

Inverting conditional blocks will make it more clean and readable.

func do(n int) {
    if n <= 12 {
        return
    }
    sum()
    subtract()
    multiply()
}

Use switch more often

The switch statement is the best way to keep the sequence of if-else statements shorter. switch is a beneficial feature for writing clean programs. The program often requires comparison, and our program uses too many if-else, making the code messy and less readable. So the use of switch helps a lot.

func transact(bank string) {
    if bank == "Citi" {
        fmt.Printf("Tx #1: %s\n", bank)
    } else if bank == "StandardChartered" {
        fmt.Printf("Tx #2: %s\n", bank)
    } else if bank == "HSBC" || bank == "Deutsche" || bank == "JPMorgan" {
        fmt.Printf("Tx #3: %s\n", bank)
    } else if bank == "NatWest" {
        fmt.Printf("Tx #4: %s\n", bank)
    } else {
        fmt.Printf("Tx #E: %s\n", bank)
    }
}

This looks messy, right? Now let’s use a switch instead. Here is how you can rewrite the same code in an idiomatic way:

func transact(bank string) {
    switch bank {
    case "Citi":
        fmt.Printf("Tx #1: %s\n", bank)
    case "StandardChartered":
        fmt.Printf("Tx #2: %s\n", bank)
    case "HSBC", "Deutsche", "JPMorgan":
        fmt.Printf("Tx #3: %s\n", bank)
    case "NatWest":
        fmt.Printf("Tx #4: %s\n", bank)
    default:
        fmt.Printf("Tx #E: %s\n", bank)
    }
}

In the future, if new banks get added, it will be easier and cleaner with switch-case.

Continuous code refactoring

In large codebases, it’s essential to refactor the codebase structure. Code refactoring improves the readability and quality of code from time to time. It is not a one-time process; Teams should pay tech debts continuously to keep the codebase sane. I read somewhere nicely — “refactor early, refactor often”, which makes a lot of sense in writing maintainable Go code. Packages become heavy with time regarding the amount of code and responsibility, so it is better to break some packages into smaller packages as they are easy to maintain. Another good reason to refactor packages is to improve naming. It is also essential that a package only contains code related to its function. For example, Go moved from os.SEEK_SET, os.SEEK_CUR, and os.SEEK_END to io.SeekStart, io.SeekCurrent, and io.SeekEnd (respectively) are more readable. The package io is better for code involving file I/O. Breaking packages into small ones also makes the dependencies lightweight.

Conclusion

With time and other programmers working on a codebase, we understand better what maintainability means. Writing maintainable code is not complicated; it requires knowledge, experience, and careful thought from everyone contributing to the code. The set of good practices that we discussed should help you and the team maintain your Go code better.

Import Cycles in Golang: How To Deal With Them

Sun, 03 Jan 2021 00:00:00 +0000

As a Golang developer, you probably have encountered import cycles. Golang do not allow import cycles. Go throws a compile-time error if it detects the import cycle in code. In this post, let’s understand how the import cycle occurs and how you can deal with them.

Import Cycles

Let’s say we have two packages, p1 and p2. When package p1 depends on package p2 and package p2 depends on package p1, it creates a cycle of dependency. Or it can be more complicated than this eg. package p2 does not directly depend on package p1 but p2 depends on package p3 which depends on p1, again it is cycle.

Let’s understand it through some example code.

Package p1:

package p1

import (
	"fmt"
	"import-cycle-example/p2"
)

type PP1 struct{}

func New() *PP1 {
	return &PP1{}
}

func (p *PP1) HelloFromP1() {
	fmt.Println("Hello from package p1")
}

func (p *PP1) HelloFromP2Side() {
	pp2 := p2.New()
	pp2.HelloFromP2()
}

Package p2:

package p2

import (
	"fmt"
	"import-cycle-example/p1"
)

type PP2 struct{}

func New() *PP2 {
	return &PP2{}
}

func (p *PP2) HelloFromP2() {
	fmt.Println("Hello from package p2")
}

func (p *PP2) HelloFromP1Side() {
	pp1 := p1.New()
	pp1.HelloFromP1()
}

On building, compiler returns the error:

imports import-cycle-example/p1
imports import-cycle-example/p2
imports import-cycle-example/p1: import cycle not allowed

Import Cycles Are Bad Design

Go is highly focused on faster compile time rather than speed of execution (even willing to sacrifice some run-time performance for faster build). The Go compiler doesn’t spend a lot of time trying to generate the most efficient possible machine code, it cares more about compiling lots of code quickly.

Allowing cyclic/circular dependencies would significantly increase compile times since the entire circle of dependencies would need to get recompiled every time one of the dependencies changed. It also increases the link-time cost and makes it hard to test/reuse things independently (more difficult to unit test because they cannot be tested in isolation from one another). Cyclic dependencies can result in infinite recursions sometimes.

Cyclic dependencies may also cause memory leaks since each object holds on to the other, their reference counts will never reach zero and hence will never become candidates for collection and cleanup.

Robe Pike, replying to proposal for allowing import cycles in Golang, said that, this is one area where up-front simplicity is worthwhile. Import cycles can be convenient but their cost can be catastrophic. They should continue to be disallowed.

:hammer_and_wrench: Debugging Import Cycles

The worst thing about the import cycle error is, Golang doesn’t tell you source file or part of the code which is causing the error. So it becomes tough to figure out when the codebase is large. You would be wondering around different files/packages to check where actually the issue is. Why golang do not show the cause that causing the error? Because there is not only a single culprit source file in the cycle.

But it does show the packages which are causing the issue. So you can look into those packages and fix the problem.

To visualize the dependencies in your project, you can use godepgraph, a Go dependency graph visualization tool. It can be installed by running:

go get github.com/kisielk/godepgraph

It display graph in Graphviz dot format. If you have the graphviz tools installed (you can download from here), you can render it by piping the output to dot:

godepgraph -s import-cycle-example | dot -Tpng -o godepgraph.png

You can see import cycle in output png file:

Apart from it, you can use go list to get some insights (run go help list for additional information).

go list -f '{\{join .DepsErrors "\n"\}}' <import-path>

You can provide import path or can be left empty for current directory.

Dealing with Import Cycles

When you encounter the import cycle error, take a step back, and think about the project organization. The obvious and most common way to deal with the import cycle is implementation through interfaces. But sometimes you don’t need it. Sometimes you may have accidentally split your package into several. Check if packages that are creating import cycle are tightly coupled and they need each other to work, they probably should be merged into one package. In Golang, a package is a compilation unit. If two files must always be compiled together, they must be in the same package.

The Interface Way:

Package p1 to use functions/variables from package p2 by importing package p2.
Package p2 to call functions/variables from package p1 without having to import package p1. All it needs to be passed package p1 instances which implement an interface defined in p2, those instances will be views as package p2 object.

That’s how package p2 ignores the existence of package p1 and import cycle is broken.

After applying steps above, package p2 code:

package p2

import (
	"fmt"
)

type pp1 interface {
	HelloFromP1()
}

type PP2 struct {
	PP1 pp1
}

func New(pp1 pp1) *PP2 {
	return &PP2{
		PP1: pp1,
	}
}

func (p *PP2) HelloFromP2() {
	fmt.Println("Hello from package p2")
}

func (p *PP2) HelloFromP1Side() {
	p.PP1.HelloFromP1()
}

And package p1 code look like:

package p1

import (
	"fmt"
	"import-cycle-example/p2"
)

type PP1 struct{}

func New() *PP1 {
	return &PP1{}
}

func (p *PP1) HelloFromP1() {
	fmt.Println("Hello from package p1")
}

func (p *PP1) HelloFromP2Side() {
	pp2 := p2.New(p)
	pp2.HelloFromP2()
}

You can use this code in main package to test.

package main

import (
	"import-cycle-example/p1"
)

func main() {
	pp1 := p1.PP1{}
	pp1.HelloFromP2Side() // Prints: "Hello from package p2"
}

You can find full source code on GitHub at jogendra/import-cycle-example-go

Other way of using the interface to break cycle can be extracting code into separate 3rd package that act as bridge between two packages. But many times it increases code repetition. You can go for this approach keeping your code structure in mind.

“Three Way” Import Chain: Package p1 -> Package m1 & Package p2 -> Package m1

The Ugly Way:

Interestingly, you can avoid importing package by making use of go:linkname. go:linkname is compiler directive (used as //go:linkname localname [importpath.name]). This special directive does not apply to the Go code that follows it. Instead, the //go:linkname directive instructs the compiler to use “importpath.name” as the object file symbol name for the variable or function declared as “localname” in the source code. (definition from golang.org, hard to understand at first sight, look at the source code link below, I tried solving import cycle using it.)

There are many Go standard package rely on runtime private calls using go:linkname. You can also solve import cycle in your code sometime with it but you should avoid using it as it is still a hack and not recommended by the Golang team.

Point to note here is Golang standard package do not use go:linkname to avoid import cycle, rather they use it to avoid exporting APIs that shouldn’t be public.

Here is the source code of solution which I implemented using go:linkname :

-> jogendra/import-cycle-example-go -> golinkname

Bottom Lines

The import cycle is definitely a pain when the codebase is large. Try to build the application in layers. The higher-level layer should import lower layers but lower layers should not import higher layer (it create cycle). Keeping this in mind and sometimes merging tightly coupled packages into one is a good solution than solving through interfaces. But for more generic cases, interface implementation is a good way to break the import cycles.

You can checkout interesting discussion about this blog post on Reddit here.

I hope you got a fair understanding of Import Cycles. Do share and reach out to me on Twitter in case of anything. You can follow my open source work at github/jogendra. Thanks for read :)

Implementing Launch at Login Feature in MacOS Apps

Sun, 20 Sep 2020 00:00:00 +0000

In this post, I will explain, how you can add the Launch at Login (launch application on system startup) feature to your MacOS Applications. Adding this feature is way more complex than you would expect. I use MeetingBar for managing my work/personal meetings over Google Meet and Zoom. MeetingBar is an open-source MacOS App. Recently, I added the Launch at Login feature to MeetingBar. Initially, I thought that there will be a simple solution to it and it will take minutes only. But when I started implementing it, I found out that it is not really that straight forward. You can find the implementation source code below.

Link to Pull Request: Add Launch at Login feature

Source Code for this post: https://github.com/jogendra/launch-at-login-macos

For the users, a straightforward solution is going to system preference and enable auto launching for applications (Preferences -> Users & Groups -> Login Items). But it is always good if the application itself offers the feature from its preference. For application developers, it’s a bit tricky.

There are a couple of ways to add a login item to the application. The most used/useful way is using the Service Management framework. Login items installed using the Service Management framework are not visible in System Preferences and can only be removed by the application that installed them. The other way is using a shared file list. Login items installed using a shared file list are visible in System Preferences; users have direct control over them. If you use this API, your login item can be disabled by the user.

In this post, I will explain how to add login items to MacOS Applications using the Service Management framework. The idea is to create an application inside the main application that handles the auto launching for the main application.

Little bit about Apple App Sandboxing

According to Apple documentation, to distribute a macOS app through the Mac App Store, you must enable the App Sandbox capability. App Sandbox provides protection to system resources and user data by limiting your app’s access to resources requested through entitlements. Apps signed and distributed outside of the Mac App Store with Developer ID can (and in most cases should) use App Sandbox as well. App Sandbox enables you to describe how your app interacts with the system. The system then grants your app the access it needs to get its job done and no more. It is always best to design your apps with App Sandbox in mind. You can check out this detailed article by Appcoda on Mac App Sandbox.

Every application is given a sandbox, a directory it can use to store data. An application cannot access the sandbox of another application. If the application needs access to data on the device that isn’t located in the application’s sandbox, it needs to request the data through a system interface. System interfaces add a layer of security and protect the user’s privacy.

To adopt App Sandbox for a target in an Xcode project, apply the <true/> value to the com.apple.security.app-sandbox entitlement key for that target. Do this in the Xcode target editor by selecting the Enable App Sandboxing checkbox.

Generally, when you create macOS App, it is already added, you don’t have to worry about it.

:zap: Initial Setups

In this post, we will use MainApplication for the main application (using SwiftUI) in which we are going to add Launch at Login functionality and the other one will be AutoLauncher, which is our helper application that is responsible for registering our main application for login items.

:hammer_and_wrench: Adding Helper Target

To add helper target AutoLauncher to our MainApplication, go to File -> New -> Target and choose macOS template with App selected (under Application section) and click Next button to choose options for helper application.

In next screen, choose ‘AutoLauncher’ for Product Name (or whatever name you want to give), select ‘Storyboard’ option for the User Interface option (we will delete this interface later anyway), make sure the Project option has ‘MainApplication’ target selected and finish the setup.

:gear: Helper Target Configurations

Since our helper target AutoLauncher should be background only as we don’t need user interface for AutoLauncher. So to make it background only service, go to Info.plist of AutoLauncher, set Application is background only key to YES.

Go to Targets, select ‘AutoLauncher’ Target’s Build Settings, and search for “skip install”. Set Skip Install to Yes. Otherwise we would end up with too many bundles in our final app archive.

Go to AppDelegate.swift of AutoLauncher, rename class name AppDelegate to AutoLauncherAppDelegate (or whatever name you want to give) because it is conflicting with AppDelegate class of our MainApplication. We will configure this Delegate class method applicationDidFinishLaunching(_ :) like below. It check if MainApplication is running, if not, launch application using openApplication(at:_:_:). This instance method launches the app at the specified path URL.

This AutoLauncher app target is actually embedded inside the MainApplication bundle under the subdirectory Contents/Library/LoginItems (we are going to do this later). So including the helper app target name (AutoLauncher) there will be a total of 4 path components to be deleted. That’s why we are running loop 4 times.

:anger: Cleaning Up Helper Target UI Elements

Helper target app (AutoLauncher) should not have any UI elements. We will remove all the visual elements from the app, even the Main.storyboard. Now, got ahead and:

Delete ViewController.swift file.
Delete Assets.xcassets folder.
Delete Main.storyboard.

Since we have deleted entry point of AutoLauncher target which was earlier configured in deleted Main.storyboard file. To make that up, follow:

Create and add main.swift file (please note it has to be ”main” with lowercased ”m”, otherwise it won’t work) to AutoLauncher.
Remove @NSApplicationMain from AutoLauncherAppDelegate class. @NSApplicationMain is no longer needed because in-general @NSApplicationMain implicit generate the main.swift file for us which we have already created.
Set the Application delegate like below in main.swift:

Clean? We are done with all the setups for helper. Now, let’s configure our Main Application.

:electric_plug: Adding Helper to Main Application

We have to copy the helper application AutoLauncher inside our MainApplication. To do so, go to Project Setting, have MainApplication target selected, select Build Phases, click + icon shown below, and select New Copy Files Phase.

Apply Settings as below:

Select Wrapper as Destination, put Contents/Library/LoginItems in Subpath and finally click on + icon to add AutoLauncher.app there (it will be inside Product folder).

Now, go to General tab and Add ServiceManagement framework to Frameworks, Libraries, and Embedded Content section.

You can now import ServiceManagement to any of your swift file and use the SMLoginItemSetEnabled(_:_:) function to enable a helper application. It takes two arguments, a CFStringRef containing the bundle identifier of the helper application, and a Boolean specifying the desired state. This value is effective only for the currently logged-in user. Pass true to start the helper application immediately and indicate that it should be started every time the user logs in. Pass false to terminate the helper application and indicate that it should no longer be launched when the user logs in. This function returns true if the requested change has taken effect; otherwise, it returns false. This function can be used to manage any number of helper applications.

Example UI

In this example, I just added a simple toggle using SwiftUI. On toggle, it’s calling SMLoginItemSetEnabled function with helper app identifier and current state of toggle. Further, you can store current state in UserDefaults.

NOTE: If multiple applications (for example, several applications from the same organization) contain a helper application with the same bundle identifier, only the one with the greatest bundle version number is launched. Any of the applications that contain a copy of the helper application can enable and disable it. You should keep this in mind if you are shipping applications under the same organization. You can read more in detail about this here.

:link: Helpful Links

:memo: Closing Notes

We have seen how we can add login items to any MacOS application. You can Download Full Source Code Here. Adding login items to macOS applications isn’t that straight-forward. You need to follow all the setps carefully. I hope this post helped you in some way. Do share and drop me suggestions/questions on Twitter. Thanks for read :)

Using Vim for Go Development

Tue, 28 Jul 2020 00:00:00 +0000

As a programmer, you spend a lot of time using text editors, IDEs, etc to code. So it is important what and how you use it. I recently moved to Vim for Go development and I am totally loving it. Initially, I was using VSCode with Go extension and after that, I used GoLand for a while. Visual Studio Code and GoLand both are totally awesome, I loved using them too. It definitely takes some time to learn using vim but it is worth the learning. It is totally up to you what works better for you. Do not use vim just because others are using it. I am very much a beginner to vim and things I am going to explain in this is what I learned after I started using it. I would be really glad if you are a long time Vim user and have some good advice/suggestions. You can put them in the comment section of this post. If you are a beginner, I will put some good resources for learning vim at the bottom of this post.

Why do people use Vim?

Vim is guaranteed to exist on all Unix systems (basically, it’s available on every major platform). It’s everywhere, and it’s the same on all platforms. Vim supports all file formats and programming languages, no need to download different IDEs for different programming languages.
Mouse free navigation. Your fingers very rarely have to leave the home row, which means you’ll be able to edit text very, very quickly. You can do key mapping according to your convenience. Not having to switch between keyboard and mouse is definitely nice with Vim.
Vim is very light-weight and fast. Vim can easily handle large files but Visual Studio or other IDE couldn’t handle them smoothly. Try opening a large file (~20MB) with your favorite non-vim text editor and vim, you will definitely get to know the difference. There is great power in the way Vim handles files (buffers), splits (windows), and layouts (tabs), the power that you can’t get in other editors.
Vim and vim like text editors (emacs, nano, etc) feel and look so native, no distraction. I don’t have to switch between the terminal and editor/IDE. It’s just simply everything in one place. It’s pretty easy to be productive in vim with little effort.
Vim is very handy when you have to make quick configurational or other changes to the remote machine/server. Even on your own machine, you won’t open a heavy text editor for small change.
Vim is highly configurable. You can simply use ~/.vimrc to override default configurations and personalize yours. Vim plugins provide everything to vim that you need in a text editor. Autocomplete, syntax highlighting, or any other feature you name it and it is available, you just need the right plug-in.
Using vim is fun. It’s little challenging to use initially, but it become fun once you get used to it.

Let’s GO!

In this post, we will explore setting up Vim as a full-fledged IDE for Go development. Plugins we are going to use are:

vim-go: Go development plugin for Vim. It has everything you need for Go development.
NERDTree - File system explorer for the Vim. It enables you to visually browse complex directory hierarchies, quickly open files for reading or editing, and perform basic file system operations.

:electric_plug: Vim-Go

Vim-Go is most popular and most used vim plugin for Go development. It offer almost all the features you may need. Some of them are:

Compile your package with :GoBuild, install it with :GoInstall or test it with :GoTest.
Quickly execute your current file(s) with :GoRun.
Syntax highlighting and folding.
Autocompletion support via gopls.
Run gofmt and goimports on save. Means, you don’t have to worry about importing packages and code formatting, vim-go will do that for you on saving the file.
Go to symbol/declaration with :GoDef and look up documentation with :GoDoc or :GoDocBrowser.
Check code coverage, do code linting etc.

You can check all the feature offered by vim-go here.

Installing vim-go

Vim 8 added native support for packages which mean you can load plugins by just cloning their contents into your ~/.vim directory. To install vim-go, you can simple run command:

git clone https://github.com/fatih/vim-go.git ~/.vim/pack/plugins/start/vim-go

You will also need to install all the necessary binaries. vim-go makes it easy to install all of them by providing a command, :GoInstallBinaries, which will go get all the required binaries.

Or you can put plugin in your ~/.vimrc.

call plug#begin()
Plug 'fatih/vim-go', { 'do': ':GoUpdateBinaries' }
call plug#end()

Now save the .vimrc and install the plugin by running vim +PlugInstall. It will install vim-go plugin with all the necessary binaries.

I have added following vim-go related directives to my .vimrc, to make it more useful:

filetype plugin indent on

set autowrite

“ Go syntax highlighting
let g:go_highlight_fields = 1
let g:go_highlight_functions = 1
let g:go_highlight_function_calls = 1
let g:go_highlight_extra_types = 1
let g:go_highlight_operators = 1

“ Auto formatting and importing
let g:go_fmt_autosave = 1
let g:go_fmt_command = "goimports"

" Status line types/signatures
let g:go_auto_type_info = 1

" Run :GoBuild or :GoTestCompile based on the go file
function! s:build_go_files()
  let l:file = expand('%')
  if l:file =~# '^\f\+_test\.go$'
    call go#test#Test(0, 1)
  elseif l:file =~# '^\f\+\.go$'
    call go#cmd#Build(0)
  endif
endfunction

“ Map keys for most used commands.
“ Ex: `\b` for building, `\r` for running and `\b` for running test.
autocmd FileType go nmap <leader>b :<C-u>call <SID>build_go_files()<CR>
autocmd FileType go nmap <leader>r  <Plug>(go-run)
autocmd FileType go nmap <leader>t  <Plug>(go-test)

You can visit official tutorials for your own customisations. Complete vim-go documentations are available in your vim editor, you can simply run :help vim-go to check them out. This is how my vim look for a Go programm after installing and configuring vim-go:

Beautiful?

Auto Completion

It’s really hard to code without auto completion and not being able to going to definition. Vim-go can use gopls for completion etc. Completion is enabled by default via omnifunc. While you are in INSERT mode, you can trigger completion with Ctrl-x Ctrl-p. If matching names are found, a pop-up menu opens which can be navigated using the Ctrl-n and Ctrl-p keys. To check if vim-go’s ftplugin/go.vim has been configured correctly for autocompletion, you can run:

:verbose setlocal omnifunc?

Message below should appear:

omnifunc=go#complete#Complete
        Last set from ~/.vim/pack/plugins/start/vim-go/ftplugin/go.vim

If you want the autocomplete prompt to appear automatically whenever you press the dot (.), you can add the following line to your .vimrc:

au filetype go inoremap <buffer> . .<C-x><C-o>

Now, typing should offer auto suggestions along with documentation previews. It should look something like this:

Apart from vim-go completion, there some good plugins which you can use for auto completion and other LSP features. Some of them are:

coc.nvim (Conquer of Completion): Intellisense engine for Vim8 & Neovim, full language server protocol support as VSCode.
LanguageClient-neovim: Minimal Language Server Protocol client written in Rust.
YouCompleteMe: Code-completion engine. It has several completion engines.

Language Server Protocol (LSP) and gopls

The Language Server protocol is used between a tool (the client) and a language smartness provider (the server) to integrate features like auto complete, go to definition, find all references and alike into the tool. The goal of the protocol is to allow programming language support to be implemented and distributed independently of any given editor or IDE. The Language Server Protocol was originally developed for Microsoft’s Visual Studio Code and is now an open standard. Microsoft collaborated with Red Hat and Codenvy to standardise the protocol’s specification.

Before LSP, there used to be different IDEs for different languages (still there are many). Every IDEs had language specific integration (syntax highliting, auto completion, going to defination, etc features). The situation is often referred to as an M × N problem, where the number of integrations is the product of M editors and N languages. What the Language Server Protocol does is change this M × N problem into a M + N problem. Best things about LSP is, it is totally independent of IDEs. As a result we can see that, Visual Studio work for so many different languages via extensions. These extensions make use of LSP.

You can read more about LSP here and her or watch this YouTube video to see how it works.

Official Language Server for Golang is gopls (pronounced: ”go please”). You can check more information about the status of gopls and its supported features.

:electric_plug: NERDTree

After setting up a lot of stuffs in your Vim, one thing you probably still missing the most is “Side Window” where you can browse your project files easily. NERDTree got you there. NERDTree is a fully fledged file system explorer, which helps to visually browse your files using a tree-style side window. With NERDTree, you can quickly open files for reading or editing, and perform basic file system operations.

Installation and Setups

You can install NERDTree same as vim-go and coc.nvim. Simply add Plug 'preservim/nerdtree’ to .vimrc and run :PlugInstall or run vim +PlugInstall from command line.

Further, you can checkout wiki FAQs for setups. My setups for NERDTree is similar to:

map <C-z> :NERDTreeToggle<CR> “ Toggle side window with `CTRL+z`.
let g:NERDTreeDirArrowExpandable = '▸'
let g:NERDTreeDirArrowCollapsible = '▾'
let NERDTreeShowHidden=1 “ Show hidden files

You can open a directory into vim using vim . (similar to code . for VSCode). You can switch between NERDTree and your code by using CTRL+ww or CTRL+w+ArrowKey. NERDTree has built-in documentations, you can check them by pressing ? when you are in NERDTree window.

This is how my Vim setup look like with NERDTree:

You can have a look at my .vimrc and vim scripts on GitHub at jogendra/dotfiles/vim.

Helpful Links

Here are some links that will help you get started with Vim:

You can simply run vimtutor in your command line by running vimtutor command. It will open up Vim tutorials and help you getting started with it.

Bottom Lines

Using vim is fun. Initially you may face some problem using it and you may have to learn how to use it but it is definitely worth learning it. Atleast you can continue learning vim along side using a IDE. Start with the minimum and build a little on it each day. There are a lot of plugins available for everything you need with Vim. Using vim for Golang development is super nice with vim-go plugin. Isn’t it nice to having everything at one place and being more productive?

Thanks for reading. Do share with your colleagues/friends. You can reach out to me on Twitter.

Building Command Line Tools in Go

Sun, 05 Jul 2020 00:00:00 +0000

Command line interface (CLI) tools are an essential part of any developer. CLI tools are lightweight, less noisy, fun to use and of course they make you more productive. Everyday I try to be more dependent on Terminal (I use iTerm) and get rid of GUI applications, simply because I am more focused using a tool that provide me everything with just some commands/scripts than some fancy GUI application that come with fancy popups, ads, pictures which add noise to my focus.

In this example, we will create a simple (but scalable to any level) bookmark CLI tool in Go using Cobra that can do basic operations like adding a new bookmark, listings, clear etc. I will try to keep it as much detailed as possible.

Why Go?

Go brings a whole set of advantages. Go compiles very quickly into a single binary, works across platforms with a consistent style, and brings a strong development community. Go applications are built into a single self contained binary making installing Go applications trivial. Easy concurrency model makes Go easy to progress with multiple tasks at the same time. Concurrency is an integral part of Go (Selling point of Go :P), supported by goroutines, channels. Go also provides backward compatibility. The list is long, let’s move on to the next part.

If you aren’t familiar with Go, you simply go through Go Tour for basic understandings.

Go is simply great to build CLI tools. Go might be the fastest and perhaps the most fun way to automate tasks. With Go, you can develop cross-platform command-line tools that are fast and reliable. There are many good libraries out there for building CLI tools and one of such library is Cobra, which we will using in this example project.

Before we start

Before we proceed any further, install Go on your machine, if you have not already installed so. For this, you can follow the installation procedure on the official Golang website. It is good to have recent version of Go on your machine. You can simply execute go version to check Go version installed on your machine.

Setting up environment variables

Environment variables, are variables in your system that describe your environment. They are executed and added to your machine environment before you access/use them. During the Go installation, some Go specific environment variables are set to configure behavior of Go tools on your machine. You can check Go environment variables by running go env.

In your .zshrc or .bashrc file, append your system’s $PATH so that we can invoke bookmark command from anywhere.

export PATH=${PATH}:$HOME/go/bin

PATH=${PATH}:path/to/folder is an interesting thing of unix, I will keep it for some other blog post to explain it in details.

Restart your terminal once to source them into your machine environment or just source ~/.zshrc.

Playing with Cobra

Cobra is widely popular Go package and many projects use it for building CLI tools. Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files. Many of the most widely used Go projects are built using Cobra such as Kubernetes, Hugo, Docker (distribution), GitHub CLI and many more big names.

Cobra is built on a structure of commands, arguments and flags. Commands represent actions, Args are things and Flags are modifiers for those actions. APPNAME is the name of your tool.

APPNAME COMMAND ARG --FLAG

For example:

git clone URL --bare

Cobra provides a lot of feature, you can check them out here.

Installing Cobra

You can simply use go get to install the latest version of Cobra. This command will install the cobra generator executable along with the library and its dependencies.

go get -u github.com/spf13/cobra/cobra

The cobra binary is now in the bin/ (usually ~/go/bin/cobra) directory, which is itself in your PATH, so it can be used directly from anywhere. You can run cobra help or just cobra to get more familiar with it.

Let’s get started

First step to generate a basic organizational structure that cobra follows. Cobra provides its own program that will create your application and add any commands you want. It’s the easiest way to incorporate Cobra into your application. Run this in your newly created project directory:

cobra init --pkg-name bookmark

Here bookmark is our tool name. This will generate basic structure which will look like:

├── LICENSE
├── cmd
│   └── root.go
└── main.go

A package named cmd is created which contains all of your commands files. main.go is the entry point of your tool, it export cmd package and run Execute() func from cmd/root.go which execute the root command (base command of your tool, bookmark in this example). rootCmd represents the base command when called without any subcommands.

var rootCmd = &cobra.Command{
    Use:   "bookmark",
    Short: "A brief description of your application",
    Long: `A longer description that spans multiple lines
           and likely contains examples and usage of using
           your application.`,
}

Here is how main.go look like:

package main

import "bookmark/cmd"

func main() {
    cmd.Execute()
}

We are importing bookmark/cmd inside our main.go. Let’s create bookmark module before building and using it.

go mod init bookmark

It will create go.mod file which look like:

module bookmark

go 1.14

require (
	github.com/mitchellh/go-homedir v1.1.0
	github.com/spf13/cobra v1.0.0
	github.com/spf13/viper v1.7.0
)

Now, let’s just build this module with:

go build

This build a binary for bookmark module and generate go.sum for the same.

Run the command below to install the module so that we can run bookmark command.

go install bookmark

Now, if you run bookmark inside your terminal, it will show the details about the tool, available commands, flags etc. You can notice that it already has help command, Cobra created that for us.

A Command Line tool to manage all of your bookmarks at one place.

Usage:
  bookmark [command]

Available Commands:
  help        Help about any command

Flags:
      --config string   config file (default is $HOME/.bookmark.yaml)
  -h, --help            help for bookmark
  -t, --toggle          Help message for toggle

Use "bookmark [command] --help" for more information about a command.

Here config file is simple configuration file which will help you eliminate providing a bunch of repeated information in flags over and over. You can check out more about it here.

Creating our first command

We are done with initial setups. Now, let’s create the first command of our tool. With cobra add, you can generate new command.

Cobra add <command>

We will create a command called insert which we will use to add a new bookmark to the bookmarks list.

Cobra add insert

This will create a new go file insert.go to cmd with the initial format. We will simply store bookmarks into a text file located at ~/.bookmarks/bookmarks.txt.

package cmd

import (
    "os"
    "os/exec"
    "github.com/spf13/cobra"
)

// insertCmd represents the insert command
var insertCmd = &cobra.Command{
    Use:   "insert",
    Short: "Add a new bookmark to bookmarks list",
    Long: `When you run this command with a link or text,
            it add that link/text to your bookmarks list`,
    Run: func(cmd *cobra.Command, args []string) {
        homeDir, _ := os.UserHomeDir()
		bookmarkFile := homeDir + "/.bookmarks/bookmarks.txt"
		if _, err := os.Stat(bookmarkFile);
		os.IsNotExist(err) {
			os.Mkdir(homeDir + "/.bookmarks", 0700)
			os.Create(homeDir + "/.bookmarks/bookmarks.txt")
		}
        f, _ := os.OpenFile(bookmarkFile,
                            os.O_APPEND|os.O_WRONLY,
                            os.ModeAppend) 
		f.WriteString(args[0] + "\n") 
		f.Close()
    },
}

func init() {
    rootCmd.AddCommand(insertCmd)
}

Every command will have a kind of similar structure to this. The Run inside the insertCmd is called when you run bookmark insert so we have implemented very simple functionality inside it. It simply checks if ~/.bookmarks/bookmarks.txt exist, if not, create one otherwise add this new bookmark text/link (which we will provide in argument) to the database which is simply a text file.

Now, you can use insert command like this:

bookmark insert "this is my first bookmark, i love this tool"

Woah! You just created your first command successfully. Easy?

Adding more commands

We will add couple of more commands to our tool. The procedure is same as what we followed in creating our first command.

cobra add list
cobra add clearall

We will use our newly created list command to display all the bookmarks in our bookmark database and clearall to clear all the bookmarks from databse. You can check out cmd/list.go and cmd/clearall.go files.

Now, if you run bookmark help in terminal, it will show newly added commands too. Make sure you run go install bookmark to see new changes.

Implementing Subcommands

In this part, we will add a subcommand last to our bookmark list command. This subcommand will display the last most added bookmark. The cobra command for creating subcommand is like below:

cobra add <subcommand> -p <parent command>

Let’s add last subcommand to list with:

cobra add last -p listCmd

listCmd is internal representation of list command.

Our implementation for last subcommand look like this in cmd/last.go file:

package cmd

import (
    "fmt"
    "os"
    "bufio"
    "github.com/spf13/cobra"
)

// lastCmd represents the last command
var lastCmd = &cobra.Command{
    Use:   "last",
    Short: "Show the last most bookmark added",
    Long: `Show the last most bookmark added from the bookmarks list`,
    Run: func(cmd *cobra.Command, args []string) {
        homeDir, _ := os.UserHomeDir()
        if _, err := os.Stat(homeDir + "/.bookmarks/bookmarks.txt");
        os.IsNotExist(err) {
            fmt.Println("Your bookmarks list is empty")
            return
        }
        f, _ := os.Open(homeDir + "/.bookmarks/bookmarks.txt")
        defer f.Close()
        scanner := bufio.NewScanner(f)
        var lastLine string
        for scanner.Scan() {
            lastLine = scanner.Text()
        }
        fmt.Println(">", lastLine)
    },
}

func init() {
    listCmd.AddCommand(lastCmd)
}

Now, if we run bookmark list last, it will display the last bookmark added. Don’t forget to rebuild binary with go install bookmark before running command. You can check newly added subcommand on list by running bookmark list --help

The last subcommand is considered a command line argument to the list command. Similarly, you can add subcommands to other commands and to subcommands itself.

Next, you can implement/add flags to your commands. It is very easy to working with flags in Cobra. You can follow their Readme/docs on flags. What we done is very basic, you can do lot with Cobra.

Source Code Sturcture

After implementing commands and subcommands, project structure looks like below:

.
├── LICENSE
├── README.md
├── cmd
│   ├── clearall.go
│   ├── insert.go
│   ├── last.go
│   ├── list.go
│   └── root.go
├── go.mod
├── go.sum
└── main.go

1 directory, 10 files

Run go install bookmark to rebuild binary.

Now, if you run bookmark help in terminal, it will look like this:

Full source code: jogendra/bookmark-cli

Wrapping up

So now you have successfully made a user-friendly CLI tool which can perform basic operations. You can check out the full source code at jogendra/bookmark-cli. You have seen how easy and scalable it is to make a CLI tool in Go using Cobra. Go is simply great language choice to build CLI tools and Cobra is undoubtly first choice. Main aim is to create basic understanding. I will keep updating it with more basic operations if it requires. Thanks for reading. Looking forword to see what you are building.

I do Dotfiles!

Wed, 10 Jun 2020 00:00:00 +0000

One of the main advantages/beauty of Unix-like systems is that configurations of everything are very customizable. Dotfiles are simply amazing. They are tiny-little configurations files but they customize/decide a lot of your system. Well-organized and understandable dotfiles basically allow you to automatize complex tasks that you repeat everyday. With dotfiles, your machine is more organized, advanced, and customized in the way you like your system to be. Also with dotfiles, you can mess around with new packages and settings quite easily, without ever having to worry about really breaking something important. If you would break something, your dotfiles are always right there to back you up.

TL;DR: Invest time learning to configure your machine and automate processes, you’ll get that time back tenfold.

Your experience, knowledge and talent are key to success, but some kick-ass dotfiles speed you up.

:rocket: :sparkles: My dotfiles can be found at jogendra/dotfiles

What are dotfiles?

Dotfiles are files and folders on Unix-like systems starting with . (dot) that control the configuration of applications and shells on your system. Dotfiles are shell scripts that are executed to change the environment of your machine. The “dotfiles” name is derived from the configuration files in Unix-like systems that start with a dot (e.g. .zshrc and .gitconfig). For normal users, this indicates these are not regular documents, and by default are hidden in directory listings. You can display dotfiles inside any directory by running ls -a command. GitHub does dotfiles is definitely great place to explore and know more about dotfiles.

Why dotfiles start with . (dot) is an interesting example of a bug that has become a feature. Checkout interesting reads on Why do hidden files in Unix begin with a dot?.

GitHub Codespaces and Dotfiles

Recently GitHub announced Codespaces. According to GitHub, Codespaces uses your dotfiles repository on GitHub to personalize every new codespace that you create. Anyone can create a dotfiles repository to personalize Codespaces for their user account. If your user account on GitHub owns a public repository named dotfiles, GitHub automatically uses this repository to personalize your codespace environment. Read more about this here.

The main reason behind creating dotfiles is customizing your machine the way you like. Imagine the situation when your machine got broken or some reason you have to change your machine or you have changed your workplace so the machine, in that case, if you haven’t put your dotfiles on some remote machine, you will have to create the dotfile again which was was your long time iterations. With dotfiles, you can have a new machine ready in hours, providing the exact same user experience as the previous one. You can publicly put them on GitHub/Dropbox/etc or keep them private. It is worth keeping your dotfiles under version control for several reasons. Keeping a history of your changes allows you to safely experiment with new configurations, revert bad changes, and review the details of past changes. It is recommended to use different branch for different systems eg. you can put macOS focused dotfiles in one branch and linux system focused dotfiles on another branch so that it become easier for you when you shift between systems. I have made my own dotfiles open sourced, and parts of my configuration are inspired by other people’s dotfiles. Afterall, dotfiles are meant for sharing.

Do not blindly copy dotfiles

Mostly, dotfiles are very specific to the individual developer. What works for someone else isn’t necessarily optimal for you. Rather than using someone else’s dotfiles, it is recommended to create your own dotfiles. But it is always great to look into other’s dotfiles to get better ideas, also you can use a bit and pieces of their profiles if you think that will be helpful to you. Going through other’s dotfiles is a great way to improve your own dotfiles. Before creating mine, I went through a lot of other’s dotfiles on GitHub. I took this idea of organizing (structure) dotfiles from Holman dotfiles. You can get ideas from different dotfiles and cherry pick some of their part into yours, so for the same reason you can make your dotfiles public on GitHub/GitLab etc. and let the other developers pick and choose from it. I do not agree with “dotfiles are meant to be forked”.

Securing the dotfiles

Dotfiles often contain some private data like plain text passwords and some pieces of information you don’t wanna share publicly. Anything that is a security risk, like files in your .ssh/ folder, is not a good choice to share using this method. Be sure to double-check your configuration files before publishing them online and triple-check that no API tokens are in your files. You can use gitattributes for git related sensitive information. Version controlled folder’s files that contain sensitive information and should not be published are kept secret using package-specific .gitignore files.

git config credential.helper store is not a very secure way to store your git server passwords. According to git credential store documentations, store helper will store your passwords unencrypted on disk, protected only by filesystem permissions. The ~/.git-credentials file will have its filesystem permissions set to prevent other users on the system from reading it, but will not be encrypted or otherwise protected. So it stores your password as is. So if you are running macOS on your machine, Git allows to use your keychain, which is way more secure. To set osxkeychain as your git credential helper, run:

git config --global credential.helper osxkeychain

If you are runnning Linux on your machine, you can use git config credential.helper cache, which stores passwords in your memory. This way stored credentials never touch the disk, and are forgotten after a configurable timeout. To set cache as your git credential helper, run:

git config --global credential.helper cache

Mistakenly, if you commit sensitive data, such as a password or SSH key into dotfiles Git repository, you can remove it from the history. To entirely remove unwanted files from a repository’s history you can use either the git filter-branch command or the BFG Repo-Cleaner (an alternative to git filter-branch) open source tool. You can check out GitHub’s guide on Removing sensitive data from a repository.

I would recommend you to use Passwordstore (pass), the standard Unix password manager. It provides a secure way to encrypt, share, manage, and use private data or passwords. pass makes managing these individual password files extremely easy. All passwords live in ~/.password-store, and pass provides some nice commands for adding, editing, generating, and retrieving passwords. It is a very short and simple shell script. It’s capable of temporarily putting passwords on your clipboard and tracking password changes using git. You can read more about pass here.

Do checkout Keep sensitive data encrypted in dotfiles. Also, check out how to secure your dotfiles.

Using dotfiles through SSH

This section is for those who login often on remote servers using SSH. When you enter into the remote server, your ZSH, plugins, all of your aliases, completions, color schemes, NOTHING is there. Everything set to their default values because your remote shell does not have access back to your local configurations. Terrible?. The solution to this, what I would recommend is to write a script that contains everything you want to put on your remote machine and install there whenever you log in. Keep this script separate from your dotfile installation script because you may not want/need to install everything that is inside your dotfiles repository. Also, because you may not want to slow down your remote server login process. You can also use this SSH wrapper tool called kyrat that allows you to source local dotfiles on an SSH session to a remote host. It works either from/to a Linux or OSX machine.

Building my own dotfiles

I came across a dotfiles repository of someone on GitHub sometime ago, I didn’t know about them before. I have always been a CLI (Command Line Interface) fanatic. I keep changing CLI configs, themes, etc time to time. I have been using iTerm2 with ZSH and oh-my-zsh from long ago. Above everything, I love scripting in general and automating stuff. For the same reason, I love shell scripting. I went through a lot of repositories from various people, but every single one of them seemed to be totally different because again dotfiles are very specific to the individual developer.

My dotfiles contain freshly brewed configuration files for various CLI applications based on macOS. With plenty of useful shell/Git aliases, shell scripts, AppleScripts, and command defaults, etc, it features beautifully customized ZSH and iTerm2 environments and a lot more stuff.

jogendra/dotfiles

When I was looking for a way to organize my dotfiles, I found Zach Holman’s dotfiles way of organizing the dotfiles is the best which is called Topical organization which is organizing the different parts of dotfiles in directories, each entitled to a specific subject. By topical organization, all AppleScripts go inside the AppleScript/ directory, git settings are in a git/ directory, and so on. Everything’s built around topic areas. If you’re adding a new area to your forked dotfiles — say, “vscode” — you can simply add a vscode directory and put files in there. Anything with an extension of .zsh will get automatically included in your shell. Anything with an extension of .symlink will get symlinked without extension into $HOME when you run installers/bootstrap.

There are a few special files in the hierarchy:

bin/: Anything in bin/ will get added to your $PATH and be made available everywhere.
topic/*.zsh: Any files ending in .zsh get loaded into your environment.
topic/path.zsh: Any file named path.zsh is loaded first and is expected to set up $PATH or similar.
topic/completion.zsh: Any file named completion.zsh is loaded last and is expected to set up autocomplete.
topic/install.sh: Any file named install.sh is executed when you run installers/install. To avoid being loaded automatically, its extension is .sh, not .zsh.
topic/*.symlink: Any file ending in *.symlink gets symlinked into your $HOME. This is so you can keep all of those versions in your dotfiles but still keep those autoloaded files in your home directory. These get symlinked in when you run installers/bootstrap.

The Components

AppleScripts

AppleScript is a scripting language developed by Apple to help people automate their work processes on the MacOS. AppleScript is an extremely simple, almost English-like language, but automation it does is pure gold. I sometimes write AppleScripts to automate stuff on my mac where it involves a lot of clicks or similar and I use them using shell aliases. Here is a simple AppleScript that I wrote to open iTerm2 tabs with right directory for all work-related projects.

property examplePath1 : "~/Projects/pathto/directory1"
property examplePath2 : "~/Projects/pathto/directory2"
property examplePath3 : "~/Projects/pathto/directory3"
property pathList : {examplePath1, examplePath2, examplePath3}
 
on run_iterm()
   tell application "iTerm"
       set newWindow to current window
       -- if you want to open repositories in new window
       -- uncomment the line below and comment linne above
       -- set newWindow to (create window with default profile)
       tell current session of newWindow
           repeat with path in pathList
               tell newWindow
                   create tab with default profile
               end tell
               write text "cd " & path
           end repeat
           delay 0.6
           select first tab of newWindow
       end tell
   end tell
end run_iterm
 
if application "iTerm" is running then
   run_iterm()
else
   activate application "iTerm"
   run_iterm()
end if

I simply use it with a shell alias:

alias workinit="osascript ~/dotfiles/AppleScripts/work_init.scpt"

I discovered AppleScript very recently. I will be writing a lot more of them and automate the stuff.

Homebrew and Homebrew Cask

Homebrew is very essential for machines running macOS. It helps you install packages and tools in an easy way through the CLI. Homebrew can also help install your apps. You won’t need to manually download and install packages and tools anymore. Homebrew Cask has the power to install GUI applications in macOS from the command line.

brew cask install iterm2
brew cask install charles
brew cask install firefox
brew cask install google-chrome
brew cask install spotify

Homebrew does not support downloading applications from the App Store. To install App Store apps using CLI, you can use a tool called mas.

My brew/ contains an install script that firstly checks whether homebrew is already installed or not. If not, download it otherwise get to next part. Next, I have listed some essential brews and casks that I use in my day to day dev life, which will be installed. And at last, it runs update and up-gradation following by cleanup.

#!/usr/bin/env bash

# Abort on error
set -e

echo "Checking if Homebrew is already installed..."; 

# Checks if Homebrew is installed
if test ! $(which brew); then
  echo "Installing Homebrew...";
  yes | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
else
  echo "Homebrew is already installed...";
fi

# Install the essential brews
brew install carthage
brew install cocoapods
brew install gettext
brew install gh
brew install git
brew install node
brew install lazygit
brew install lsd
brew install tree
brew install yarn
brew install zsh
brew install zsh-completions
brew install neovim
brew install pass
brew install vim

# Install essential casks
brew cask install iterm2
brew cask install charles
brew cask install firefox

# Update and Upgrade
echo "Updating and upgrading Homebrew..."; echo;
yes | brew update
yes | brew upgrade

# Remove outdated versions from the cellar
brew cleanup

Git Configurations

My git/ contains .gitconfig and some bash scripts related to git. I hate the idea of creating short aliases for every single basic git commands like ga for git add ., gc for git commit etc. They create confusion instead of saving time. I use git aliases for little longer git commands or git processes that involve more than two series of commands. I simply put them in a bash file and use them as aliases. You can simply use them according to your convenience. I have hardlinked my dotfiles .gitconfig with my system’s global .gitconfig. They are hardlinked so that I can use the same in my other systems.

A symbolic (symlink) or soft link is an actual link to the original file, whereas a hard link is a mirror copy of the original file. If you delete the original file, the soft link has no value, because it points to a non-existent file, symlinked file will be useless. But in the case of hard link, it is entirely opposite. Even if you delete the original file, the hard link will still has the data of the original file. Because hard link acts as a mirror copy of the original file. In other words, indode number for soft linked files are different (point to different inode) but on the other hand inode number for hard linked files are same (point to same inode). In unix-like systems, Inode is a data-structure that represents a file or a directory. An Inode number is a unique number given to an inode.

You can simply create a hard link by running:

ln ~/.gitconfig gitconfig

OR if you want to create a soft link instead of a hard link, just use -s option.

ln -s ~/.gitconfig gitconfig

You can do the same for other git configuration files like .gitignore, .gitattributes etc.

Please be careful before putting any sensitive data into git configs files that you are going to put public on GitHub. You can refer to Securing the dotfiles section of this blog.

My .gitconfig look like this:

[user]
	name = jogendra
	email = [email protected]

[mergetool]
	keepBackup = false

[alias]
	parent = rev-parse --abbrev-ref --symbolic-full-name @{u}
	last = log -1 HEAD
	unstage = reset HEAD --
	pr = !sh ~/dotfiles/git/pull_request.sh
	remotes = remote -v
	syncu = !sh ~/dotfiles/git/sync_with_upstream.sh
	diffall = !sh ~/dotfiles/git/git_unpushed.sh
	plog = !sh ~/dotfiles/git/plog.sh
	lazy = !lazygit
	contributors = shortlog --summary --numbered

[color]
	diff = auto
	status = auto
	branch = auto
	ui = true

[commit]
	gpgsign = false

[core]
	editor = vim
	excludesfile = ~/.gitignore
	
[credential]
	helper = osxkeychain

ZSH and OH-MY-ZSH

Command-line is arguably one of the most important tools for any power user, so configuring it in the right way is really important. I prefer Z Shell over any other shell. I am using Z Shell from last almost 3 years now and did not found a reason to use another shell. I used to use Bash before that. Zsh is a powerful shell that features some great improvements over Bash like autocompletion, shared command history, themeable prompts, and a lot more. From the customizations perspective, no one can replace ZSH. There are many ZSH configuration frameworks available, oh-my-zsh is the most used/popular one. ZSH is also been made default shell for macOS from Catalina. For writing scripts, I prefer Bash over Zsh. You can get more insight into practical differences between Bash and Zsh. Some people also prefer using Fish shell over Bash and Zsh.

oh-my-zsh: Oh-my-zsh is simply amazing. Without it, it is difficult to customize/configure ZSH. Oh-My-Zsh is wildly adopted, has a strong community, and a great range of features. I use Oh-My-Zsh with Powerlevel10k theme. My favorite thing about Powerlevel10k is its Powerlevel9k compatibility. I use a lot of Powerlevel9k customizations on Powerlevel10k and source them in zshrc. The minimal theme is also nice to use.

My zsh/ contains zshrc which I kept very clean by putting similar thighs into different files eg. all aliases into aliases file, configurations in config file, powerlevel9k customizations in powerlevel9k file and so on, and just sourced them into zshrc. Neat. Dotfiles zshrc is hardlinked with system’s zshrc.

# Load: Configurations
source $HOME/dotfiles/zsh/config

# Load: Plugins
source $HOME/dotfiles/zsh/plugins

# Load: OH-MY-ZSH
source $ZSH/oh-my-zsh.sh

# Load: POWERLINE
source $HOME/dotfiles/zsh/powerlevel9k

# Load: ALIASES
source $HOME/dotfiles/zsh/aliases

Looks very simple and clean? But with source command, it imports and executes a lot of stuff in it and they are loaded into your shell environment before you use them. zshrc is loaded and executed before you start your terminal. source is a shell built-in command which is used to read and execute the content of a file, passed as an argument in the current shell script.

macOS Preferences

A lot of macOS settings can directly be set from the command line. Preference and configuration files in macOS use property lists (plists) to specify the attributes, or properties, of an app or process. macOS comes with a defaults command-line interface that lets you read, write, and delete macOS user defaults.

Mathias Bynens dotfiles repository has a lot of macOS defaults listed, I just picked some of the defaults that I found useful. Here’s how it look like some of them:

# Free the Dock
defaults write com.apple.Dock size-immutable -bool no; killall Dock

# Remove the auto-hiding Dock delay
defaults write com.apple.Dock autohide-delay -float 0

# Remove the animation when hiding/showing the Dock
defaults write com.apple.Dock autohide-time-modifier -float 0

# Set the icon size of Dock items
defaults write com.apple.Dock tilesize -int 28

# Disable press-and-hold for keys in favor of key repeat
defaults write NSGlobalDomain ApplePressAndHoldEnabled -bool false

To apply the macOS defaults, you can simply run:

Source ~/.dotfiles/macos/settings

Similarly, I have some of the defaults specific to Xcode only are inside xcode/.

iTerm Configurations

iTerm2 + Zsh + Oh-my-zsh = :sparkling_heart:

My iTerm2/ contains Default.json which is configurations for iTerm2’s Default profile that includes color schemes, Normal Font (I use JetBrainsMono), Non Ascii Font (I use MesloLGSNer) and lot more. A profile can be imported or can be saved as JSON from iTerm2 > Preferences > Selecting Profile name > Clicking Other Actions.

Installation Script

To configure another system of your with your remote dotfiles, you need an installation script that does all the installations and syncing process for you.

Make sure to check out other people’s scripts for more ideas and inspiration. You can refer to these general-purpose dotfiles utilities that will help you with managing, syncing, and/or installing your dotfiles. Be careful about your installations script, there may already be configurations file like .zshrc, .gitconfig etc. and you may not want to lose/replace.

My dotfiles follow topological structure. Any file ending in *.symlink gets symlinked into $HOME. These get symlinked on running installers/bootstrap. Any file named install.sh is executed on running installers/install. To avoid being loaded automatically, its extension is .sh, not .zsh. dot is a simple script that installs some dependencies, sets macOS defaults, sets Xcode defaults and so on. Tweak this script, and occasionally run dot from time to time to keep the environment fresh and up-to-date.

I will soon be adding vscode and vim configurations.

Some Interesting/Helpful Reads

I hope this post will give you enough push to start with your own dotfiles. Looking forword to your freshly brewed dotfiles. You can reach out to me on LinkedIn in case of anything. Thanks for the read :) Please take care of security of your system (or remote system) and your mental health :sparkles: :sparkles:

How to use multiple GitHub accounts on single machine

Sun, 05 Apr 2020 00:00:00 +0000

Most of us have multiple (mostly two) GitHub accounts, personal and work account. You need to have the ability to push and pull to multiple accounts. This post is about how to setup and use them on a single machine using HTTPS or SSH.

Note: The instructions below have all been executed on macOS and should work fine on all Unix based operating systems.

Using HTTPS

Step 1: Change remote URL

git remote set-url <remote-name> https://<username>@github.com/<username>/<repo-name>.git

If you are setting-up new remote:

git remote add <remote-name> https://<username>@github.com/<username>/<repo-name>.git

Step 2: Update git config

By default, git use a system-wide configuration file (global config file) or the one stored at top of your home directory to pick your username and email. To ensure that the commits appear as performed by correct username, you have to setup the user.name and user.email for project, too:

git config user.name <username>
git config user.email <[email protected]>

Every git repository has a hidden .git folder (dotfile) which stores all of git related information. You can always check the username and email for a particular project.

open .git/config // check [user] section for email and username

You are good to go now!

git push <remote> <branch>

Entering this, terminal will ask your GitHub account password (once). If it is asking for password each time you push commit, you can cache them using git credential store:

git config credential.helper store

Using this helper will store your passwords unencrypted on disk, protected only by filesystem permissions. This command stores credentials indefinitely on disk for use by future Git programs.

Using SSH

Step 1: Generate new SSH Keys

Before generating new SSH keys, check for existing SSH keys. To list existing ssh keys, go to the terminal, run command ls -al ~/.ssh, files with extension .pub are your SSH keys. You need to have ssh keys for each account. If you are planning to use two accounts personal and work, there should be two SSH keys, if not, you have to generate them.

If you see No such file or directory after running ls -al ~/.ssh command, go ahead and create ~/.ssh directory with command mkdir -p ~/.ssh.

Generate SSH key for Work account

To generate a new SSH key, go to terminal and run the command:

ssh-keygen -t rsa -C <work-email>

To get the email associated with your work account:

Go to GitHub
Log in to your work account
Navigate to Settings
Copy the associated email

On running the command, you will see:

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/<current user>/.ssh/id_rsa):

Enter file name /Users/<current-user>/.ssh/id_rsa_work. Default will be id_rsa. But to differentiate between work and personal, use id_rsa_work_ and id_rsa_personal. After entering the key file name, you will be asked for entering passphrase.

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

A passphrase is similar to a password. The purpose of the passphrase is usually to encrypt the private key. This makes the key file by itself useless to an attacker.

Generate SSH key for Personal account

Follow the same steps as generating an SSH key for the work account. Save the key file as id_rsa_personal.

After generating SSH keys for both work and personal account, if you enter ls -al ~/.ssh, you will see list of your keys as below:

-rw-------   1 <current-user>  staff  2655 Apr  5 02:18 id_rsa_work
-rw-r--r--   1 <current-user>  staff   579 Apr  5 02:18 id_rsa_work.pub
-rw-------   1 <current-user>  staff  2655 Apr  5 02:11 id_rsa_personal
-rw-r--r--   1 <current-user>  staff   571 Apr  5 02:11 id_rsa_personal.pub

id_rsa_work.pub and id_rsa_personal.pub are your public SSH keys. id_rsa_work and id_rsa_personal (keys without .pub extension) are private keys. SSH keys always come in twos. The private key is stored on the client (your machine). The public key is stored on the remote machine. When you makes an attempt to connect to a remote machine (GitHub here but true in general) via SSH, the SSH protocol will check your computer for the private key that matches the public key stored on the remote machine. If they matches, the connection is successful.

Step 2: Add generated SSH Keys to GitHub accounts

For Work account

Copy your work account SSh key to machine clipboard with command:

pbcopy < ~/.ssh/id_rsa_work.pub

To associate SSH key with GitHub account:

Go to GitHub
Login to your work account
Navigate to Settings
Go to SSH and GPG Keys section from the sidebar
Click on New SSH Key button
Paste key in Key text field.

You will most likely receive a mail from GitHub that a new public key is added to your account.

For Personal account

Use key id_rsa_personal and follow the same step as work account for personal account.

Step 3: Update git global configuration

Ignore this step if you are going for Step 4

Git global configuration file should be aware of all of your GitHub accounts. Run this command to edit the global config file:

git config --global --edit

Config file will open in vim, enter i for insert mode and enter:

[work]
  name = <work github username>
  email = <work email>
[personal]
  name = <personal github username>
  email = <personal email>

Press esc and :wq to exit the insert mode in vim.

Now, whenever you will be pulling or pushing, you will be asked which account should be used for this repositopry (once only) and the local config file (repository level) will remember the account.

Important: Make sure you’re using SSH instead of HTTPS as remote URL:

git remote set-url <remote-name> [email protected]:<username>/<repo-name>.git

If you are setting-up new remote:

git remote add <remote-name> [email protected]:<username>/<repo-name>.git

Now, you are all set to use multiple GitHub accounts on your machine!

Further, feel free to use SSH configuration rules explanined below if you find them more handy.

Step 4: Add SSH configuration rules [OPTIONAL]

Register new SSH keys

Before configuring rules, register the new SSH Keys with the ssh-agent. Open the terminal and run:

ssh-add ~/.ssh/id_rsa_work
ssh-add ~/.ssh/id_rsa_personal

If you entered passphrase during generating key process, you will be asked to enter the same here, not otherwise.

Enter passphrase for /Users/<current-user>/.ssh/id_rsa_work:

(same for personal account key)

On success you will see:

Identity added: /Users/<current-user>/.ssh/id_rsa_work (<work-email>)

(same for personal account key)

To make sure if ssh-agent is running, run command eval "$(ssh-agent -s)".

Create SSH Config File and Add Rules

Create new SSH config file by runnning

touch ~/.ssh/config

We need to add SSH config rules for different hosts to specify which identity file to use for which domain. This is way to tell SSH when to use work account and when to use personal account while performing git/github related stuff.

Open newly created config file with command vim ~/.ssh/config. You can choose other editor to edit file if you are not comfortable with vim.

Add rules to config file as below:

# Rule for Work account
Host github.com-work
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_rsa_work

# Rule for Personal account
Host github.com-personal
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_rsa_personal

Test the rules

To check if everything is working fine, create a new test repository on your personal GitHub account and run commands below in terminal:

mkdir TestRepo
cd TestRepo
git init
touch testfile.txt
echo "This is test line" >> testfile.txt
git add testfile.txt
git commit -m "This is test commit"
git remote add origin git@github-personal:<personal-username>/TestRepo.git
git push origin master

Things to be taken care

If you have the repository already cloned update remote URLs like below:

git remote set-url <remote-name> [email protected]:<username>/<repo-name>.git

If you are creating a new repository set remote like below:

git remote add <remote-name> [email protected]:<username>/<repo-name>.git

If you are cloning a repository

git clone [email protected]:<username>/<repo-name>.git

(same for work repositories, use github.com-work)

All set, rest will be taken care by SSH configuration!

Don’t forget to share ^_^

How to write proposal for Google Summer of Code

Mon, 25 Feb 2019 00:00:00 +0000

It worth mentioning that the proposal plays a very big role in selecting in Google Summer of Code. A proposal is basically you describing to your organisation how you would go about the project. Based on this and your credibility, your organisation would contemplate on whether to select you or not. I was Google Summer of Code student in 2018. During the proposal submitting time, I have seen a lot of proposal on the organization chat channels, some are good and some bad. Many people try but some of them get in as there are limited slots in every organization. What stands out the selected student from the student who didn’t get selected is their proposals (there are other factors too). Your proposal should convince the mentors that you’re the right person for the project that can take project to next level.

I did Google Summer of Code 2018 with FOSSASIA and Mentored Google Summer of Code 2019 students. I am sharing my perspective as a mentor, what mentor except in a proposal and what are some things that make you stand out.

What a good proposal contain?

Project Description

Write a small description of the project. It makes sense when you are proposing a new project. Do not copy the project description from the project GitHub page and paste.

Deliverables

You should propose a clear list of deliverables, explaining exactly what you promise to do and what you do not plan to do. You can also include the list of libraries/frameworks/tools which you are planning use for deliverables to make things clear.

Implementation

Implementation is the detailed section of Deliverables. Describe each deliverable in detail, how you are planning to get deliverables done. Write little about the technical things like mentioning libraries/frameworks/tools or including small code snippet or wireframe.

Timeline

In this section, break google summer of code timeline into the small time interval right from the Community Bonding Period right to the Final Submission date and write about what you will be delivered in particular time interval. Be realistic about the timeline, mentors can easily spot unrealistic timelines. You can split the time up into two week periods and described what I would do in each those periods. Find the full program timeline here.

Open Source Contributions

It is also important to mention how much you have contributed to the organization or Open Source in general. You can give links to the Pull Requests you have made or issued you have opened.

Personal Information

Write some important information about yourself. I have mentioned the following info in the proposal:

Name
University
Email
Personal Website
Github Handle
LinkedIn Profile Link
Resume Link
Location
Timezone

About Me

Write down a few sentences about yourself like your coding background, coding projects, internship experience etc which show that you are the strong candidate. Showing that you have already worked on a similar project helps a lot.

Obligations/Schedule Conflicts

Mention about the obligations you will be having during the GSoC period, mention the number of hours in a week you can give to your GSoC project. Mentor understand that you have you may have university classes/exams, they will not mind but mention it to avoid future inconvenience. Most likely many students have exams in the initial period and new semester starting in the final period.

Post GSoC and Future Work

Write a little about the work that will not be delivered during the GSoC period due to the time limit but after GSoC. Mention about how you will be making contributions to the organization after GSoC (coding is not the only thing that matters to organizations).

References

Provide links to the sources you have used in the proposal, it is always a good idea.

PRO TIPS

that’s what you need to know to stand out!

Get your proposal reviewed - It is important to get reviewed your proposal from the project mentor or right person in the organization. Organizations are always looking for the best students, they are always ready to review your proposal. The mentor can tell you what exactly the organization is willing to get done from a particular project in GSoC. You can get the review from the other participating students, friend/senior of you who have done google summer of code in the past. I would suggest you make proposal in a google doc which you can edit anytime. Make sure comments are enabled on the doc. Share the document link on the organization mailing list/channel and ask others to review. You can ping personally too.
Check the Grammar before submitting - Mentors know that students come from very different places and it is not necessary to be proposal in good English, no mentor will mind that but check your punctuation and use a spellchecker like Grammarly.
Submit your draft proposal early - Submit your draft proposal early so that mentor can give their feedback before final submission and ask you questions or request more detail on aspects of your proposal. Google allows you to edit the draft as many times as you wish before the application deadline.
Quality > Quantity - You can submit up to three proposals to one organization or different organizations, it’s up to you but I would suggest you to submit less proposals but make sure they are the best.
Describe your proposal, not project - Use the abstract section to briefly describe your proposal ideas than the project itself. The project in GSoC sense is the actual work you will be doing and not the organization project. Your mentor know very well what your project is.
Be proactive - Mentors are more likely to select students that openly discuss the existing ideas and/or propose their own. It is a bad idea to just submit your idea only on the Google web site without discussing it because it won’t be noticed.
Do not sit back after submitting the proposal - Keep working on the bug fixes, this could influence their decision. Try to learn more about the codebase. Selecting or not selecting is in organization mentor hand but keep working, that’s what is in your hand.
We’re long-term people looking for long-term people - Students that are likely to disappear after GSoC are less likely to be selected. This is because there is no point in developing something that won’t be maintained. And moreover, one scope of GSoC is to bring new developers to the community. Show them that you are long-term people.
Keep it short - Do NOT make a very lengthy proposal, mentors have limited time and many proposals to review. Keep your proposal short and informative. Your lengthy proposal will look like filling space with noise. Keep your proposal DRY (Don’t Repeat Yourself)

Here are my proposals that I submitted to the FOSSASIA organization:

Enhancement to SUSI iOS Project (Accepted)
Phimpme iOS Project (Not Accepted - to be honest, I gave a lot more time making this proposal and did good research than the accepted proposal above. It was a new proposed project. You can see how much it is important to know about the priority of the project for you are going to submit the proposal. Pro tips: contact the mentor earlier, they can tell you what are their priorities and what exactly they are looking for!)

Important Links

Closing Notes

I hope I have provided useful information. Wish you all the best for the Google Summer of Code. Do NOT get demotivated in case your proposal didn’t get selected, Keep doing open source, I am sure you are gonna learn a lot. After all Open Source is Love. In case of any query, you can always reach out to me on twitter OR contact information given on About Me page. You can find my GitHub Profile here.

My Google Summer of Code Project Blogs

Sat, 23 Feb 2019 00:00:00 +0000

I was Google Summer of Code (2018) Student Developer for FOSSASIA. I spend summer working on SUSI.AI iOS project. During GSoC period, I have written weekly blogs about the features implemented by me. You can find all the blogs in links below. These blogs are originally published on FOSSASIA Blogs website.

Connecting SUSI iOS App to SUSI Smart Speaker - August 25, 2018
Adding Support for Playing Youtube Videos in SUSI iOS App - August 21, 2018
Adding Option to Choose Room for SUSI Smart Speaker in iOS App - August 21, 2018
Adding Support for Playing Audio in SUSI iOS App - August 21, 2018
Integrating Gravatar and Anonymizing Email Address in Feedback Section - August 20, 2018
Implementing Five Star Rating UI in SUSI iOS - August 4, 2018
Adding Support for Displaying Images in SUSI iOS - July 29, 2018
Displaying Skills Feedback on SUSI iOS - July 28, 2018
Allowing user to submit ratings for skills in SUSI iOS - July 25, 2018
Change Text-to-Speech Voice Language of SUSI in SUSI iOS - July 24, 2018
STOP action implementation in SUSI iOS - July 21, 2018
How Anonymous Mode is Implemented in SUSI iOS - July 15, 2018
Initial Setups for Connecting SUSI Smart Speaker with iPhone/iPad - June 29, 2018
Post feedback for SUSI Skills in SUSI iOS - June 27, 2018
Creating Onboarding Screens for SUSI iOS - June 8, 2018

Closing Notes

Initially it was hard writing blogs but after writing some blogs, it’s got easier. Google Summer of Code is not all about the code, it is about communication, team work, documentations, scrums, meetups. The GSoC journey was fun indeed. If you have any query regarding my GSoC project or GSoC in general, feel free to reach me out :)

Changing My GitHub Username

Wed, 05 Sep 2018 00:00:00 +0000

Now I have my first name as my GitHub username!

My old username was imjog so I wanted to change it to my first name jogendra but this username was not available (Already taken by someone).

I looked into jogendra profile and found that it was inactive since this profile created (Zero activity). Then I came across Github’s username squatting policy:

GitHub account names are provided on a first-come, first-served basis, and are intended for immediate and active use. Account names may not be inactively held for future use. GitHub account name squatting is prohibited. Inactive accounts may be renamed or removed by GitHub staff at their discretion. Keep in mind that not all activity on GitHub is publicly visible. Staff will not remove or rename any active account.

Immediately clicked the Contact a human button on the page and sent them this request to release jogendra username:

Hi,

I’d like to know if the username jogendra can be released? The user who has registered that username doesn’t seem to have any activity at all (from 2013).

My first name is Jogendra so I’d like to have jogendra as my username. Currently, I own imjog.

Please let me know if this is possible. Would be really awesome if it can be done!

Cheers, Jogendra

GitHub customer service is amazing, I got the reply email from GitHub within 2 hours.

Hey Jogendra,

You are in luck — we have classified the jogendra account as inactive and released the username for you to claim, as per our Name Squatting Policy:

https://help.github.com/

articles/name-squatting-policy

Be quick, as the username is now publicly available!

Cheers, Clark

They released my requested username. Finally, I changed my old username imjog to jogendra.

Now, I have to update my GitHub profile URL wherever I had given and change Remote URLs of local repositories.

Find me on GitHub with my new username here: https://github.com/jogendra

If you ever want to change your GitHub username, this post by Nikhita is very helpful. In fact, I was inspired by this post!

Jogendra

Writing maintainable Go code

Keep main small

Use meaningful names

Code grouping

Write meaningful comments

Don’t repeat

Linting and style guidelines

Avoid deep nesting

Write better functions

Avoid package level state

Return early and use conditions wisely

Use switch more often

Continuous code refactoring

Conclusion

Import Cycles in Golang: How To Deal With Them

Import Cycles

Import Cycles Are Bad Design

:hammer_and_wrench: Debugging Import Cycles

Dealing with Import Cycles

The Interface Way:

The Ugly Way:

Bottom Lines

Implementing Launch at Login Feature in MacOS Apps

Little bit about Apple App Sandboxing

:zap: Initial Setups

:hammer_and_wrench: Adding Helper Target

:gear: Helper Target Configurations

:anger: Cleaning Up Helper Target UI Elements

:electric_plug: Adding Helper to Main Application

Example UI

:link: Helpful Links

:memo: Closing Notes

Using Vim for Go Development

Why do people use Vim?

Let’s GO!

:electric_plug: Vim-Go

Installing vim-go

Auto Completion

Language Server Protocol (LSP) and gopls

:electric_plug: NERDTree

Installation and Setups

Helpful Links

Bottom Lines

Building Command Line Tools in Go

Why Go?

Before we start

Setting up environment variables

Playing with Cobra

Installing Cobra

Let’s get started

Creating our first command

Adding more commands

Implementing Subcommands

Source Code Sturcture

Full source code: jogendra/bookmark-cli

Wrapping up

I do Dotfiles!

:rocket: :sparkles: My dotfiles can be found at jogendra/dotfiles

What are dotfiles?

GitHub Codespaces and Dotfiles

Sharing your dotfiles

Do not blindly copy dotfiles

Securing the dotfiles

Using dotfiles through SSH

Building my own dotfiles

jogendra/dotfiles

The Components

AppleScripts

Homebrew and Homebrew Cask

Git Configurations

ZSH and OH-MY-ZSH

macOS Preferences

iTerm Configurations

Installation Script

Some Interesting/Helpful Reads

How to use multiple GitHub accounts on single machine

Using HTTPS

Step 1: Change remote URL

Step 2: Update git config

Keep `main` small