Why migrate at all

A few things pushed me toward it. A couple of years into the Computer Programming and Analysis program, I’d seen enough tools and tradeoffs that “run a lighter stack” stopped being an abstract idea and turned into an actual plan. NotionNext is a good project. I’ll get into why it stopped working for me, but it’s more machinery than a personal blog needs.

I’d also run out of excuses not to touch it. One of my rules is: if it works, don’t touch it, and that’s exactly why this sat on my todo list for so long. But “I don’t fully understand web app internals yet” was not true for me anymore, and once that excuse is gone, all that’s left is a task I’m avoiding.

And practically, between graduation and the next job I have more free time than I’ll have again for a while, so it made sense to sit with my notes and actually figure out what I’d learned. Getting back into regular blogging needed a platform I’d actually want to open.

I also looked at Hexo and Astro. The short version of why Hugo won is in Building This Blog: it comes down to how content maps to URLs and how each one handles Org-mode.

The longer version is that this year I went through IDEA, VS Code, Neovim, and Emacs for different kinds of work. IDEA is still my favorite for Java: its indexing and language support make everything else feel like it’s guessing. VS Code is the balanced choice once you’re off Java or working on something large; the ecosystem covers file browsing, Markdown rendering, and even reading a PDF without leaving the editor. And since I live in a terminal (WSL as my main environment, so I get fzf, rg, and the Linux tooling that things like Claude Code supported first) right now, Neovim is hard to pass up: it’s light, fast, and everything stays on the keyboard.

None of that is actually why I picked Hugo, though. I picked Hugo because I fell for Emacs. It’s the first tool that gave me what “one unified environment” actually means. The Org mode is the part I like most: think of it as Markdown crossed with a Jupyter notebook. When I want code output sitting inside my notes instead of copy-pasted from a terminal, Org is about the best format for that. Hugo happens to parse Org natively, so the fit was already there before I went looking for it.

Why not just stay on NotionNext

This is the part with real evidence behind it, not just preference:

1. It’s a React app with a long dependency chain.

2. It’s hard-coupled to the Notion API. A major API update once took the whole blog down in one shot, and there was nothing I could do about it on my end.

3. Forking is the wrong shape for this. Maintaining my own fork meant every upstream change was a potential merge conflict and a version-bump decision I didn’t want to make.

4. Error rates I never got to the bottom of. Vercel’s dashboard would occasionally show something like this:

   

5. The deployments themselves were flaky, on top of everything else. A run of “Updated” deploys failing back to back on production isn’t something you want in your history:

   

6. React’s CVE treadmill. Every so often there was a fresh CVE to patch that had nothing to do with anything I’d written:

   

None of that is exotic. It’s just the cost of running someone else’s React app instead of a static site, and I’d paid it long enough.

How I migrated

Getting oriented

I started at Hugo’s own site, found the themes gallery, and looked for something that fit a personal, bilingual blog. PaperMod stood out: MIT licensed, 13.9k GitHub stars, still getting updates, and the demo already looked close to what I wanted without any customization.

From there it was the usual mix: reading the theme’s own docs, skimming its GitHub repo for how people actually configure it, and asking an AI assistant questions that would’ve otherwise cost an evening of trial and error, mostly which config keys are current versus deprecated, and how Hugo’s page bundles are supposed to be laid out.

Actually doing it

The content move itself was mechanical: 45 posts pulled out of a Notion export, cleaned up, and dropped into content/. The interesting part was everything that broke after the content was in place, and none of it showed up until I actually tried to use the feature.

One Issue: oversized record failed the whole deploy

My Algolia push script truncates each post’s content to stay under Algolia’s 10KB per-record limit, but I’d only truncated content, not summary. Hugo builds an automatic summary by grabbing whole content blocks, and one post that opened with a long block produced an 11KB summary. Algolia rejected the record, the push script exited non-zero, and that failed the entire Vercel build: not a partial deploy with one missing search result, a hard stop.

"summary" (.Summary | plainify | truncate 300 "" | htmlUnescape | htmlUnescape)

Cutting over

The old blog was still live on Vercel, wired to www.parkerchenca.com and parkerchenca.com. First I paused that project.

Then it was straightforward: pull the domain off the old project, import the new repo as its own Vercel project, add the environment variables, and point the domain back at the new one. Vercel won’t let the same domain sit on two projects at once, so the order matters.

Comments were the last piece: giscus needed the repository to be public with GitHub Discussions turned on and its own GitHub App installed before it would actually render anything.

And then, boom, it was done. Simpler than I expected, and the environment variables even came out to about half of what NotionNext needed.

Where that leaves things

The blog is live, search works, comments work (I think the light/dark toggle also flips the comment widget now, but I haven’t actually tested it in a browser myself. If you’ve read this far, give it a try and tell me in the comments below ;D ).

Useful links

Hugo:

• https://github.com/adityatelange/hugo-PaperMod
• https://github.com/adityatelange/hugo-PaperMod/wiki

My Blog:

• https://github.com/BHChen24/MyLittleBlog-Hugo/

My original goal for Release 0.4 was to contribute real code to a large open-source project related to finance. I completed that goal by working on Actual Budget, which is a fairly big project with around 23k stars.

Thoughts About the Future

Now that I understand the workflow better, I hope I can eventually try adding a feature or modifying core code in a large codebase. I’m also paying attention to bigger finance-related libraries such as QuantLib, and maybe one day I will be able to contribute there as well.

Overall, I would say I accomplished what I wanted for this release — just not as fully as I expected. But it’s still a good start.

How I Worked Through the Problem

Most of my technical work is understanding the project’s structure and figuring out how to safely fix the type issue. One important thing I learned was that the .d.ts files inside /node_modules/@actual-app/... are not the source code, even though ESLint and TypeScript errors pointed me there.

*.d.ts files for the issue desc

These files only describe the types, so the real fix needed to be applied in the actual source files with the same paths (not totally same).

… And their corresponding original files

Another useful technique I learned was compiling files directly using tsc. By compiling only the files I changed, I could quickly check whether the error was fixed.

But since I had to temporarily update the config to include my test files, it was easy to break something by accident. In this case, I relied on Git to get rid of all temp files and keep the repo clean before submitting the changes (To be honest, creating a totally new test branch is another good idea).

I must mention that, the “fork first, then work separately” workflow we learned in class this semester did help me a looooot for managing my chaotic developing process.

Community, Communication, and the Open Source Mindset

After watching my classmates’ presentations, I realized that mastering a specific language is not the main requirement for open-source contribution. The real skill is always the communication: reading existing discussions, following instructions, asking questions when unsure, and respecting the time of maintainers.

Large projects usually have clear contributing guides, and Actual Budget is no exception. Their documentation explains workflow, expectations, and review rules in detail. As contributors, our responsibility is to follow these instructions first before doing anything else. Good communication keeps the whole project running smoothly; ignoring guidelines only creates extra work for others.

My PR also helped me experience the interaction between contributors and automated tools like Copilot, Coderabbitai, and many other review bots. They gave suggestions and asked for tests. Sometimes I felt a bit frustrated that I couldn’t discuss things with a real human; however, if I can solve the issue with bots alone, I guess it means I did a pretty good job, right…?

Overall, this release helped me understand more about two key concepts of the open source community: communication and respect.

I really enjoy the friendly and efficient communication among the contributors.

🔔 Prelude: Me working with a big project… Wait, me?

Starting the Contribution

This week I finally moved from planning into actually contributing. I decided to work on Actual Budget again, and honestly, I was kinda nervous because this repository has 23.6k stars, real users, and an active core team.

I chose a TypeScript issue related to incompatible type definitions

(https://github.com/actualbudget/actual/issues/6290).

In short, the Query type was missing a few methods and caused type errors inside the API package.

My PR is small and touches only a few lines of code (PR: https://github.com/actualbudget/actual/pull/6331). The challenge was not writing the code only, but understanding what the project expected from contributors.

Understanding the Project and the Rules

Before writing anything, I spent most of my time reading the project structure and the Contributing guide. Actual Budget has an entire website explaining how to participate:

https://actualbudget.org/docs/contributing/

Compared to our previous workflows, the overall process is similar — fork repo, create branch, implement change, send PR. However, the attitude and expectations are much more formal.

The contributing guide explains:

• development workflow
• expectations for PR quality
• how reviews work
• and, very directly, that not every PR will be accepted

“We aren’t going to take every single little change. Don’t be offended if we close your PR…”

So even for a small fix like mine, discussion might still be required, and reviewers could ask for adjustments. It’s more serious, but also very professional.

In addition, I got in touch with yarn in this project, and the project has a set of commands to generate a release note instead of describing PR on GitHub.

The PR Experience

After pushing my code, I first marked it with [WIP]. Soon after, Copilot automatically reviewed the PR and suggested writing tests. That’s kind of strange because when I checked the file, I found there were no dedicated tests at all for that file, so I asked the question directly inside the discussion and waited for a reviewer to reply.

When I removed [WIP], another automated reviewer (coderabbitai) appeared, plus almost 30 checks waiting to finish. Seeing that number made me feel how large and complex this project really is.

So far, the review and discussion are still ongoing.

Final Thoughts

Even though this PR is small, the experience means huge for me. I got to know about how large open-source projects manage quality and how serious review standards can be.

I also feel more confident contributing to large projects now. I’m planning to share more details and personal reflections during Friday’s meeting, and hopefully continue contributing after Release 0.4.

🔔 Prelude: Tough week, and it will get tougher

Planning for the release 0.4

Last week, we wrapped up some final tasks for Release 0.3, and now I’m officially moving into the work for Release 0.4. I mentioned earlier that I was still waiting for my PR for Release 0.3 to be merged. Fortunately, right after the lecture, someone from Opsimate finally reviewed my changes and gave me feedback. The response time was a bit slow, but at least things are moving again.

The real issue, however, is the schedule. The end of the semester is approaching, and last week I was completely occupied with assignments from other courses. Because of that, I didn’t spend as much time exploring Release 0.4 as I had hoped.

The good news is that during Release 0.3, I had already identified a few projects I really wanted to contribute to: My last post. I also spent some time understanding their codebases, so I’m not starting from zero. I’ll talk about those projects below.

My plan is to clear out the most urgent schoolwork first, then fully commit myself to Release 0.4.

Microsoft Qlib

I already finished setting up the environment using pyenv and uv, which allows me to manage Python dependencies very cleanly. I also prepared the example dataset used in the project.

My next step is to go through the latest issues on their GitHub repo and see if there are any that interest me or are suitable for my skill level. Once I choose an issue, I can start analyzing the relevant parts of the code.

I don’t intend to fully understand the entire codebase, because Qlib is large and complex. Instead, I plan to learn the sections that are directly related to the issue I want to work on.

Actual Budget

When I was reading the code earlier, I actually found an approach for solving this issue: https://github.com/actualbudget/actual/issues/6149

However, the problem mainly involves the UI, and the fix probably requires only around ten lines of code(In fact, the existing PR for this issue modifies fewer than 20 lines.) Because of that, I eventually decided not to work on this issue, since it feels too small for Release 0.3.

My next step is to continue exploring the parts of Actual Budget’s codebase that I already understand and look for issues that are more meaningful to contribute to.

One thing I realized while reading the code is that in a well‑designed project, adding a new feature—even a large one—doesn’t necessarily require changing many lines of code. The architecture handles most of the complexity. For an assignment, this might make the contribution look “too small on the surface,” but the real difficulty lies in reading and understanding the existing code.

🧳 Summary

In my current plan for Release 0.4, I expect to focus mainly on these two projects. The most difficult part for me right now isn’t the code itself, but managing my time during this extremely busy part of the semester.

I hope everyone in the course has a smooth development process, and I’ll try my best to push forward as well.

🔔 Prelude: Rocket lift off

Answering Main Lab Questions

Originally I had a reflection section for this blog, but my Professor provides some wonderful questions for me to share my experience and thoughts, so, my reflection has been melted into my answers. I hope you can find useful information directly in there.

• Which release tool and package registry did you choose? Provide links to everything you mention.

  • Go has it’s unique release system — basically, if I init my module locally, push to the GitHub, have a right git tag version, and finally click the “Request” on https://pkg.go.dev/example.com/my/module … then, done, I don’t need to handle rest things, the module will be indexed on the official module platform, and anyone should be able to go install my module. So convenience.

• What was the process for creating a release? Be detailed so that other developers could read your blog and get some idea how to do the same.

  • Ok, assume that you already have a “ready-to-go” codebase (you cannot release empty folder)
  • Then, you should use git tag related commands for tagging you current commit (Use git tag --help for help)
  • Next, you should push your commit to GitHub, maybe you have already done that, so, you should push your tag separately to GitHub
  • Don’t forget to change your documentation… I used to notice that my release still shows v0.0.1 for the version flag, which means I have to repeat my work again (depressedly).
  • Finally, you can release your package. I used Go, and put some useful links in the Reference section. If you are also using GO, them can help you make your way.

• What did you learn while doing your release? Did you have any “aha!” moments or get stuck?

  • A lot of “aha!” moments, actually.
  • Go’s release workflow feels almost suspiciously simple—so simple that sometimes I overthought things.
  • The biggest challenge wasn’t complexity but the danger of skipping steps because the process looked too easy.
  • You can find more of my “aha!” moments in the detailed experience I describe below.

• How much did you have to alter your code, files, build, etc. to use the chosen package format and registry?

  • I didn’t need to change my code structure at all (But actually, I still need to change the documents).
  • Go’s build system is easy, clean and straightforward. I think this is one of the reasons many developers love Go — compared to languages like C++, incremental builds and direct code fetching “just work.” (Disclaimer: I also really like C++.)
  • One thing to be careful about is that git tags must follow the vX.X.X format, such as v1.0.1. Otherwise, the Go package platform may fail to recognize the version or cause unexpected issues.

• How did the User Testing session with your partner go? Describe what it was like, where they got stuck, and how you corrected the problems.

  • Before the session, I tested installation myself on my Raspberry Pi.
  • Interestingly, because my package URL is https://pkg.go.dev/github.com/BHChen24/repo2context, the default installed binary is named repo2context, not the short alias r2c that I used throughout my documentation.
  • This confused both me at first — I couldn’t find the installed executable because I was searching for r2c.
  • To avoid further confusion, I updated my README to explicitly mention this and show how to rename the binary if users prefer a shorter command.
  • Still waiting for feedbacks from my partners

• How do users install and use your project now that it has been released? Provide links and some instructions.

  • I have provided full installation instructions in my README:

  ## Installation
  
  ### Prerequisites
  
  - [Go](https://go.dev/) installed on your system
  
  ### Quick Install
  
  ```bash
  go install github.com/BHChen24/repo2context@latest
  

  This installs the binary as repo2context to your $GOPATH/bin (or $HOME/go/bin by default).

  Add Go bin to PATH (if not already configured):

  Linux/macOS:

  # For bash
  echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc && source ~/.bashrc
  
  # For zsh
  echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.zshrc && source ~/.zshrc
  

  Windows (PowerShell as Administrator):

  [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\go\bin", "User")
  

  Then restart your terminal.

  # Verify installation
  repo2context --version
  
  # (Optional) Rename to shorter command
  mv ~/go/bin/repo2context ~/go/bin/r2c
  

  
  I found once my app is released on the go pkg platform, all these instructions also appear on the home page, which is really cool and convenient. I put it again here for you to quickly navigate: [https://pkg.go.dev/github.com/BHChen24/repo2context](https://pkg.go.dev/github.com/BHChen24/repo2context)
  

References

• https://pkg.go.dev/about#adding-a-package
• https://semver.org/

🔔 Prelude: Bugs in the middle of the way

OpsiMate bugs fixing

During the development of the new Coralogix integration, I ended up discovering two UI bugs — because of course things like this always happen, right?

1. The first issue was a missing icon. This one was extremely small: a one‑line fix in a single file. Honestly the PR felt almost too tiny.
2. Fortunately, another bug appeared at exactly the right time. This one involved a UI element that refused to trigger properly, which required a bit more investigation and work.

Missing dog

1. In my first blog post, I mentioned that OpsiMate includes a DataDog integration. Ironically, the dog went missing

   

   Where is the dog?

2. I attached the screenshot directly to the issue. It more or less explains the entire situation by itself https://github.com/OpsiMate/OpsiMate/issues/557.

3. I wasn’t sure if I had to follow the full issue template… describing such a simple visual bug felt also a little bit painful.

4. The fix was straightforward, and again, a screenshot was enough to show the completed result: https://github.com/OpsiMate/OpsiMate/pull/560

   

   Doggy is back!

Indifference button

1. The other issue was a button labeled “Add Provider” that refused to open the sidebar.

2. While researching good tools for recording UI interactions, I discovered ScreenToGif: https://github.com/NickeManarin/ScreenToGif . It turned out to be incredibly useful, and I used it to record a small gif video and attach it to the issue.

   

   So easy for using

3. You can see the lively demonstration right in the issue: https://github.com/OpsiMate/OpsiMate/issues/558. It’s one of those situations that is very hard to explain clearly with text alone.

   

   Wow I can also insert it here!

4. The root cause was improper state management. Once I identified which component and function were supposed to be triggered, the fix itself was not too difficult.

Reflects

Overall, even when you focus on a single PR, bugs still have a way of appearing continuously (sadly). There’s never a shortage of issues to work on — you don’t have to worry about “running out” of them.

🔔 Prelude: API document reading — totally as hell

Coralogix Integration

What is it?

According to the official description, Coralogix provides “real-time insights and trend analysis for logs, metrics, and security data with no reliance on storage or indexing.”

In simpler terms, it is essentially a real-time server monitoring and observability service. Coralogix helps track logs, visualize metrics, and detect anomalies without requiring developers to manage complex storage systems. For projects with active deployments, this kind of integration makes debugging and performance monitoring much easier.

Coralogix’s Main Dashboard

My main task is to first fetch all the dashboards’ information to support further features.

Challenges

1. Reading the API documentation turned out to be much harder than I expected. As shown in the screenshot：

   

   API Docs

   The example on the API usage page points to https://api.coralogix.com/. However, when I used this endpoint, I didn’t receive any meaningful response—only an API key permission error.

2. I went back to the dashboard and expanded my API key permissions all the way to the admin, but the error still appeared. That was when things started feeling really strange.

3. Since the issue clearly wasn’t about permissions, I began to suspect the endpoint itself. It didn’t make much sense that everyone would use the same entry point. So I spent a long time digging around the documentation… and eventually found the endpoint control page: https://coralogix.com/docs/integrations/coralogix-endpoints/

   

   End Point demonstration

4. I was a bit frustrated — why wasn’t this mentioned anywhere on the main API page? And because the service is still relatively new, there is almost no discussion online; even AI tools didn’t help much. Honestly, I think it was part luck and part persistence that led me to the correct page. Otherwise, I would have wasted much more time.

5. By the way… there are also outdated API references still visible in the docs

   

   Huh?

   which makes things even more confusing.

6. Through this experience, I realized how important high-quality developer documentation is…

Fixing

1. To implement the new feature, I mostly referenced another integration in the project : https://github.com/OpsiMate/OpsiMate/blob/main/apps/server/src/bl/integrations/integration-connector/datadog-integration-connector.ts.

   Their implementation was very clean, so I could follow the structure and focus mainly on handling the data — the request and response parts.

2. And although the Coralogix documentation has some organization issues, the API page itself is straightforward. It clearly shows the response format, and the examples are easy to follow:

   

   A clear API response

   This made writing the actual code much easier.

3. Apart from the time I spent searching for the correct endpoint, the actual development process was quite enjoyable. Nothing beats the satisfaction of running a curl command and finally seeing the server return the correct data.

🔔 Prelude: I have a bad feeling about this: once again, I find myself stuck trying to choose the right project.

Main Content

Still WIP

At the end of this week, I haven’t submitted my first PR yet. Most of my time went into searching for a suitable open‑source project, and my plan is to update this post again after I finally publish my first PR.

Since I previously mentioned that I want to contribute to a repo related to $finance$🤑, I spent a good amount of time exploring that topic. Here are some projects currently on my list:

AI-powered investment platform

Microsoft Qlib (https://github.com/microsoft/qlib)

Qlib describes itself as “an AI‑oriented quantitative investment platform,” but in simpler words, it’s a framework that provides data tools, modeling support, and workflow automation to help build AI‑driven quantitative trading strategies.

• I’m personally very interested in this project and have already started exploring it. The development activity is not bad — issues and PRs are still being handled as recently as this week.
• It uses Python, has plenty of issues to choose from, focuses on a hot topic (AI), and the documentation is fairly complete.
• But…I spent an entire afternoon debugging my Python environment. Absolutely terrifying.

Open‑source banking system

Apache Fineract (https://github.com/apache/fineract)

• This is an open‑source banking system written in Java. I feel that its tech stack aligns well with what employers in the industry expect. If I can learn its design principles and make meaningful contributions, it could be very helpful for my future job search.
• However, the repo doesn’t have a typical Issues section, and its contribution rules seem quite different. I might need extra time to figure out how to get started.
• Still, this is the project I’m currently most interested in.

Personal-finance app

Actual Budget (https://github.com/actualbudget/actual)

• This personal finance platform is super active: around 30 PRs were handled within just a week, and it has around 23k stars. Clearly a very popular project.
• It mainly uses TypeScript and focuses on “practical frontend” features. The demo isn’t such fancy, but the features look solid and well‑built.
• It doesn’t feel “technically fancy” or groundbreaking, but it solves real problems — exactly the type of project I care about and would like to contribute to.

🧳 Summary

Overall, I’m still in the process of selecting the right project and diving into the code, but I’m getting closer. Hopefully I can finally report back with my first PR on weekend.

Updates

Over the past several days, a few things happened that changed the direction of my work.

1. At first, I planned to continue exploring Qlib. However, when I tried to set up the environment, uv and pyenv ended up conflicting with each other again.
2. I spent additional time rebuilding a clean environment, but unexpectedly, Python packages started throwing compilation errors—some of them simply refused to build.
3. At that point, I felt I had already invested too much time just dealing with environment issues. So I decided to switch back to a project I’m more familiar with: OpsiMate (https://github.com/OpsiMate/OpsiMate ), which I worked on during release 0.2.
4. While reviewing feature requests, I found an issue that has not been implemented yet: https://github.com/OpsiMate/OpsiMate/issues/94 . It’s new, has reference implementations, and involves a reasonable amount of work. It felt like the right fit, so I decided to focus my efforts on contributing to OpsiMate.

🔔 Prelude: Another helpful hand, and more

Main Content

This week I worked on GtHub Actions CI for my Go project, added a Go linter, and wrote tests for a partner’s repository. The lab overlapped with my Cloud Computing (CCP) course, so the CI work fit well with what I’m learning there.

Reflections

• I’m also taking CCP, so CI-related tasks felt practical.
• I had already added CI in a previous lab (I thought “why not?” while I was adding tests), so I extended that work here.
• Adding a Go linter was new to me (I know the eslint), but following the golangci-lint repo made it straightforward.

Answering questions

How did you set up your GitHub Actions CI Workflow? What did the YAML for this workflow look like?

I searched “How can I set up my GitHub Actions CI Workflow?”, as just same as the question title. Then, I found a Go workflow templates by clicking the action button in GitHub. The workflow builds and tests on push and pull requests to main and dev. Super straightforward again.

Template YAML:

name: Go
on:
  push:
    branches: [ "main", "dev" ]
  pull_request:
    branches: [ "main", "dev" ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: '1.25.1'
    - name: Build
      run: go build -v ./...
    - name: Test
      run: go test -v ./...

How did your partner’s repo and testing setup differ from yours? What was it like writing tests for a project you didn’t create?

My partner’s repo did not initially have CI now(I will check again later). They did provide example tests, which helped me a lot. Writing tests for someone else feels just like writing a feature, but you must understand more about the intended behavior before you can test it well.

What do you think of CI now that you’ve set it up for yourself?

• CI acts as an automatic safety layer — it finds flaws before the changes are really applied to the main (or other danger zone).
• It saves manual steps: every push triggers the same checks.
• CI is also flexible: you can configure testing closer to the real deployment environment, which local runs can’t always match.

If you did the optional challenges, talk about how that went and what you learned.

I added golangci-lint via GitHub Action (the repo/documentation has a ready template). Check their repo and instruction: https://github.com/golangci/golangci-lint-action

I was surprised when I found they actually have provided “ready-to-use” config lines that allow me to copy and paste and then run everything correctly.

Lesson: read official docs and search the marketplace before creating the wheel — many reusable actions already exist.

🔔 Prelude: Code everywhere, tests everywhere, tokens everywhere, budget nowhere

Main Content

Testing commit:

https://github.com/BHChen24/repo2context/pull/36/commits

Answering Lab Questions

• Which testing framework/tools did you choose? Why did you choose them? Provide links to each tool and briefly introduce them.
  • Since I my project is written by Go, so I just use the go test for testing: https://pkg.go.dev/testing
  • As described on the official page, it “provides support for automated testing of Go packages.” It’s also a part of the standard library, so it can be used directly when the Go environment is set.
  • At the beginning, I put the test files in another folder just like what I used to do with Typescript testing, but then I found it’s better to just place them beside the source code as a standard way in Go projects.
  • Use go test [target folder/file] to run tests, and use go test -cover [target] to see the test coverage
• How did you set them up in your project? Be detailed so that other developers could read your blog and get some idea how to do the same.
  • See above~ :)
• What did you learn while writing your test cases? Did you have any “aha!” moments or get stuck?
  • I felt writing tests is painful.
  • I have to consider each possible way to trigger an error, which is literally difficult to cover all the cases - also means I have to fully understand the tested target (mostly functions in Go).
  • Always, when I hand my tests to AI for reviewing, it will give more comprehensive test cases, like missing values, edge cases, input format, etc. I did learned a lot.
  • But I also begin to doubt that I can really memorize all useful cases. There are at least 10 to 15 cases for each function, even though there are some common cases I can reuse.
  • Maybe a test cases document is the truly practical tool for the testing.
  • I also made good use of “given-when-then” pattern for writing the tests. (See https://github.com/BHChen24/repo2context/blob/main/pkg/scanner/scanner_test.go) It’s super helpful for planning the test process.
• Did your tests uncover any interesting bugs or edge cases?
  • No for this time. But I am curious about why I didn’t find any bugs… Maybe more tests will reveal some, or I need more time to review my tests.
• What did you learn from this process? Had you ever done testing before? Do you think you’ll do testing on projects in the future?
  • Actually I have done the tests in the Lab6 (See https://github.com/BHChen24/repo2context/blob/main/pkg/tokenCounter/tokenCounter_test.go)
  • At that time, I just simply thought that, “oh, since I will develop a new feature, maybe developing the tests at the same time is a good idea,” and then I created the tests beside it.
  • I think doing the testing is a standard step for developing reliable applications, so I definitely will do that in my future projects.
  • But I am actually feeling weird… Since each test case can be different, I’d like to say I’ve learned a lot from past tests, but for the next test I may still go blank with the new situation… Even though I know how to apply the test pattern, most of the time I still need to find some references to implement the test logic. Is it normal or not?

Experience with Speckit

As the additional content, I’d like to mention the new AI related tool called **Speckit, built by GitHub.**

Speckit installing screen

This week, I tried it on my project and generated some scope-focused documentation for adjusting the AI assistant’s behavior towards my project.

Tldr, it looks good, but it didn’t reach my expectation for budget and left some confusion about how it understands the project context.

Firstly, as a CLI tool, it can generate corresponding commands for popular AI assistant tools such as Claude Code, Codex CLI (I use cursor-agent cli), and then, helps you to generate the project documentation. Which means you still have to call the api for creating the docs, and it has a lot of strict rules:

To-do list for generating plans

As you may see, besides the plan, we also have constitution and specify that need to be created before, and then we have tasks to generate, finally implement it.

The full chain is constitution → specify → plan → tasks → implement; they all could be generated or run in the chat box with the AI assistant by slash commands like /speckit.* [your chat content].

The quality of documentation is fantastic, as you have all the practical built-in rules in the speckit:

A lot of .md files

Good project understanding and constitution set up:

Nearly wonderful and comprehensive documentation

And quality checking:

But, the token consumption is also beautiful:

3 million token cost in minutes

At that point it exactly hit me like: for some project this small, Speckit steering the ship was overkill.

In addition, it did help me to create a new branch for implementing new test:

Helpful hand

However, it ignored my git context and named “001-test-xxx” (implicitly pointing to issue 1) the new branch, while I am currently at the “33-add-more-tests” branch. I think it’s just, not perfect, though I still paid a lot of token.

In the end, I found the Speckit is a really practical tool - there’s so much documentation for the AI to follow, that its behavior stays nicely in check (though I still think any AI-generated docs need a human adjust). However, for a small personal project like mine, I haven’t felt a huge payoff yet.

If you are interested, you can also have a try on it in your projects. :>

🔔 Prelude: Journey of open-source contribution

In October, in Hacktoberfest…

What I did

At first, I helped my friend build his open-source project. I introduced him to Hacktoberfest and added issue and PR templates to his project to make it easier for more people to contribute. Project link: https://github.com/TemaDeveloper/library_proj

Then, I found a fun “cat card battle” project on GitHub. I joined it just because it looked interesting - and I love cat pictures. I also noticed that it is a new project created for Hacktoberfest, not too hard, but still meaningful (Not just “add yourself to the Contributors.md”). I contributed code to help the project fetch cat images correctly. Project link: https://github.com/JessieVela/cat-card-battle

My next two PRs were for the OpsiMate project. This project has about 200 stars with a very active open-source community. They even use Slack to make announcements regularly. The reason why I choose this project is after working on two smaller projects, I wanted to join a bigger one that needed more communication and coordination - and OpsiMate was a good match. I unified their eslint and prettier config files, and also helped write some tests. Project link: https://github.com/OpsiMate/OpsiMate

how I’ve progressed

The beginning was difficult. Honestly, the assignment really pushed me to start - because I needed to complete something for the marks. But once I made the first try, I realized most problems were not as hard as I thought.

The hardest part for me was finding the right issues. The hacktoberfest tag and my classmates’ sharing on Teams helped a lot. I also learned a lot about GitHub search. Here’s a document I often used and recommend to others:

https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax

Then came reading and understanding code - or more exactly, understanding the whole structure of a repository. Usually, a repo has many tools like ESLint, pnpm, biome, etc. These tools may not be part of the main logic, but if they are not configured correctly, the project cannot even run, and there is no way to develop and test the project. I once tried a project that I couldn’t make run locally, and I finally had to give up: **https://github.com/BHChen24/flexprice** (If you are interested, you can give it a try.)

Another important part is using soft skills, like time management and communication. Good time management is important. our professor has told us many times not to push all PRs at the last minute. I tried to make a detailed schedule with flexible options. For example, one week I was sick and couldn’t finish my PR by Friday, but I finished it during the weekend. That was the “acceptable case” in my plan. I also had other priority levels and fallback plans, such as contacting the professor if needed. In longer projects, unexpected things can always happen, so it’s important to track progress and prepare alternatives.

About communication - I noticed many open-source contributors communicate in a very casual way. Maybe that’s a community habit. But some comments like “Hey, give me the issue” feel a bit rude to me. I saw that some people spoke like that and then received no reply 😂. So I try to be polite and neutral, and keep my messages short. Being too formal can also confuse others, I think.

I also learned that timely follow-up is important, because not everyone is a full-time open-source developer. For example, when I was debugging in the cat card project, the author only replied after I mentioned them - so if I had stayed silent, nothing would have moved forward.

What I learned

I think my biggest improvement is getting to know how to read code in a better way. Now, when I start working on a project, I know exactly what to check first: read the README.md, look at the repository’s insights ****tab, read the CONTRIBUTE.md file, etc. I also learned how to use good tools when reading code — I always search first, and then use “go to definition/references” to jump precisely to related code. I scroll much less with my mouse now.

I also became more confident using Git. I use Git often in assignments and at my internship, and I’ve learned some useful details. For example, if I publish a branch first and then rebase, the history becomes very messy like spaghetti - and everyone can see it. But if I don’t publish before rebasing, the worst thing is just a local conflict, which I can solve privately. Then when I publish, the history looks clean and is easier for reviewers to follow.

I also gained inspiration on how to build reliable projects by reading clean repositories, like this one: https://github.com/yamadashy/repomix/

Another repo I liked is https://github.com/juspay/hyperswitch . I didn’t have a chance to contribute yet, but it’s a great example of how to build a financial project in Rust, a direction I’m very interested in. I’ll keep following it.

Considerations

I think I made some progress during Hacktoberfest, but this is still just the beginning.

I had planned to contribute to larger projects (with maybe over 2k stars), but due to time, strange build errors, and some unexpected competition, I chose a safer way to meet the requirements of the course first. Still, I really want to contribute to big projects. Some of my classmates have already done that, and after this round of Hacktoberfest, I finally feel confident enough to try it too in the future.

By the way… seeing my avatar appear in the Contributors list makes me feel kind of proud.

🔔 Prelude: We ****need to be tested for sure

In release 0.2 week 4…

What I did

This week I contributed in another issue in the project OpsiMate, - the same one I contributed to last week.

My main task was to add test cases for one of the APIs.

Working on (issue/PR)

Here’s the issue I picked up: https://github.com/OpsiMate/OpsiMate/issues/371

And here’s my pull request: https://github.com/OpsiMate/OpsiMate/pull/537

This issue was a bit of a “legacy” one. Someone had tried working on it before, but their PR was rejected. Another contributor also took it but later unassigned themselves.

When I saw it sitting there for a while, I thought “Why not give it a try?” So I volunteered to take it on. Right now, both the issue and my PR are still waiting for review.

Need to know

The issue focused on writing tests using the Supertest framework, which is quite similar to Vitest. By looking at existing tests in the project, I quickly figured out how to use it.

It was also very helpful to check some closed issues and PRs - there are lots of good examples there.

Difficulties & Fixes

While testing, I actually found a few bugs in the original API code.

It seems the API didn’t have proper try-catch logic, so it couldn’t return the correct response status. Because of that, I had to mention this problem in my PR - basically saying, “Hey, this API might have a bug. It should be fixed before we can finalize the tests.”

I submitted a draft PR temporarily. The maintainers might ask me to fix the bug as well, or maybe just provide more guidance on the tests. Either way, I just need to wait for the review.

Considerations

I’ve seen some test code that doesn’t really “test” anything - it just exists to make the tests pass.

With AI tools becoming more common in development, this problem might get even more serious: AI can help you generate tests quickly, but those tests might only aim to pass instead of really verifying quality (especially when you tell the AI, “Hey, this code doesn’t work!”).

In my experience, my tests did help me discover real issues and hidden bugs, which shows how valuable testing can be - even if it’s sometimes tedious.

Combining AI-assisted coding with good testing practices is definitely an interesting topic worth exploring in the future.

The feature

I implemented the token counting feature inspired by the Repomix project in this lab.

The feature displays the token cost calculated by a specific model align with each file in the file tree. Users can better manage API call budget now. For example:

I also added corresponding tests to ensure reliability.

The development

In the development step, I tried to apply the TDD pattern

To follow it, I wrote the tests first with AI assistance. Tests provided a clear direction for developing, though some tests turned out to be tricky or hard to satisfy (because they are generated by AI… A strict tech leader!)

In the end, I still have to ask AI for help or frequently search my question online… But I think this experience is valuable.

The inspiration

• Directly referring the pattern for applying tiktoken library in Repomix:
  • this.encoding = get_encoding(encodingName); → tke, err := tiktoken.GetEncoding(encoding)
• Writing test to make the feature more robust (just like what Repomix has done)
• The difference, which is also the challenge, is passing text into the new function and handling the output. Due to the project structure, this is totally different from Repomix so I have to review my code again and try to find a best way to integrate the function into my project
  • Then I noticed that I need to do more refactoring work later.

Next step

I want to add more tests for all features in the project. Also, there are more and more lines piling up in the core.go so I may have to refactor most of the code in it (blame the past me) by wrapping more logic into functions.

Other Interesting things..

CodeRabbitAI gave a wrong suggestion for code changing that broke my CI/CD pipeline! (Do not trust AI so hard…)

🔔 Prelude: If I cannot understand the project, how can I write my own code?

Main Content

Introduction of the target feature

The feature I focused on is token counting. This component is responsible for calculating how many tokens a given text input contains.

I ran the **repomix** project locally and got output like below:

Which I think it’s exactly the feature I need for controlling the cost of calling LLM APIs.

Explore the codebase

To understand the implementation, I went through the official documentation and source code of the project.

• Read the official website – This provided a general overview of what the project does and how it can be used.
• Read the GitHub main page –The project is written in TypeScript, and the main repository offers clear descriptions of the project’s capabilities and setup process.
• Read README.md – This basically is the main content of the GitHub page.
• Read package.json – From here, I learned about the project’s dependencies, scripts, and build process.
• Read CONTRIBUTING.md – This document describes how to develop and contribute to the project. While reading, I also noticed that there is an additional instruction file called repomix-instruction.md, which gives more detailed guidelines.
• Build and run locally – After understanding the setup, I built and executed the project on my local machine to test it directly.
• Locate feature implementations – I identified the files where the token counting logic is implemented by:
  • Ask Claude Code – The project provides a CLAUDE.md file with instructions for AI-assisted development.
• Most important file – The core logic resides in src/core/metrics/TokenCounter.ts. Other related implementations can be found by tracing symbol references from this file.
• Read both the main source code and test files – Doing this helped me understand the internal structure and how the feature is being used in different contexts:

The way to understand the project

One challenge was understanding the tiktoken library.

Originally, tiktoken is a Python package, but this project uses its TypeScript implementation. Since my project uses Go, I had to search for a Go version online. I found pkoukk/tiktoken-go, but after reviewing its issues I discovered that a newer maintained fork exists: localit-io/tiktoken-go. I decided to use the newer one.

While exploring the implementation, I also found some hardcoded parameters in Repomix, which indicate the project’s default behavior (as shown in my screenshots):

It wasn’t very difficult to understand the class pattern in TypeScript, since we have already learned similar concepts in our C++ and Java courses.

I also noticed there are many utility (“util”) functions used throughout the code:

As you can see, except for the line this.encoding = ..., most of the other lines are mainly responsible for:

• setting timers for performance testing
• logging the operations

These parts are not the core logic of token counting; they mainly support it by monitoring and recording runtime behavior.

And, it also has a lot of error handling code:

Being able to identify their purposes can reduce the mental load when reading the code.

Learned

The key to understanding a large codebase is to focus on the core business logic first. Identify which parts handle essential functionality, and which are for error handling, performance monitoring, or utility purposes. While those are important, they are not the main focus for my target feature.

In addition, navigating through references is also very helpful for understanding the codebase. I spent some time learning how to use the “Go to Definition / Type Definition / Implementation / References” features in my editor, and once I got used to them, they saved a lot of time by precisely revealing the details I needed to know.

🔔 Prelude: I am one part of a group of a hundred developers?!

In release 0.2 week 3…

What I did

This week I participated in the project that was recommended by my classmates: OpsiMate; it’s truly an active open-source project—once I commented on an issue, there was a contributor to reply to me in time.

I also joined their slack channel and found they even have short but regular reports for community growth, which makes me really feel like I am a part of the project.

Working on (issue/PR)

The issue I worked on is: https://github.com/OpsiMate/OpsiMate/issues/517 and this is the related PR for it: https://github.com/OpsiMate/OpsiMate/pull/521

This issue is about adjusting the project’s linting and formatting configurations. Before, there were several config files in different folders, such as the app server folder, the client folder, and the shared package folder. So one of the main contributors wants to create unified base configs for both the linter and the formatter in order to manage them in a standardized way.

Need to know

After analyzing the codebase, I realized that the project is mainly using eslint.config.js/mjs and .prettierrc as the configuration files. S the first thing I need to figure out is how prettier and eslint reads their configs from specific files.

And, obviously, .prettierrc doesn’t support importing or exporting, so I need to find a way to transit config objects within config files.

Difficulties

It’s not so hard to find the online resources and apply them to create a new base config file that is accepted by prettier. But the eslint configs seem to be more complex.

Furthermore, once the eslint configuration is broken, it will spread out to subdomains and eventually lead to a failed CI/CD workflow (I made one mistake and then there were a huge number of red error messages that freaked me out). So I need to take it more carefully and frequently ask for help.

Fixes

To be honest, the fixings are not so special or awesome; I basically just followed online instructions plus a little bit of my personal experience to accomplish this issue. If I made a mistake, the local IDE tools like SonarQube, eslint and prettier plugin would correct me before making changes; besides, this project applied the CodeRabbitAI for GitHub PR reviewing. I got a lot of useful suggestions for improving my bug-fixing code. Everything just looks like it’s running smoothly and under control.

Considerations

There are a few interesting thoughts I want to mention here but, I don’t know if I should write some super long paragraphs for each of those 😂, so I decide to list them below as bullet points:

• Technically speaking, this is my first time participating in a project that has a public developing community; my first PR was made for my friend, and my second PR was made for a hacktoberfest-specific project (I think. But it still is a fun project!). So I am very exciting for this week’s work.
• Eslint9 doesn’t support extend syntax anymore, but my work was based on a previous version, so I did pay for it with some useless effort. Thankfully I noticed this problem from the code reviewer. Should take more care about the version of developing tools next time.
• Slack seems super useful for communication. It also likes the discord… Maybe I should take some time to learn about it.
• Do not feel afraid of following up on the work. Eventually we should push the process somehow.

🔔 Prelude: Shall we have a talk about the strange issues?

In release 0.2 week 2…

What I did

This week I mainly worked on a small but interesting project: Cat Card battle (https://github.com/JessieVela/cat-card-battle). It’s a web-based game built with Vue and TypeScript, and styled using Tailwind CSS.

Working on (issue/PR)

Early this week, I found a bug that caused some image URLs from The Cat API to redirect to Tumblr’s “content violation” placeholder instead of showing actual cat photos. Like this:

(Also see: https://github.com/JessieVela/cat-card-battle/issues/23)

So I decided to file this bug as an issue, and see if I can be assigned then fix it.

Need to know

I have some experience with the Vue framework, but I needed to review a few of its concepts. Fortunately, the bug didn’t require any functional changes, so I could focus purely on TypeScript logic.

The next thing I needed was to understand how to use The Cat API. Luckily, they provide detailed documentation:

https://developers.thecatapi.com/view-account/ylX4blBYT9FaoVd6OhvR?report=bOoHBz-8t

Difficulties

The main challenge this week was Tumblr’s redirection behavior.

I used the Network tab in DevTools to trace why placeholder images were being returned and where they came from. Eventually, I found that some image requests returned a 301 status code, with a Location header pointing to a placeholder image.

To handle this, I added logic to detect 301 responses and fetch the image again. But strangely, even after refetching, the placeholder problem was still there. This make me wonder that whether I should dig deeper into Tumblr’s API mechanism — though that might have been too complex.

I finally decided that the issue was likely on The Cat API’s side, and it wasn’t worth pursuing further.

Fixes

For the Tumblr image issue, I implemented a simple workaround: temporarily filter out Tumblr-sourced images. If an image source is detected to be from Tumblr, the app simply re-fetches until it gets the required number of images.

Now, all images come from CDN sources, which should theoretically be more stable.

Another challenge was communication.

After submitting the issue, the repository owner didn’t respond, but they did close another issue during that time. I feel a little bit confused about that but also not sure if I should follow up with them.

Since I already submitted a PR, I decided to wait for a while and may reach out to them proactively if there’s still no reply.

Considerations

While handling the Tumblr image issue in the PR, I felt a lot of pain — every attempt to “check and re-fetch” still resulted in placeholder images. Then I realized something: if the goal is simply to solve the problem, a simpler solution works just as well — the source is unreliable, then I can just don’t use it.

Perhaps in practice, solving a problem doesn’t always require overthinking — sometimes the simplest solution is still effective.

🔔 Prelude: Even more powerful commands for version control

Main Content

Write a blog post about the process of refactoring your code.

• What did you focus on in your improvements? How did you fix your code so it would be better in each step?
• How did your interactive rebase go? Did you find any bugs in your code while you did this? Did you break your program while changing things?
• How did it go using Git to change your project’s history?

What did you focus on in your improvements?

I mainly focused on looking for big code blocks to implement my improvements because it has a higher chance of discovering a function that can be exacted. At the same time, I was also looking for a chance to rename some vague variables and add comments to logic.

I used a code quality checking plugin called SonarQube (https://www.sonarsource.com/products/sonarlint/) to find potential issues in my code. Here is the showcase:

As you can see, SonarQube lists its concerns for my codebase. It’s convenient, but if you are also using Go for programming, you must have noticed that: if err != nil is basically inevitable, counting it into the complexity value is meaningless. It’s still a good tool for pre-checking our code though.

How did your interactive rebase go?

Interactive rebase is surprisingly good, plus I found that GitLens (https://www.gitkraken.com/gitlens) provides a pretty UI with the IDE like VS Code.

(Reference: https://www.gitkraken.com/learn/git/problems/git-interactive-rebase)

I don’t need to be too concerned about the looking of the submit tree now because I learned how to rearrange it by “rebase.” Separately creating small commits also makes the workflow clearer when we are developing. But since it will break the branch - specifically, drop some commit histories - we should always use it on our own, personal topic branch (and we’d better know what we are exactly doing).

Since I only made minor changes, I didn’t confront big issues in this lab, but I do have a story to tell in the next section.

How did it go using Git to change your project’s history?

Here is the concise story of using Git in my lab 5:

• I created new branch
• I made changes
• Too smoothly! I finished all 3 targets without making a commit!
• Had to pick the file that need to be committed, and saved others for later commits… Used add
• In the middle of the way, noticed that the names of the local branch and the remote were different! Had to change them… (Then I deleted the remote one first, I don’t know why I did that.)
• Rebase but failed! Since Git couldn’t find the remote branch…
• …

Well you see, even though I finally managed to rebase my branch, the most difficult part still wasn’t applying some Git commands but driving Git well from the very beginning. However, I got to know at least one thing: Git has most of the methods to help you keep the code history safe and operable (again, if you know what you’re doing there).

I feel like I only touched 30%~40% of Git’s usages. It’s definitely worth investing time to learn it well.

🔔 Prelude: Everything’s hard in the beginning

In release 0.2 week 1…

What I did

This week I mainly focused on searching for suitable open source projects to contribute to. I haven’t started submitting any pull requests yet, but I did managed to create an issue (see link below) and am waiting for it to be assigned.

https://github.com/TemaDeveloper/library_proj/issues/17

Working on (issue/PR)

I opened an issue about setting up issue templates for a repository. Although I think it was a simple one, it still was my first time dealing with this topic, so I referred to the official GitHub documentation. I surprisingly learned that using a .yml file for the issue template allows better formatting and a cleaner layout for users filling in issue forms than the .md template.

The process has been updated; please have a check on the “Updated” section in this post

Need to know

Still waiting for feedback or assignment on my issue. Once that’s done, I plan to contribute my first PR to this project or one of the other candidates I’ve found.

Difficulties

The main challenge this week was finding the right project to start with. Some repositories are attractive and popular but have too many contributors already. It’s so hard to find available “good first issues.” in those repos.

Fixes

After rewatching a previously recorded lecture, I realized I had overlooked GitHub’s advanced search feature. By also researching on the GitHub official documentation, I improved my efficiency in locating suitable issues by using no:assignee, etc. I’ve already starred several projects for upcoming work.

Considerations

Some classmates shared potential projects on our team channel, and I found that exchanging ideas and experiences is really helpful. I believe active communication and collaboration will be key to achieving our release goals.

Updated

I have added templates to the repo and The PR has been merged.

https://github.com/TemaDeveloper/library_proj/pull/18

Here are some things I want to share:

1. Even though this PR is simple, it is somehow a little bit tricky. Because the templates will not be applied until the PR has been merged into the main repo (Github needs to read them), I have to create a new test repository in my account to test the templates.
2. And, this testing procedure did cause a bug: I mistakenly placed the templates in .github/workflow/ISSUE_TEMPLATES instead of the correct path .github/ISSUE_TEMPLATES in the original repo. However, in my separated test repo, the path is correct so that it didn’t reflect any issue.
3. So after noticing the PR has been merged and the bug appeared, I still need to communicate with the owner to let him know I will create a new PR to fix the minor bug (https://github.com/TemaDeveloper/library_proj/pull/19). This cost extra time.

This little issue got me thinking about how to handle PRs whose results only show after merging… I’d like to explore this topic further.

🔔 Prelude: PR, code review and communication.

Refelction

First, how did the code itself go?

The Python project I worked with is clean and straightforward. It made me reconsider my tech stack: I may use Python as my primary prototyping language, and only turn to Go, Rust, or C++ when specific requirements demand it.

Did you run into any problems?

Implementing the logic was simple, but writing tests was more difficult. Too many cases could be included!

How did you tackle the work?

I looked up examples online and used some tools to inspire different test cases.

Second, how did it go using git?

Since I’ve been using Git continuously in recent months, I didn’t face major technical issues. The only recurring problem was occasionally forgetting to create a new branch, etc.

Did you find any of it difficult? How did you get around this?

There was a tricky issue: I directly worked on my forked main branch and mentioned the original issue in one of the commit, so, the issue pointed back to my commit on the main branch. It’s a little bit confused because for a new feature I should have a clearly named branch links to the issue.

Luckily, I could still use the correct branch for making the new PR, but the comments are still left in the issue… And I feel like it’s troublesome to change the recorded behavior on Github.

I haven’t found a perfect solution for human-caused fault yet, so I simply try to be more careful. Fortunately, Git and GitHub are well-designed, so there’s usually a way to recover mistakes.

What would you do differently next time? What did you learn from the experience?

In this week’s lab, a couple of tests passed locally but failed on the maintainer’s machine, so weird. I later realized that the issue was due to a mismatch between my local and pushed code.

Through communication we resolved it, but next time I will double-check my final code version. I also learned that consistent CI/CD pipelines and active communication are essential for online code contributing.

🔔 Prelude: Made a lot of mistakes, yet the actual merging process is very smoothly.

Main Content

Project repo: https://github.com/BHChen24/repo2context

Your issues:

https://github.com/BHChen24/repo2context/issues/19

https://github.com/BHChen24/repo2context/issues/20

Your merge commits:

https://github.com/BHChen24/repo2context/commit/c9ae3957f1fa1749659181ba6c0773c1a7c9d0b8

https://github.com/BHChen24/repo2context/commit/4817fc097517a3c6a7daa8bbd7bcd1d02f25e2a3

Reflections:

Discuss what you did, the changes you made for your features, and the process of doing your merges. What problems did you have? What did you learn? What would you do differently next time?

Merging branches

I basically just followed the lab instructions and completed the main assignment, but I need to develop two extra features in separate branches because:

My initial approach was straightforward: create a branch, finish the feature, then make a PR. Since I followed this workflow step-by-step for each feature, I did not encounter any merge conflicts at all.

Later I realized I misunderstood the instructions. I actually need to trigger the merge conflicts by developing features in parallel, and then merging branches back in a line. I managed to develop two more features and did the fast-forward merge and a three-way merge.

Besides, I also filed some issues to reduce the number of function parameters or refine the output format.

Paid more effort due to begin the work so fast.

What I learned

The biggest lesson in this lab was not about the merges themselves but the importance of carefully reading instructions before diving in.

On the positive side of the first two issues (totally no conflicts but not align with the requirement), I confirmed that my personal development process could be good-for-work: open an issue, create a branch, link the issue to the branch commit (using GitHub keywords like fixes #num), then develop step by step.

For solo development this procedure keeps conflicts to a minimum. I will still follow these steps next time.

However, in a collaborative environment, I think the conflicts are inevitable. That makes it essential to understand Git commands deeply and to take advantage of the rich ecosystem of version control tools.

(I also think that so many tools exist is proof that developers have been tortured by merge conflicts for years…)

CodeRabbitAI code review

Surprisingly, I discovered an auto-review tool while I was looking through examples of “how to file a good issue” on open-source projects.

What impressed me most was that tools like CodeRabbitAI can automatically generate a pull request summary, provide next-step suggestions, and even create sequence diagrams based on the code changes in the PR：

The whole report can be auto-generated and triggered by the work-in-process PR!

Here is an example I explored: https://github.com/BHChen24/repo2context/pull/25

🔔 Prelude: This is my first step into building an open‑source style CLI tool in Go.

Release 0.1

Project Description

For this assignment, I built a “Repository Context Packager” tool named repo2context, which can scan a local git repository and generate a single, well-structured text file with repository information optimized for sending to LLMs such as ChatGPT and Gemini.

Technology Choice

• Language: Go (Golang)
• Output format: Markdown
• Why Go?: Although many people are talking about Go’s advantages all the time, my main reason to do this was simply that I wanted to challenge myself.

Implemented Features

Required Features

• Basic CLI interface with --help and --version
• Repository/file analysis
• Path tree structure
• Git commit/branch metadata
• Summary statistics (file count, lines of code)
• Standard streams (stdout for output, stderr for errors)
• Error handling

Optional Features Implemented

1. Gitignore Integration
   • The tool automatically excludes files and directories listed in .gitignore.
   • Provide a --no-gitignore to disable .gitignore filtering
2. Output to File (-o / --output)

   • Users can save the formatted repository context into a file (markdown text).

   • Example:

     toolname . --output context.md
     # usually the toolname is "r2c" but can be built as other names
     

Development Experience

Process

1. Set up GitHub repository
2. Implement CLI argument parsing in Go (with cobra package)
3. Add recursive directory/file reading; Implement project structure tree displaying; tests…
4. Extract Git info (os/exec to run git commands and parse metadata)
5. Get data together and format output
6. Implement the two optional features: .gitignore handling + output to file
7. Also invite classmates to file issues

Challenges

• Git env: Needed to handle different situations like Git may not be available or the repo may not be initialized. (To be honest, I found this type of check should be applied to basically everywhere, and that’s a bit painful handling errors in Go..)
• Starting from scratch: This was my first time writing a full CLI tool in Go, so I had to set up everything from zero — project structure, flags, Git integration, error handling, etc. (Have to do a lot of research)

Learnings

• Learned how to build a demo project from 0 to 0.1 in Go.
• Gained experience reading Git metadata and filtering files dynamically.
• Deepened understanding of how to do file system traversal, file I/O and error handling in Go.

Summary

• Implemented all required features
• Completed 2 optional features
• A not bad foundation for future extensions
• Good start for practicing open-source contribution process

Links

• GitHub Repository: https://github.com/BHChen24/repo2context/

🔔 Prelude: About the process of contributing a code change to another project

🖋️ Main Content

The project repo: https://github.com/RiverDave/rust-cli-tool

Your issue: https://github.com/RiverDave/rust-cli-tool/issues/27

Your pull request: https://github.com/RiverDave/rust-cli-tool/pull/28

1. What I did

Briefly speaking, I did:

• First take a look at the whole project to see the current situation
• Check if the “recent file” feature has been implemented
• Analyze code base to see how to add custom commands
• Search online for obtaining file metadata in certain language
• Raise issue, fork repo, switch branch, develop logics
• Test my code
• Update documentation
• Create PR
• Communicate with repo owner
• Close issue
• Write blog

1.1 The changes I made for my feature

• I found the rust project used clap — a famous and solid Command Line Argument Parser for Rust.

• Thanks for that, I have a very clear pattern to follow then create a new command for the application:

  #[arg(long = "recent")]
  pub recent: bool,
  

  As simple as it looks like!

• Then, I extended the Config struct to include a recent_only field, which controls whether to filter for recent files.

• Next, I create useful logics in the file.rs. The main filtering logic checks if files were modified within the last 7 days — if a file is older than 7 days, it gets skipped.

1.2 The process of getting your work accepted

• First, review the codebase and existing issues to make sure I understand the basics of the project and avoid raising a duplicate issue.
• Then, communicate with the repo owner — by Teams, by issue, by email, or whatever I like (but also must check the comfortable way for the owner first), to say, “hi, can I add a feature to your project, because…” The core of this is to “let them know.”
• During the coding process, we’ll mainly communicate by the issue. I code, they give feedback, I change my code until we are all good for the issue.

2. Technical aspects

2.1 How did file timestamps work in the language you were working with?

https://doc.rust-lang.org/std/fs/struct.Metadata.html#method.modified

According to this file metadata documentation, we have a lot of tools for obtaining info of a file, including the timestamps for the last modified time. Noticed that this method may “not be available on all platforms” so I added some error-handling code to it.

Next, we should also obtain the current system time (https://doc.rust-lang.org/std/time/struct.SystemTime.html#method.now), minus 7 days, then compare these two variables. If the file wasn’t touched in 7 days, it is not a “recent” file.

2.2 What challenges did you face integrating with the existing codebase?

I think there is one main challenge I want to mention: It takes time to understand the project.

I had to trace through the code to see how clap handles commands. Well… Actually I noticed soon that if I follow the coding pattern in the repo then I should be OK to write the new code. Fully understanding the clap is a hard task itself.

And I also need to figure out how the Config struct flows through the application (The really important task) and where the file processing logic lives in file.rs. Reading other people’s code is always slower than writing your own, plus you have to spend a lot of time researching the language that you are not so familiar with.

2.3 In addition…

In the process of collaboration, I do have a question I really want to ask: Should I use AI tools to quickly understand other people’s open-source projects?

Theoretically, feeding an open-source project into an AI shouldn’t pose security or legal issues, because it’s “open-source”; but, the AI technology is still so new (and the legal issues are always tricky) that no one really knows what the hidden costs might be. Even if I let the AI summarize someone else’s project, who can tell if its summary is reliable?

On the other hand, if I try to research and interpret things completely on my own, there’s still a high chance that I’ll make human mistakes. So, whether or not to use AI tools ends up becoming more of a “trade-off” decision to me…

2.4 How did you handle edge cases?

There was an interesting thing I want to mention in testing. So when I implemented my feature and first tested it, I found that the app would output all the files in the target folder, which made me confused. But later I noticed that because:

1. The target folder for testing is one of this project’s folders.
2. When I use git clone to clone the repo to a local place, it also means that I “modified” all the local files in the folder.

So, the “recent” feature will not filter anything out because all the files are “recently” edited. I think this case can be considered an edge case.

My solution is to manually create a recent_test_files folder that contains some old files and some new files, then test the feature on them. This leads to a correct test result and also prevents the application from reading too many unnecessary files at once.

3. If your repo received a pull request…

Haven’t got a PR yet. 😶‍🌫️

🔔 Prelude: Doing cool things with classmates

• How did you go about doing your code reviews? Do you prefer an async or sync approach? Why?

I prefer the async approach to doing the code reviews; it gives me a flexible schedule to handle my work and life. And I feel relaxed when I need to read something alone.

• What was it like testing and reviewing someone else’s code? Did you run into any problems? Did anything surprise you?

Just like learning new concepts! I may know about the programming language, but the ideas from others are always new and valuable to me. I sometimes could not understand the meaning of others’ code, but thankfully, except for directly asking them, we can also leverage AI in these days.

• What was it like having someone test and review your code? Were you surprised by anything?

It’s just like being judged … but I considered it a little bit; in an open-source community, being reviewed by someone is for making the product better, and then I got relief with this thought. The collaborators always surprise me by discovering new bugs and applying new tests in a way that I never thought of before!

• What kind of issues came up in your testing and review? Discuss a few of them in detail.

Well, for example, I got stuck in the middle when I tried to write tests for a C++ project (although I found that I don’t need to actually write them for this lab in the end). It doesn’t mean I don’t know about C++, but I need time to remind myself of how to write tests in C++ because it has been a while since I used C++ to build something. I have to search online for how to write the tests properly and look for examples. When I face some unfamiliar frameworks, testing and review take time.

• Provide links to issues you filed, and summarize what you found

https://github.com/ElshadHu/RepositoryContextManager/issues/3

This is a tricky one because I am not so familiar with CMakefile. When I tried to build the project the system kept showing errors, I had no idea at that time. But I finally found that it was triggered by the hardcoded PATH setting when I truly dove into the file. I want to tell myself, “If you want to fix a bug, don’t just stare at the error prompts, you have to dive into the file!”

All issues I filed should be under the same issues page; here is another repo I filed issues for: https://github.com/RiverDave/rust-cli-tool/issues

• Provide links to issues that were filed on your repo, and what they were about

https://github.com/BHChen24/repo2context/issues/1

And all other issues are under the “issues” page.

I noticed I included a configuration management tool in my project but since I haven’t used it, I didn’t write any comment or mention it in my “README.md”, and this did cause some confusion. Thanks a lot David!

• Were you able to fix all your issues? What was that like?

https://github.com/BHChen24/repo2context/issues/4

For documentation issues, I can, but for some feature requirements and tricky bugs I cannot yet. Actually, I fixed the markdown file syntax error immediately: the embedding link [https://go.dev/](GO) should be like [Go](https://go.dev/) .(And this is the first time I asked copilot to review my code for the PR, wow!)

• What did you learn through the process of doing the testing and reviewing?

It’s definitely a necessary process for improving our products. The key point here is barely anyone can accomplish a high-quality project by working totally alone. In ancient China there is an idiom: “When everybody adds fuel, the flames rise high,” which means, “Great things can be achieved by mass effort.” This is a wonderful description of the meaning of testing and reviewing in the open-source community.

Yes, I am taking the OSD600 course. To be honest, I have been very eager to take this course because many of my friends told me how valuable it is, and I have already felt the power of the open‑source community — I use Linux daily, I hear stories about open‑source projects and people all the time. In addition, I had never really thought too much about how open‑source projects can influence a company’s business before our first OSD600 lecture; that lecture really caught my interest.

I want to be someone who can confidently say “I am able to develop software for real‑world use” after this term, with open‑source contributing experience. I am especially interested in contributing to projects in the finance field, such as high‑precision computation, trading systems, backtesting systems, and so on.

I researched a project on the daily trend page called “everyone-can-use-english.” [https://github.com/ZuodaoTech/everyone-can-use-english/tree/main] Since English is my second language, I often feel I am not good enough at using it. This project provides a way to improve my spoken English by correcting tone and pronunciation. For example, it has a feature called “Pronunciation Assessment,” which allows me to record my speaking and get feedback on whether it is correct, or how it can be improved.

I also noticed that its documentation is not very complete yet, and currently they only provide some demos in Chinese. Maybe these could be potential entry points for making contributions.

🔔 Prelude: With these commands you are able to do most text-related work the same as you are on Windows.

Linux Common Commands

System Management

System Information

# Basic system information
lscpu                                  # Detailed CPU information
uname -a                               # Kernel and architecture info
cat /etc/os-release                    # Distribution information

# Hardware information
lsblk                                  # Block devices
lsusb                                  # USB devices
lspci                                  # PCI devices

Package Management

# dpkg package management
sudo dpkg -i package.deb                           # Install deb package
dpkg -l | grep package_name                        # Search installed packages
dpkg -L package_name                               # List package files
dpkg -S /path/to/file                              # Find which package owns file

Monitoring and Performance

Memory and Disk

# Memory usage
free -h                                # Human readable format
watch -n 1 free -h                     # Real-time monitoring

# Disk usage
df -h                                  # Disk usage
du -sh /path/to/directory              # Directory size
du -h --max-depth=1 | sort -hr         # Sort directories by size
sudo fdisk -l                          # Partition table info

System Monitoring

# Temperature monitoring
vcgencmd measure_temp                   # Raspberry Pi temperature
sensors                                # General temperature sensors
watch -n 1 vcgencmd measure_temp        # Real-time temperature monitoring

# Process monitoring
ps aux                                 # All processes
top                                    # Real-time process monitor
htop                                   # Enhanced top
ps aux --sort=-%mem | head -10         # Sort by memory usage
ps aux --sort=-%cpu | head -10         # Sort by CPU usage

# I/O monitoring
sudo iotop                             # I/O usage
sudo iotop -o                          # Show only processes doing I/O

Network Monitoring

# Connection status
ss -tuln                               # Network connections
ss -a                                  # All connections
ss -tuln | grep :22                    # Specific port

# Traffic monitoring
iftop                                  # Interface traffic (requires installation)
nethogs                               # Traffic by process (requires installation)

Processes and Services

Process Management

# Find processes
pgrep -f "process_name"                # Find process PID
ps aux | grep "process_name"           # Detailed information

# Terminate processes
kill PID                               # Normal termination
kill -9 PID                            # Force termination
pkill "process_name"                   # Terminate by name

Background Jobs

# Background execution
command &                              # Start in background
nohup command &                        # Run without hangup

# Job control
Ctrl + Z                               # Suspend current process
bg                                     # Continue in background
fg                                     # Bring to foreground
jobs                                   # List background jobs

# tmux sessions
tmux new-session -d -s session_name "command"
tmux attach -t session_name

Service Management

# systemd services
systemctl status service_name          # Check status
systemctl start/stop/restart service_name
systemctl enable/disable service_name  # Auto-start on boot

# Log viewing
journalctl -u service_name             # Service logs
journalctl -f                          # Real-time logs
journalctl --since "2 hours ago"       # Time range

Scheduled Tasks

# cron jobs
crontab -e                             # Edit
crontab -l                             # List

# Syntax: minute hour day month weekday command
# 0 2 * * * /home/user/backup.sh      # Run daily at 2 AM
# */10 * * * * /usr/bin/check.sh      # Run every 10 minutes

Network Management

Network Interfaces

# View network interfaces
ip addr show                           # All interfaces
ip a                                   # Short form
ip link show up                        # Enabled interfaces

# Manage interfaces
sudo ip link set eth0 up/down          # Enable/disable interface

# Routing information
ip route show                          # Routing table
ip route | grep default                # Default gateway

WiFi Management

# NetworkManager
nmcli dev wifi list                    # Scan WiFi
nmcli dev wifi connect "SSID" password "password"
nmcli connection show                  # Saved connections

# Traditional tools
iwconfig                               # WiFi interface status

Network Testing

# Connectivity testing
ping google.com
ping -c 4 google.com                   # Limit count
traceroute google.com                  # Path tracing

# Port testing
nc -zv google.com 80                   # Port connectivity
nmap -p 22,80,443 target_host          # Port scanning

# DNS queries
dig google.com                         # DNS lookup
cat /etc/resolv.conf                   # DNS configuration

# Firewall
sudo ufw status                        # Ubuntu firewall status

Files and Text

File Finding

# Find by name
find /path -name "filename"
find . -name "*.txt"                   # By extension
find . -type f -name "*.log"           # Files only
find . -type d -name "temp*"           # Directories only

# Command location
which python3                          # Command location
whereis python3                        # Binary, source, manual

# Fast search
sudo updatedb                          # Update database
locate filename                        # Quick search

Content Search

# Basic search
grep "pattern" file.txt
grep "pattern" *.txt                   # Multiple files

# Common options
grep -i "pattern" file                 # Ignore case
grep -r "pattern" directory/           # Recursive search
grep -n "pattern" file                 # Show line numbers
grep -v "pattern" file                 # Invert match

# Context search
grep -A 3 "pattern" file               # Show 3 lines after
grep -B 3 "pattern" file               # Show 3 lines before
grep -C 3 "pattern" file               # Show 3 lines around

File Content Operations

# View files
cat file.txt                           # Full content
head -20 file.txt                      # First 20 lines
tail -20 file.txt                      # Last 20 lines
tail -f file.txt                       # Follow changes
less file.txt                          # Paged viewing

# Sort and unique
sort file.txt                          # Sort
sort -n numbers.txt                    # Numeric sort
sort file.txt | uniq                   # Remove duplicates

# File comparison
diff file1.txt file2.txt               # Basic comparison
diff -u file1 file2                    # Unified format
diff -y file1 file2                    # Side-by-side

Text Processing and Pipes

# sed stream editor
sed 's/old/new/g' file.txt             # Global replacement
sed -i 's/old/new/g' file.txt          # In-place modification
sed '/pattern/d' file.txt              # Delete matching lines
sed -n '1,10p' file.txt                # Print specific lines

# awk text processing
awk '{print $1}' file.txt              # Print first column
awk '{print $1, $3}' file.txt          # Print multiple columns
awk '/pattern/ {print $2}' file.txt    # Conditional print
awk -F':' '{print $1}' /etc/passwd     # Specify delimiter
awk '{sum += $1} END {print sum}' numbers.txt  # Calculate sum

# Pipes and redirection
command > file.txt                     # Output redirection
command >> file.txt                    # Append redirection
command 2> error.log                   # Error redirection
command &> all.log                     # All output redirection

# Pipe operations
command1 | command2                    # Basic pipe
cat log | grep "ERROR" | awk '{print $1}' | sort | uniq -c

# tee splitting
command | tee file.txt                 # Output to both file and terminal
command | tee -a file.txt              # Append mode
echo "text" | sudo tee /root/file.txt > /dev/null  # Privilege escalation write

Transfer and Compression

Network Downloads

# wget downloads
wget https://example.com/file.zip
wget -O newname.zip https://example.com/file.zip  # Specify filename
wget -c https://example.com/largefile.iso         # Resume download

# curl downloads
curl -O https://example.com/file.zip               # Keep original filename
curl -o newname.zip https://example.com/file.zip   # Specify filename
curl -C - -O https://example.com/largefile.iso     # Resume download

Remote Transfer

# scp secure copy
scp file.txt user@remote:/path/                    # Upload file
scp -r directory/ user@remote:/path/               # Upload directory
scp user@remote:/path/file.txt ./                  # Download file
scp -P 2222 file.txt user@remote:/path/            # Specify port

# rsync synchronization
rsync -av source/ destination/                     # Basic sync
rsync -av --delete source/ destination/            # Delete extra files
rsync -av source/ user@remote:/path/               # Remote sync
rsync -avz --progress source/ destination/         # Compression + progress

Compression and Extraction

# tar archives
tar -czf archive.tar.gz files/                     # Create compressed archive
tar -xzf archive.tar.gz                            # Extract archive
tar -tzf archive.tar.gz                            # View contents
tar -xzf archive.tar.gz -C /destination/           # Extract to directory

# zip compression
zip -r archive.zip directory/                      # Compress directory
unzip archive.zip                                  # Extract
unzip archive.zip -d /destination/                 # Extract to directory
unzip -l archive.zip                               # View contents

Device Management

USB Devices

# USB device management
lsusb                                  # USB device list
lsusb -v                               # Detailed information
watch -n 1 lsusb                       # Real-time monitoring

# Mount USB
sudo mkdir /mnt/usb
sudo mount /dev/sdb1 /mnt/usb          # Mount
sudo umount /mnt/usb                   # Unmount

Bluetooth Devices

# Bluetooth management
systemctl status bluetooth             # Service status
sudo hciconfig hci0 up                 # Enable adapter
sudo hcitool scan                      # Scan devices

# Bluetooth console
bluetoothctl
# Common commands: power on, scan on, pair <MAC>, connect <MAC>

Audio Devices

# Audio devices
aplay -l                               # Playback devices
arecord -l                             # Recording devices
pactl list sinks short                 # PulseAudio output devices

# Volume control
alsamixer                              # Graphical mixer
amixer sset Master 80%                 # Set volume
pactl set-sink-volume @DEFAULT_SINK@ 50%

Quick Operations

History Operations

# History search
Ctrl + R                               # Reverse search history
Ctrl + S                               # Forward search history
history                                # Show history list
history | grep "pattern"               # Search history commands

# ! operator (history expansion)
!!                                     # Repeat last command
!$                                     # Last argument of previous command
!^                                     # First argument of previous command
!*                                     # All arguments of previous command
!n                                     # Execute nth command in history
!ssh                                   # Execute most recent command starting with ssh
!?config                               # Execute most recent command containing config

# Quick substitution
^old^new                               # Replace old with new in last command
!!:s/old/new                           # Same as above, sed-style replacement
sudo !!                                # Add sudo to previous command

# Argument operations
echo !$                                # Show last argument of previous command
ls !*                                  # Use all arguments from previous command with ls

Quick Editing

# Cursor movement
Ctrl + A                               # Move to beginning of line
Ctrl + E                               # Move to end of line
Ctrl + F                               # Move forward one character
Ctrl + B                               # Move backward one character
Alt + F                                # Move forward one word
Alt + B                                # Move backward one word

# Deletion operations
Ctrl + K                               # Delete from cursor to end of line
Ctrl + U                               # Delete from cursor to beginning of line
Ctrl + W                               # Delete previous word
Alt + D                                # Delete next word
Ctrl + H                               # Delete previous character (same as Backspace)
Ctrl + D                               # Delete current character

# Copy and paste
Ctrl + Y                               # Paste last deleted content
Alt + Y                                # Cycle through deletion history

# Other editing
Ctrl + T                               # Transpose current and previous character
Alt + T                                # Transpose current and previous word
Alt + U                                # Convert current word to uppercase
Alt + L                                # Convert current word to lowercase
Alt + C                                # Capitalize current word
Ctrl + _                               # Undo last edit

# System control
Ctrl + L                               # Clear screen
Ctrl + C                               # Interrupt current command
Ctrl + Z                               # Suspend current process
Ctrl + D                               # End input/exit shell

# Auto-completion
Tab                                    # Auto-complete
Tab Tab                                # Show all possible completions
Alt + .                                # Insert last argument of previous command
Alt + *                                # Expand all possible completions for current word

Directory and File Operations

# Directory operations
cd -                                   # Return to previous directory
pushd/popd                             # Directory stack operations
mkdir -p path/to/deep/directory        # Create nested directories

# {} Brace expansion - generates multiple names
touch file{1,2,3}.txt                  # Creates file1.txt file2.txt file3.txt
mkdir {backup,temp,logs}               # Create multiple directories
cp file.txt{,.bak}                     # Copy to file.txt.bak
echo {A..Z}                           # Expand A B C ... Z
echo {1..10}                          # Expand 1 2 3 ... 10
echo {01..10}                         # Expand 01 02 03 ... 10 (preserve format)

# [] Bracket matching - matches existing files
ls file[123].txt                       # Match file1.txt file2.txt file3.txt
ls file[1-5].txt                       # Match file1.txt to file5.txt
ls [abc]*.txt                          # Match txt files starting with a, b, or c
ls [A-Z]*.log                          # Match log files starting with uppercase
ls file[!123].txt                      # Match files except file1,2,3.txt
rm temp[0-9][0-9].tmp                  # Delete files like temp01.tmp to temp99.tmp

# Wildcard combinations
cp *.{jpg,png,gif} images/             # Copy all image files
ls file[1-3].{txt,log}                 # Match file1.txt, file1.log, etc.
find . -name "*[0-9].txt"              # Find txt files ending with digits

🔔 Prelude: When writing Rust programs, Result and Option are data structures we can hardly avoid. I believe that rather than understanding their underlying mechanisms, we should first quickly figure out how to handle them.

Gift Wrapping

Actually, we don’t need to think of Option<T> and Result<T,E> as too complicated:

• Option contains the data we want, where the data type is T. However, there might be no data inside (None). But regardless, as long as what we care about is wrapped, it will be an Option.
• Result also contains the data we want, but it comes with another “restless” additional item E (Error). In fact, combinations of Result and Option are very common, such as Result<Option<T>, E>. Result provides a powerful and unified specification for Rust’s error handling.

So, how do we open the gift box…

The moment of unwrapping gifts is always exciting.

Whether it’s Option or Result, we can use unwrap() to open this package.

• If the gift box contains a normal value, everything goes smoothly, and everyone’s happy.
• But if it contains something “weird” (None or Err), the program will immediately panic and crash.

Of course, if we insist on using safer unwrapping methods (like unwrap_or, match, etc.), we can control whether the program crashes ourselves, which is very practical.

What functions do these gift boxes provide?

Let’s quickly go through the methods they provide. Detailed explanations won’t be provided here, as I believe you can look up relevant information through https://doc.rust-lang.org/std/option/ and https://doc.rust-lang.org/std/result/.

Option

Notable methods:

• map(f) provides a way to operate on inner data without unpacking, very commonly used
• expect("Hi") can display error messages when panicking, more practical than unwrap()
• ? can greatly improve code cleanliness
• is_some() and is_none() are also very useful for making decisions

Result

Compared to the intuitive and easy-to-understand Option, Result seems more “convoluted” with an additional type, but essentially it’s almost identical to Option: what to do if we didn’t get the value (possibly due to an error).

Result also has: map(f) and ?, as well as useful is_ok() and is_err()

In Result<T, E>:

• T is the type of value returned on success (e.g., file content, calculation result, etc.).
• E is the type of value returned on error (e.g., std::io::Error, custom error enum, etc.).
• Actually:
  • E can be any type, with no restrictions
  • But to use ?, facilitate debugging and printing, E usually needs to implement Debug, Display, Error, and other traits
  • Yes, E can be very complex types (carrying context, providing helper methods), or very simple error structures (like, a string). Err is just the shell that Result uses to mark “this is the error branch”, with E inside

Examples

// ===== Creating Option =====
let some_value: Option<i32> = Some(42);  // Has value
let none_value: Option<i32> = None;      // No value

// Common usage: returning from functions
fn find_number(flag: bool) -> Option<i32> {
    if flag { Some(7) } else { None }
}

// ===== Creating Result =====
let ok_value: Result<i32, String> = Ok(42);                    // Success
let err_value: Result<i32, String> = Err("Oops".to_string()); // Failure

// Common usage: returning from functions
fn divide(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err("Division by zero".to_string())
    } else {
        Ok(a / b)
    }
}

🔔 Prelude: Yes, You can always type :h to see help, for example, :h windows

Vim in not so short

Preliminaries

• When vim is not available, you can temporarily use cat or nano as alternatives
• When using a new IDE, you should first learn or configure:
  • save
  • copy / paste
  • duplicate line
  • delete word / delete line
  • line movement
  • navigate forward / back
  • undo / redo
  • page navigation (page down, page up, center to middle, etc.)
  • indent / unindent
  • multi-cursor
  • search / content search
  • input commands (Ctrl + P in VSCode, double Shift in IntelliJ, : in vim…)
  • completion, suggestion, parameter hint, hover hint
  • go to / peek definition, type, declaration, reference, implementation
  • rename symbol / refactor (if available)
  • AI controlling: toggle chat box, trigger inline chat…
  • tabs / windows management
• Use the :help command to query anything you don’t understand
• :set option? can view current settings

Windows and Tabs

Buffer: Can be understood as a temporary file. Even if this file is edited, it doesn’t mean it’s written to the actual file. We can observe buffers through windows and manage them through tabs.

1. Use commands starting with b in Ex (command line) mode for buffer operations:
   • bd buffer delete; bwipeout clears more thoroughly
   • bn or bnext switch to next buffer
   • bp or bprevious switch to previous buffer
   • ctrl + ^ switch to the last buffer

Ctrl + W window shortcuts and :sp split commands are the basics of window management. :sp can use parameters to specify files to split (open a new window for this file)

1. Ctrl + W + w cycle windows, Ctrl + W + hjkl switch focus left/down/up/right (move cursor)
2. Ctrl + W + = (make window panes equal size)
3. Ctrl + W + + Ctrl + W + Ctrl + W + < Ctrl + W + > (fine-tune window size)
4. :vsp performs vertical split, dividing into two sides
5. :resize 20 sets height to 20 lines; :vertical resize 80 sets width to 80 columns

:tabs is the basic tab management command.

1. :tabnew opens a new tab, :tabe (edit) opens a tab for editing. Can be followed by filename.
2. :tabn :tabp switch tabs, or use gt gT to switch
3. Display current buffer in new tab: :tab split
4. :tabmove move tab, for example :tabmove 2
5. Batch execution:
   • :tabdo {cmd} execute on all tabs, e.g., :tabdo set nocursorline
   • :windo {cmd} execute on each window in current tab, e.g., :windo diffthis

:only and :close are universal management methods

1. Type :close :only directly to manage windows
2. Type :tabclose :tabonly to manage tabs

Key Remapping

Here’s the key remapping configuration in VSCode vim extension:

{
"vim.leader": "<space>",
"vim.useSystemClipboard": true, // important
"vim.normalModeKeyBindings": [
    {
      "before" : ["J"],
      "after" : ["5", "j"]
    },
    {
      "before" : ["K"],
      "after" : ["5", "k"]
    },
  ],
"vim.normalModeKeyBindingsNonRecursive": [
    {
      "before" : ["<Backspace>"],
      "after" : ["x"]
    },
  ],
"vim.insertModeKeyBindingsNonRecursive": [

  ],
"vim.visualModeKeyBindingsNonRecursive": [
    {
      "before" : ["<Backspace>"],
      "after" : ["d"]
    },
  ]
}

Common key aliases:

• <Backspace>
• <C-c> -> Ctrl + C
• <A-c> -> Alt + C
• <Shift>
• <CapsLock>
• <Tab>
• <Enter>
• <Esc>
• <Cmd-> Mac specific
• <Up>
• <Down>
• <Left>
• <Right>

vim Configuration File

Use the .vimrc file in the home directory:

" This is vimscript, so use let for assignment and " for comments

nnoremap <SPACE> <Nop>
let mapleader = " "
set number

" Use system clipboard
set clipboard=unnamedplus

" Map `J` to `5j`, `K` to `5k`, `<Backspace>` to `x`
nnoremap J 5j
nnoremap K 5k
nnoremap <Backspace> x
" inoremap
" vnoremap

" nmap
" imap
" vmap
nnoremap <Enter> o<Esc>

Unbound Keys

In VSCode and other IDEs, you can return Vim-controlled keys to the IDE, since they have no use in GUI interfaces.

• Ctrl + D scroll down
• Ctrl + Z suspend Vim
• Ctrl + X decrease number at cursor by 1, in insert mode it’s completion, decrease by 1 is quite useful
• Ctrl + C can be considered
• Ctrl + F scroll forward, in insert mode used to view command history
• Ctrl + W window command, delete one word before cursor
• Ctrl + P completion
• Ctrl + S pause output
• Ctrl + Q same as Ctrl + V, only q alone is for recording macros, VSCode defaults to Add cursor below, multi-cursor editing tool
• Ctrl + Y / E scroll window up/down by 1 line
• Ctrl + T depends on situation

Quick Reference

(jut for memory, may not be accurate)

1. w -> word
2. b -> back
3. e -> end
4. H -> page head; L -> low; M -> middle
5. zz move current line to the middle position
6. Ctrl + U & Ctrl + D half screen move up & down
   • Ctrl + F & Ctrl + B full screen move forward & back
7. g -> go (sometimes obviously more than that)
   • gn go to next (matched), commonly used
   • gi go to (last) insert
   • gd go to definition
   • gf go to file
8. d -> delete (actually puts deleted content into register); sometimes means down
   • dd delete one line
9. x -> dl; X -> dh
   • s -> (x + i)
   • c -> change (d + i)
10. y -> yank
11. p -> do paste | as paragraph
12. { } -> paragraph
13. f -> find occurrence (char)
    • ; -> next occurrence
    • , -> last occurrence
    • t -> till next occurrence
    • F -> backward to occurrence
14. / -> search item with pattern
    • n -> next item
    • ? -> back search
15. u -> undo; Ctrl + R redo
16. 123… -> as line number / do multiple times
17. i -> do insert | as inner (inside); o -> open a line below; a -> append | around
18. s -> as sentence | do substitute
19. q -> record macro
20. v -> visual
21. s -> surrounding. cs{old}{new}. plugin command
    • v S{desire pair} -> surrounding by.
22. J join
23. r replace

Special Characters

1. @ -> execute register content
2. . > as current line | do repeat last change, very commonly used, for repeating edit operations
3. % -> as all lines(all contents); in normal mode represents matching symbols like {[(
4. 0 -> beginning of line
   • $ -> end of line
   • ^ first meaningful character
   • _ first meaningful character (can be operated by g etc.)
   • g_ last meaningful character
5. ; repeat last f, F, t, T command. For example, if you used f to find a character, pressing ; will continue to find the next matching character.
   • , reverse repeat
6. ' for mark navigation. For example, pressing 'a jumps to the beginning of line of mark ‘a’.
7. ``` (backtick) for mark navigation. For example, pressing ``a` jumps to the exact position of mark ‘a’.
8. ~ change char case.
9. & repeat last substitution command

Modes

1. Normal mode: Enter normal mode when first starting, press i (insert) to enter insert mode, press : to enter command input mode
2. Insert mode: Edit file, press Esc to exit.
3. Command input mode: Input commands, press Esc to exit.
4. Press v to enter visual mode, generally used for selecting paragraphs

Command Structure

1. Normal mode commands are almost based on the verb + adj(count) + obj(motion, text-object) pattern, e.g.: d3j, ca(
   • Omitting verb means cursor movement, which can actually be understood as a type of verb.
     • Example: 3j, move down 3 lines
     • Example: 0, $, these are special characters
     • Example: v3w, v only switches mode, doesn’t count as verb, but subsequent behavior without verb is treated as cursor movement
   • Special case: Omitting adj. means based on current position, or only operating on one object.
     • Example: cw, f{
   • Special case: Omitting both adj. and obj. generally means some single character/line shortcuts
     • Example: dd, yy, gg
     • Example: s, x, ~, u
2. Command line mode has almost no pattern. If anything, they can almost all be categorized as command-like modes.
   • verb + obj pattern: :set number, :r file (read file)
   • adj + verb pattern: :3,5 d
     • adj + verb + obj: :3,5 d0
   • obj pattern: :map
   • verb pattern: :w, :q
   • Special pattern (can be viewed as mode switching): :!command (execute external command)
   • Command-like pattern: :s/foo/bar/gc

Repeat Operations

• . for modifications.
• ; for f, etc.
• r means replace
• f sth -> r -> ; -> . -> ; -> . -> … : guess what will happen?
• gn for / etc. Need to operate on current search content once first, then use . to repeat.

Tips

• verb is almost never absent, omitting verb generally means movement (v provides selection function, but still needs to move to some position to trigger)
• At the same time, obj is also almost never absent, omitting obj generally means current position

When inputting commands, if you’re unclear what else to input, consider these questions:

1. Does the command have an object? E.g., w, p, s. (Specifically, line operations generally omit objects). Selection in v mode actually provides objects. Similarly, movement actions actually also provide objects. So, this part should be considered first, but input last.

2. Does the command have modifiers? If there’s a clear area to operate on, you must pay attention to modifier input. Because if not provided, it will immediately operate based on current position, very easy to cause misoperations.

3. What does the command need to do? Please treat this as the last part to think about, to control vim behavior more precisely. But when inputting commands, generally need to input first. So, input this first.

Seqs: 3 → 2 → 1

Commonly used Commands

• :w save
• :q quit
• :q! force quit without saving
• :w filename save file as filename
• :w! filename force save to filename
• :set nu :set number display line numbers, commonly used
• /word search downward (note, no :, when pressing /, command line becomes / mode)
  • Press n, N to search next/previous
  • ?word search upward
• u and :u undo
• Ctrl + R redo
• x = dl, X = dh
• s = ch

Compound Commands

• :5 d delete line 5, commonly used
• :3,5 d delete lines 3 to 5
• :$ d delete last line of document
• :% d delete all content in document
• :n move m move line n to after line m, commonly used
• :n,n+3 t m copy lines n to n+3 to after line m, commonly used
  • Summary: :n,m generally means from line n to line m
• :%s/hello/nihao/g replace all hello with nihao, similar to sed operation
  • :s/hello/nihao/g only replace in current line
• :5,8s/hello/nihao/g replace hello with nihao in lines 5-8

Common Shortcuts

Movement

1. Ctrl + O previous position, Ctrl + I next position
2. If you have Home End PageUp and PageDown keys, you can use them directly, adding Ctrl is more convenient
   1. PgUp PgDown behavior varies, specifically use with Ctrl and Shift
3. Ctrl + U and Ctrl + D half screen scroll; Ctrl + F and Ctrl + B full screen scroll
4. Ctrl + Up to beginning of line, vice versa

Normal Mode

Cursor Movement

Character-based Movement

• h l move left/right, k j move up/down, arrow keys also work
• Use f to find next character, uppercase for reverse search; using t stops before that character
  • Use ; and , to repeat forward/backward search
• ^ move to first non-whitespace position
• g_ find first non-whitespace position from end of line
• Use $ to move to end of line
• Use % to match brackets like ( { [

Word-based Movement

• w move to next word, commonly used, remember as word
• b move to beginning of current/previous word, commonly used, remember as back
• e move to end of current/next word, commonly used, remember as end
  • Uppercase W, B, E, gE for including characters after words
  • ge move to end of previous word
  • 3w can move 3 times
• Use / and ? to search for pattern, use n and N to jump to next/previous

Line-based Movement

• g is the most basic line movement command
• 0 move cursor to beginning of line, $ move cursor to end of line
• Home key to beginning of line, End key to end of line
• G (Shift+G)/gg move cursor to end/beginning of file
• Actually G is go, so you can input 500G or 500gg to locate to line 500, commonly used
  • Or directly use :line_number to locate
  • gi return to last insert location, commonly used

Block or Screen-based Movement

• { } move by paragraph
• H move to top line of screen; L move to bottom line of screen; M move to middle of screen

Mark-based Movement

• ma set mark a
• 'a jump to beginning of line of mark a
• ``a` jump to exact position of mark a
• '' jump to beginning of line of previous position, commonly used

Operation Commands

Follow {operator}{count}{motion} pattern, e.g.: d2w

• c change, d delete, y yank (copy), p paste
  • change means delete corresponding content and directly enter insert mode
• gu gU or directly press ~ to change char’s case (commonly used)
• = format, for formatting, need to set code standards in advance, e.g.:

set autoindent        " Inherit indentation from previous line
set smartindent       " Smart indentation based on syntax
set cindent           " C/C++ style indentation
set shiftwidth=4      " Move 4 spaces for each indentation operation
set tabstop=4         " Display one Tab as 4 spaces
set expandtab         " Use spaces instead of Tab

Common formatting commands:

• ==: Format current line.

• =motion: Format range specified by motion.

• =ap: Format current paragraph (ap means “a paragraph”).

• =%: Format content within brackets matching current cursor position.

• gg=G: Format entire file.

• Use >> for indentation, use > when target is provided

Text Objects (delete content of specific patterns)

Follow {operator}{a/i}{text object} pattern, e.g.: di' (delete inside ’)

• Generally used with c, d
• a -> around, i -> inside
• text-object identifiers:
  • w word
  • s sentence
  • p paragraph
  • '"[{< ` corresponding to respective special blocks
  • t tag, commonly used in html language, between ><

Copy and Delete

• yy copy current line, commonly used
• dd cut current line, commonly used
• 3dd delete 3 lines, commonly used
• p/P paste content after/before cursor, commonly used
• x delete character at cursor, X delete previous character
• r modify character at cursor
• R enter replace mode

Undo

• u undo, commonly used
• Ctrl + R redo, commonly used

Enter Insert Mode

• i enter insert mode at current position
• a enter insert mode at next character
• A enter insert mode at end of line
• o enter insert mode on next line, often used with G and End, commonly used
• s delete current character and enter insert mode
• S delete current line and enter insert mode
• cw delete next word and enter insert mode
• cb delete previous word and enter insert mode

Insert Mode

Generally use shortcuts for operations

Cursor Movement

1. Ctrl + A move cursor to beginning of line, uppercase moves to beginning of document
2. Ctrl + E move cursor to end of line

Text Operations

1. Ctrl + W: Delete one word before cursor.
2. Ctrl + U: Delete all content from current cursor position to beginning of line.
3. Ctrl + T increase indentation to the right
4. Ctrl + D decrease indentation to the left
5. Ctrl + R: Insert register content. After pressing, need to input register identifier, e.g., Ctrl + R, 0 inserts content of register 0.

Completion Features

1. Ctrl + N: Auto-complete next matching word. commonly used
2. Ctrl + P: Auto-complete previous matching word.
3. Ctrl + X, Ctrl + L: Full line completion, shows dropdown menu
4. Ctrl + X, Ctrl + N/P: Word completion based on current file.
5. Ctrl + X, Ctrl + F: Filename completion.
6. Ctrl + X, Ctrl + K: Dictionary lookup completion.

Others

1. Ctrl + C: Exit input mode. Replace Esc, commonly used
2. Ctrl + O: Temporarily switch to normal mode to execute one command, then return to input mode. commonly used
3. What if you press wrong key? In normal mode use Ctrl + O to return to previous position, meaning in input mode press Ctrl + O x2

Visual Mode

Follow {trigger v}{motion}{operator} pattern, e.g.: v2wd (select two words then delete)

• Press v for character selection, V for line selection, Ctrl + V for block selection
• Generally only used for copy-paste, operation speed is slow

: Command Mode

Batch Processing (delete, move, copy, paste)

1. :2,5d a: Delete lines 2 to 5 and save in register a
2. 0 line 0; `# Vim in a Nutshell
3. :.,+3d delete current lint & plus 3 lines
4. In visual mode，:'<,'>d means “delete selected content”
5. @: repeat last : command
   • After using q for macro recording we can use @@ repeat it
   • After @: , @@ is still available
6. :'<,'>move .
   • :m 10 move (current line) to 10 line after
7. :/ looking for last found pattern

Quick Reference

Find and Replace

• :%s/old/new/g: In entire file range, replace all strings matching old with new. Add c to ask before each replacement.
• :s/old/new/g: Replace all old with new in current line.
• :g/pattern/d: Delete all lines matching pattern.
• :'<,'>s/old/new/g: In visual mode selected range, replace all old with new.
• :'<,'>normal command: Execute normal mode command on each line selected in visual mode.

Line Operations

• :d: Delete current line (similar to dd).
• :t .+1: Copy current line and paste to next line.
• :m .+1: Move current line down one line.
• :m .-2: Move current line up two lines.
• :-3,. m .+1: Move 3 lines above current line to below current line
• :-3,.y | :.+1put: Copy above three lines, paste to next line. put creates new line, p pastes at cursor position

sed-like Command Usage

1. Replace all matching patterns at once: :%s/pattern/replacement/gc for entire file range (%), substitute (s) pattern with replacement
2. gc are flags, common flags include:
   • g: Global replacement (apply command to all lines)
   • c: Ask before each command execution.
   • i: Ignore case
   • n: Maximum number of replacements
   • p: Print results
   • v: Invert results
   • !: Pass to external tool -> %!sort will sort entire text
3. Explicitly use normal commands in Ex mode. Use norm
   • Very useful with v mode
   • Example: :'<,'>norm A!, will for content selected in v mode (‘<,’>), uniformly add a “!” at the end of lines (A)

% itself is shorthand for **`1,# Vim in a Nutshell

Tips

• Accidentally pressed Ctrl + S? Use Ctrl + Q to release
• It’s best not to use the right numeric keypad for editing, there might be key conflicts

Copy-Paste Issues

Vim editor has its own clipboard system called registers. Vim uses registers to store text, which are different from X11 clipboards. If Vim is compiled with X11 clipboard support (through +clipboard option), then you can use special registers "* and "+ to access X11’s PRIMARY and CLIPBOARD.

Paste Mode

To prevent auto-formatting from corrupting pasted content, Vim provides paste mode. Before pasting, execute :set paste command to enter paste mode, which will temporarily disable auto-indent, auto-wrap and other functions. After pasting, execute :set nopaste to return to normal mode.

You can also install some programs to access X11 clipboard, such as xclip or xsel.

Right mouse button enters visual mode?

• :set mouse-=a

Register Overview

Vim uses a set of registers as its “clipboard”. These registers can be used to save text and paste later. Each register has an identifier, which can be a single letter or special character. Here are some basics about Vim registers:

Note, to use registers, first press ", then switch to the desired register, then perform operations

To view register status, type :reg in command line mode

Basic Registers

• "" - Default register, if you don’t know where copied content went, look here
• "0 - Number 0 register. Stores content of your last yank (copy).
• "- - Small delete register. Stores content of your last delete or change that’s less than one line.
• "1 to "9 - Number registers. Store your recent delete or change history ("1 is most recent, "9 is oldest).
• "a to "z or "A to "Z - Named registers. You can use lowercase letters to store text, uppercase letters to append text to corresponding lowercase register.

Special Registers

• "* and "+ - Clipboard registers. In Vim with clipboard support (usually GUI version Vim or Vim with +clipboard feature), these two registers communicate with system clipboard:
  • "* register corresponds to X11’s PRIMARY clipboard (usually the select-to-copy one).
  • "+ register corresponds to CLIPBOARD clipboard (usually used with Ctrl+C/Ctrl+V key combinations). Most commonly used.

Using Registers

• Copy to register: You can use "ay to copy to register a, where a is the register name, y is the yank command.
  • Almost the same in visual mode
• Paste from register: To paste from register, you can use "ap to paste content of register a, where a is the register name, p is the paste command.
• In insert mode: Use Ctrl + R to call up " symbol

Using Registers in Insert Mode

Press

Ctrl + R + register name

For example

Ctrl + R + " uses default register, Ctrl + R + + uses system register.

Using Registers in Terminal

When you use Vim in terminal instead of GUI version, accessing system clipboard becomes more complex, because Vim needs to include clipboard support at compile time. You can run vim --version to see if your Vim supports clipboard (look for +clipboard or +xterm_clipboard).

If your Vim supports clipboard, you can interact with system clipboard in the following ways:

• Use "*y to copy to system’s PRIMARY clipboard.
• Use "+y to copy to system’s CLIPBOARD clipboard.
• Use "*p or "+p to paste from corresponding system clipboard to Vim.

If your Vim doesn’t have clipboard support, you won’t be able to directly access system clipboard from Vim. In this case, you need to use external programs (like xclip or xsel) to help you copy Vim register content to system clipboard, or paste from system clipboard to Vim.

External Commands

Using :! to Execute External Commands

You can use :! followed by command to execute any external command. For example, if you want to see current directory contents, you can type in Vim’s command mode:

:!ls

Using :r to Read External Command Output

If you want to insert output of sed, awk or other commands into current Vim editor text, you can use :r ! command. For example, if you want to insert ls command output at current position, you can type:

:r !ls

Using :%! to Process Entire File Content Through External Command

If you want to apply sed or awk command to entire file content and replace current file content, you can use :%! followed by corresponding command. For example, use sed command to replace all “foo” with “bar” in document:

:%!sed 's/foo/bar/g'

Partial Usage

You can also specify a range to use external command only on certain parts of the file. For example, only process lines 5 to 10 through awk command:

:5,10!awk '{print $1}'

Macro Recording

1. Use q for macro recording in normal mode
   • Give register a name, say a, the full name of this register is @a
   • Press q again to end recording after recording is complete
   • Type @a to execute macro, @@ to execute last macro, 9@a to execute macro 9 times
2. +1 operation on numbers. <C-a>, can be used with macro recording to write ordered lists:
   • 1. sth, then yyp, perform <C-a> on 1, repeat

Other Features

1. Spell check. :set spell! spelllang=en_us
2. :set rnu set relative line numbers. Convenient for jumping

🔔 Prelude: No need for digging a big hole, just use it.

Golang in short

Go is

1. A modern high-level programming language that resembles C
2. Open-source, compiled, statically typed, and memory-safe

Go has

1. Simple yet powerful package management (pulls directly from GitHub)
2. Built-in concurrency primitives
3. Garbage collection (GC)
4. Lightning-fast compilation
5. Minimal syntax
6. Cross-platform compilation

Go doesn’t have

1. Classes and inheritance
2. Function overloading
3. Implicit type conversions

I use Go to

1. Say goodbye to Java’s verbose syntax
2. Build web services and microservices
3. Handle high-concurrency scenarios

Go is perfect for

1. Web services and RESTful APIs
2. Microservices architecture
3. Network programming and distributed systems

Go might not be ideal for

1. GUI desktop applications
2. Kernel development
3. Machine learning (Python has a stronger ecosystem)

Installing Go

1. Using OS package managers
   • Linux: apt, yum, snap
   • macOS: brew
   • Windows: choco, scoop, etc.
2. Download official precompiled binaries
   • Already compiled, ready to use
   • Set up path and links manually
3. Verify with go version

Hello World

// This is a comment
/* This is
   a multiline
   comment */
package main // This is the main package

// No semicolons at line endings

import (
    "fmt"
    "math"
) // Importing other packages

const myConstant int = 0 // Constants need explicit initialization

func main() {
    fmt.Println("helloworld")
    // Package names -> lowercase
    // Lowercase in package -> myConstant -> package-private
    // Capitalized -> Println() -> exported (public)
}

Types

bool

string

int  int8  int16  int32  int64
uint uint8 uint16 uint32 uint64 uintptr // Has pointers but no pointer arithmetic

byte // alias for uint8

rune // alias for int32
     // Represents a Unicode code point
     // From ancient Nordic "rune"

float32 float64

complex64 complex128

// Zero value for reference types is nil

// Type assertion
t, ok := variable.(int) // Returns two values, ok indicates success
                        // Panics if ok is not captured and type is wrong

// Type conversion
var myInt int32 = 42
myAnotherInt := int64(myInt) // Type conversion
                             // No direct conversion between bool and int
                             // Generally, single characters and numbers can convert
                             // Otherwise, only conversions within same type family

Variables and Functions

var hi bool = true // Variables outside functions must have explicit types

func myFunc(x, y int) (int, int) {
    innerHi := "hi" // Inside functions, use := for type inference
    const hiConst = "hi again" // Constants cannot use :=
    return x + 1, y + 1
}

func MapFilter[T any, R comparable](
    slice []T,
    mapper func(T) R,
    predicate func(R) bool,
) func(options ...int) (filtered []R, count int, err error) {
    // Returns a function
    return func(options ...int) (filtered []R, count int, err error) {
        // Implementation
        return
    }
}
// A complete function signature example
// Note the second func starts parameters
// The last func starts return type -> returns a function
// T is generic, R is constraint, but they're essentially the same thing

func(x int) int { return x * 2 } // Anonymous function definition

Arrays, Slices, and Maps

// Arrays - fixed length
var arr [5]int = [5]int{1, 2, 3, 4, 5}
arr2 := [...]int{1, 2, 3} // Compiler infers length

// Slices - dynamic length
var slice []int = []int{1, 2, 3}
slice2 := make([]int, 5)     // Length 5
slice3 := make([]int, 5, 10) // Length 5, capacity 10

// Maps
var m map[string]int = map[string]int{"one": 1, "two": 2}
m2 := make(map[string]int)
m2["key"] = 42

// Check if key exists
value, exists := m["key"]
if exists {
    fmt.Println(value)
}

Control Flow

// Only for loops exist
// All parts of for loop are optional
for i := 0; i < 10; i++ {
    // Loop body
}

// Infinite loop
for {
    // Equivalent to while(true)
}

// Condition loop
i := 0
for i < 10 {
    i++
}

for i, v := range expression {} // Iterate over iterables
                                // Similar to Python's for..in
                                // Directly provides index and value
                                // No enumerate function needed
                                // Use _, v to ignore index

// if statement
if v := 5; v < 6 { // Can assign in condition
    // Condition body
}

// switch statement
switch x := 5; x { // x is optional
    case 1:
        fmt.Println("one")
    case 2, 3, 4:      // Multiple values
        fmt.Println("two, three or four")
    default:
        fmt.Println("other")
}

// Type switch
switch v := x.(type) {
    case int:
        fmt.Printf("int: %d\n", v)
    case string:
        fmt.Printf("string: %s\n", v)
    default:
        fmt.Printf("unknown type\n")
}

Defer and Channels

// defer - deferred execution (stack structure, LIFO)
defer fmt.Println(1)
defer fmt.Println(2)
defer fmt.Println(3)
panic("!")

// Output order: 3 2 1 panic
// defer provides stack-based deferred execution
// panic triggers deferred functions

// channel - channels (queue structure, FIFO)
func channelExample() {
    myChan := make(chan int, 2) // Buffer size 2
    myChan <- 10 // 10 goes in
    myChan <- 20 // then 20 goes in
    took := <-myChan      // took is 10
    fmt.Println(<-myChan) // 20
}

func blockingChannel() {
    ch := make(chan int) // Unbuffered channel
    // ch <- 1           // Will block! Need another goroutine to receive

    // Correct approach
    go func() {
        ch <- 1
    }()
    fmt.Println(<-ch)
}

// Channels provide a queue-like or pipe-like structure
// FIFO

Pointers

// Go has pointers
// Useful when referencing large data
// Go's design philosophy is very close to C-family languages
// Fun fact: When passing pointers to functions, both C and Go copy the pointer
// All parameters are pass-by-value in both languages
// But C++ has completely different reference passing mechanism

func main() {
    var myPtr *int
    // var anotherPtr uintptr  // uintptr is integer type, not pointer

    i := 42
    myPtr = &i // Take address

    fmt.Println(*myPtr) // Dereference, outputs 42
    *myPtr = 43         // Modify through pointer
    fmt.Println(i)      // Outputs 43

    // No pointer arithmetic
}

Format Verbs

Reference:

String Formatting

// %[flags][width][.precision]verb

// Width and alignment
fmt.Printf("%5d\n", 42)      // "   42" right-aligned, width 5
fmt.Printf("%-5d\n", 42)     // "42   " left-aligned, width 5
fmt.Printf("%05d\n", 42)     // "00042" zero-padded

// String alignment
fmt.Printf("|%10s|\n", "hello")   // "|     hello|" right-aligned
fmt.Printf("|%-10s|\n", "hello")  // "|hello     |" left-aligned
fmt.Printf("|%10s|\n", "你好")     // "|        你好|" handles Chinese

pi := 3.14159265359

// Decimal precision
fmt.Printf("%.2f\n", pi)     // "3.14" 2 decimal places
fmt.Printf("%.4f\n", pi)     // "3.1416" 4 decimal places (rounded)
fmt.Printf("%8.2f\n", pi)    // "    3.14" width 8, 2 decimals
fmt.Printf("%08.2f\n", pi)   // "00003.14" zero-padded

// Scientific notation precision
fmt.Printf("%.3e\n", pi)     // "3.142e+00"
fmt.Printf("%.3g\n", 0.00012345)  // "0.000123" auto format

// + flag: show sign
fmt.Printf("%+d\n", 42)      // "+42"
fmt.Printf("%+f\n", -3.14)   // "-3.140000"

// # flag: show base prefix
fmt.Printf("%#x\n", 255)     // "0xff"
fmt.Printf("%#o\n", 8)       // "010"
fmt.Printf("%#b\n", 5)       // "0b101"

// Space: add space for positive numbers
fmt.Printf("% d\n", 42)      // " 42"
fmt.Printf("% d\n", -42)     // "-42"

// Making tables
fmt.Printf("%-10s %8.2f %5d\n", "Apple", 3.99, 10)
fmt.Printf("%-10s %8.2f %5d\n", "Banana", 12.5, 5)
// Output:
// Apple          3.99    10
// Banana        12.50     5

// Dynamic width and precision
width := 10
precision := 2
fmt.Printf("%*.*f\n", width, precision, pi)  // Width and precision from variables

Structs

type MyStruct struct {
    x int  // Private field (package-visible)
    Y int  // Public field (exported)
}

// No need for "->" with struct pointers, Go handles it

// Value receiver method
func (s MyStruct) myFunc(x, y int) (int, int) {
    return s.x + x, s.Y + y
}

// Pointer receiver method
func (s *MyStruct) modify(x int) {
    s.x = x  // Can modify original struct
}

// Pointer receivers can accept values and pointers
// Value receivers can also accept both, Go handles it automatically
// In a sense, pointer parameters have "broader" acceptance

// Struct tags
type User struct {
    Name string `json:"name" xml:"user-name"`
    Age  int    `json:"age,omitempty"`
    Pass string `json:"-"` // Ignore this field
}

// Reading tags with reflection
import "reflect"
field, _ := reflect.TypeOf(User{}).FieldByName("Name")
fmt.Println(field.Tag.Get("json"))  // "name"

Interfaces

// Interfaces define method signatures
// No explicit implementation needed - types automatically implement interfaces
// Interfaces can embed other interfaces

type MyInterface interface {
    myAdd(x, y int) int
}

type MyStruct struct{
    x int
    y int
}

func (s MyStruct) myAdd(x, y int) int { // Implements myAdd
    return x + y
}

// Now MyStruct implements MyInterface

// Empty interface
interface{} // or any (Go 1.18+)
// Can store any type
var x interface{} = 42
x = "hello"
x = []int{1, 2, 3}

// Empty struct
var y struct{} = struct{}{}
// Takes no memory, often used as signal

Error Handling

// error is a built-in interface
type error interface {
    Error() string
}

// Functions typically return result and error
result, err := doSomething()
if err != nil {
    fmt.Printf("couldn't convert number: %v\n", err)
    return
}

// Custom error
type MyError struct {
    msg string
}

func (e MyError) Error() string {
    return e.msg
}

// Create errors with errors package
import "errors"
err := errors.New("something went wrong")

// Format errors with fmt.Errorf
err := fmt.Errorf("invalid value: %d", value)

Concurrency

// Use go keyword to start goroutines
func main() {
    go say("world")
    say("hello")

    // Need to wait for goroutines to finish
    time.Sleep(time.Second)
}

// See Defer and Channels section for channel creation

// Sending to full channel blocks
// Receiving from empty channel blocks

// Close channel
close(myChan)
// Note: Only senders should close channels

// Use select to handle multiple channels
// Like concurrent switch
// select blocks until one case can proceed
// When multiple cases ready, randomly picks one
select {
    case v := <-ch1:
        fmt.Println("received from ch1:", v)
    case ch2 <- x:
        fmt.Println("sent to ch2")
    case <-quit:
        fmt.Println("quit")
        return
    default:
        fmt.Println("no communication")
}

// Mutex
import "sync"
var mu sync.Mutex

mu.Lock()
// Critical section
mu.Unlock()

// Use defer to ensure unlock
mu.Lock()
defer mu.Unlock()
// Critical section

// Directional channels
func send(ch chan<- int) { ch <- 42 }      // Send-only
func recv(ch <-chan int) { val := <-ch }   // Receive-only

// Check if channel is closed
v, ok := <-ch  // ok is false if channel closed and empty