git & Linux cmds, help, tips & tricks - Gabriel.txt

Gabriel Staples

This file is part of eRCaGuy_dotfiles: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
Video of HOW IT FEELS TO *NOT* BE DOING CONTROLS OR MOTION PLANNING, OR SENSORS OR ACTUATORS IN MY DAY-JOB:
https://www.linkedin.com/feed/update/urn:li:activity:6964107799882575873/
I'd rather do that kind of work--it would pump up my spirits. Need that kind of work done? Hire me. 
MY RESUME: https://drive.google.com/file/d/1qgDBc1nYYgqGs79IVOfYlSQ7wInOENkN/view?usp=sharing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

HOW TO FUZZY-SEARCH THIS FILE:
---
cat "path/to/eRCaGuy_dotfiles/git & Linux cmds, help, tips & tricks - Gabriel.txt" | fzf -m --reverse
    [GOOD] Fuzzy search this file withOUT showing line numbers.
    See my comment: https://github.com/junegunn/fzf/issues/1034#issuecomment-1054558594
grep -n '' "path/to/eRCaGuy_dotfiles/git & Linux cmds, help, tips & tricks - Gabriel.txt" | fzf -m --reverse
    [BETTER] Fuzzy search this file WITH showing line numbers!
    See my comment: https://github.com/junegunn/fzf/issues/1034#issuecomment-1054558594
gs_fzf_git_and_linux_cmds_doc
    <========= FUZZY SEARCH THIS DOCUMENT! =========
    [BEST] Same as above, but use my bash function which is defined in ".eRCaGuy_dotfiles/home/.bash_aliases" instead!


====================================================================================================
= Mentorship: =
====================================================================================================
[how to be a good mentor]

References:
1. *****+++ Primary reference: https://hbr.org/2019/08/great-mentors-focus-on-the-whole-person-not-just-their-career

"Great Mentors Focus on the Whole Person, Not Just Their Career"
    https://hbr.org/2019/08/great-mentors-focus-on-the-whole-person-not-just-their-career

Note: other types of knowledge-sharing and guiding include:
    - coaching (ex: training in soft skills or job changes)
    - skill-building (ex: teaching C++, electrical engineering, or controls)
    - performance feedback (ex: a manager providing work-related performance feedback to someone under them on their team)

> Share your stories. When I meet with a younger person for the first time, I say: “Tell me your story. Start at the beginning and take your time — 20 or 30 minutes. I may ask a few questions, and everything you say will be confidential between us. Then, when you’re finished, I’ll tell you my story if you want me to.” (They always do.) This simple exercise can transform the trajectory of a mentoring relationship because it shows that you’re truly interested in understanding your mentee and his or her journey, not just in dispensing professional advice. It gives you knowledge of the person’s past which enables you to make more probing inquiries over time. When I tell my story, I make sure to describe one or two of the difficult chapters in both my career and personal life, including my marriage. This signals that all aspects of our lives are on the table.

> Ask great questions. Effective mentors develop a storehouse of probing questions on any number of subjects. Examples include:
>
> 1. What keeps you up at night?
> 1. Can you see yourself being stimulated and fulfilled on your current career path for the next five years?
> 1. What do you do to “reboot” so that the busyness and tech overload in your life does not result in burnout?
> 1. Who has been most influential in your life?
> 1. What did you love doing in high school?
> 1. What would you have done differently in your life if you had the chance?
> 1. On a scale of 1 to 10, how would you rate your marriage/romantic relationship right now?
> 1. How was your relationship with your parents?
> 1. Were you raised in a particular faith or religious tradition?

"If you must make an ethics decision that potentially affects keeping your job, keeping your client, or keeping your professional license, you should decide on the path that keeps your license. You can always get another employer or another client, but you rarely can get another license."
    - VectorSolutions, "Ethics for Professionals" training, Conclusion slide/section.
<=====

- "If your obligation to your employer or client conflicts with your professional obligation or ethics, you should 'have such objectionable conditions corrected, or resign.'"
- "If you know a professional that behaves unethically, you should 'avoid association with that professional'."
    - VectorSolutions, "Ethics for Professionals" training

----------------
Words of wisdom:
----------------

"When men carry bound energy, it makes women [or people in general] feel unsafe."
    - Raj Narayanan - https://www.linkedin.com/in/raj920/ 
    GS Context: stuffing down energy like anger, resentment, pain, hurt, etc., can lead to volcano-like explosions, negativity, negative energy or sentiment, etc. This is what we call "bound energy". If we just get with our emotions every day, instead, and experience them at no one and nothing, we can instead free that energy and be a safe space for others.

"When are things going to turn around?
Answer: When you're fully there. That's the only answer I can give you. 
When you're committed to being there, and you're fully there." 
    - Raj Narayanan - https://www.linkedin.com/in/raj920/ 
    GS: in other words, when we have done the work and have done **our part**, **then** we will be ready to embrace the positive changes that are coming.

1. *****+ "Numbers are important, but don’t let them define your choices. Don’t use money to cut back on things you love just because they're "expensive." Use money to actualize your vision for how you want to live your life."
    - Dexter Zhuang (https://www.linkedin.com/in/dexter-zhuang/)
      https://www.linkedin.com/posts/dexter-zhuang_in-2019-i-left-my-cushy-san-francisco-tech-activity-7061146444270858241-OS0M/

[Practice "defensive employment"]
1. Don't go 110%!: https://www.tiktok.com/@phong.thieu/video/7131489984686640390?is_from_webapp=v1&item_id=7131489984686640390
1. Let it burn! 🔥🔥: https://www.tiktok.com/@phong.thieu/video/7138809958451121414?is_copy_url=1&is_from_webapp=v1&item_id=7138809958451121414
    1. If deadlines truly are unreachable, they should burn 🔥. It's the only way leadership ever realizes there's a problem, you know?

1. *****+ Part of the ebb and flow of life and "work/life balance" or "work/life harmony" is that sometimes you must spend extra time on your family and it will affect your bonus, and sometimes you can spend extra time at work and it will help you get promoted in your current job or find a new job. 

    keywords: gabriel staples elusive work-life balance, no!: it is a work-life **harmony**, with give and take, ebb and flow, sometimes giving more to one role in your life than another, and alternating as necessary so that you can do your best work and be mos-productive in each role in its due time:
        See also: 
        1. Work-life harmony, by Nicole Malachowski: https://www.linkedin.com/feed/update/urn:li:ugcPost:6942500854797152256/?commentUrn=urn%3Ali%3Acomment%3A%28ugcPost%3A6942500854797152256%2C6943330228509315072%29
        2. https://www.linkedin.com/posts/gabriel-staples_inspiration-work-lifebalance-activity-7003243118720425984-g7ko?utm_source=share&utm_medium=member_desktop
        3. ***** [my LinkedIn post with this very content] https://www.linkedin.com/feed/update/urn:li:ugcPost:7003891808833351680/

    Is there an elusive work-life balance? No!: it is a work-life **harmony**, with give and take, ebb and flow, sometimes giving more to one role in your life than another, and alternating as necessary so that you can do your best work and be most-productive in each role in its due time.

    Ex: let's say you spend 2 months of intense house hunting, followed by a huge family move to move into the new house, get settled there, and fix it up. Perhaps you have maintenance people in the home many days, and that distracts from work and requires your attention. Perhaps you have a difficult closing process and must take an extra 10 days off of work to work with the lender, provide documentation, do home inspections, or coordinate with the builder, etc. As a result of these things, you may have to "partially meet" expectations for that season of your employment, perhaps even losing a portion of or all of your annual bonus. 💸$$💸 Instead of thinking, "I failed! I am not meeting expectations", the thought of which drags you down into despair, think to yourself: "I **SUCCEEDED** and **AM SUCCEEDING**!" "I manged to get my family into a new home while keeping my job, despite all these difficulties. I have **succeeded**!" Then, get back to work. 

    As someone who has traditionally flat-out neglected my family (to their and my severe detriment--and generally with it _still_ not being enough for what my work/employer wants anyway) for fear of not succeeding at work, I have begun to realize that "work-life balance" (or "work-life harmony", as some people call it [see link 1 above]) doesn't mean "trying to meet family expectations *and* work expectations all of the time, no matter what". Rather, it means: "sometimes meeting work expectations, and sometimes meeting family expectations, according to the season of life you are in and the individual circumstances at play." Sometimes, you must spend very little time with your family for 5+ years to get through a grueling school program or to grind through a really hard time in life where you are working one job while building skills for another. And, you do this "work" ultimately *for your family*. In the end, it benefits both, but in the moment, it feels like losing your family or losing your work. And, sometimes you must reduce your work output significantly so you can get your family into the house you've been working for for the last 25 years (or to help out with medical needs, or to do some other really important thing), even though that reduced output may mean your employer removes your bonus and tells you you are failing. If you have done all you can do and kept your job or found another one, you are *not* failing. You are **succeeding**! You have discovered that your work at home or for others is important and is not replaced in importance by your work for your employer. 

    In other words: ***you have found work-life balance!***

1. The **85% rule:** to reach your full potential, aim for 85%, not 100%: https://www.linkedin.com/posts/danfounder_the-85-rule-ugcPost-7005885256721461250-wu83?utm_source=share&utm_medium=member_desktop
    - 100% just feels too overwhelming, and will actually cause you to *decrease* performance. When you strive for 85% it leaves room to relax and enjoy the process and get into the flow, rather than just feeling stressed all the time. 
    - Here are my words on it: [my own post] https://www.linkedin.com/feed/update/urn:li:activity:7005947220453720065/

1. @Alex Nguyen on "What I wish I knew hopping companies": https://www.linkedin.com/posts/alxngu_alexcancode-career-coding-activity-7005961425647009793-71UI?utm_source=share&utm_medium=member_desktop

1. “Children are not distraction from more important work they are the most important work” -C.S. Lewis
    From LinkedIn post by @Sanjay Pendharkar: https://www.linkedin.com/feed/update/urn:li:activity:7006792087178260481?utm_source=share&utm_medium=member_desktop


====================================================================================================
= Fun facts: =
====================================================================================================

A collapsing electromagnetic field when you rapidly turn off a switch to DC power causes an inductance-induced voltage spike akin to a water hammer in your pipes causing an inertia-induced pressure spike when you rapidly turn off the water. 
    - Gabriel Staples, 13 June 2024


====================================================================================================
= Quotes: =
====================================================================================================

"Anyone can take anything from you, except your honor and integrity. Only *you* can give that away."
    - Matthew Snider, US Army Ranger: "A" Company 2nd Platoon 3/75 Ranger Battalion Special Operations Command (SOCOM), quoting his grand-dad, 13 June 2024

"Yes is yes. Maybe is yes. And a no is just a delayed yes."
    <=== a perspective I need to have more in life, to keep me calm and help me carry on.
    - Friend of Elon Musk, at 36:10 in "Elon Musk: The Real Life Iron Man", a video documentary on Tubi. 
      GS notes: [How to have an optimistic perspective to drive you to keep trying in business even when it seems impossible]

"Entrepreneurs have a phenomenal bounce back factor. They *expect* to fail sometimes."
    Another quote from a different person (who seemed reputable in my view), at 36:46 in "Elon Musk: The Real Life Iron Man", a video documentary on Tubi. 

"Working hard for something we don't care about is called stress. Working hard for something we love is called passion."
    - Simon Sinek, on Linkedin
      https://www.linkedin.com/in/simonsinek/
      https://www.goodreads.com/quotes/7697100-working-hard-for-something-we-don-t-care-about-is-called

"Don't apply for a specific job. Find a company you want to work for and get in any way you can." 
    - Max Landesman
    Slide 5 of 9 shared by Austin Belcak here: https://www.linkedin.com/posts/abelcak_7-best-pieces-of-career-advice-ugcPost-7027298563168591872-82La?utm_source=share&utm_medium=member_desktop

"Set your own boundaries for work/life balance. No one else will do that for you."
    - Jess Almlie
    Slide 7 of 9 shared by Austin Belcak here: https://www.linkedin.com/posts/abelcak_7-best-pieces-of-career-advice-ugcPost-7027298563168591872-82La?utm_source=share&utm_medium=member_desktop

"I believe that creating a culture of valuing people doesn't just make them *feel* better to be on your team, it makes them work harder and *perform* better with greater *success* on your team. If you as a manager do this, then instead of a win/lose relationship in the *short term* (making them work extra now [they lose] for greater immediate productivity [you win]), and a lose/lose relationship in the *long term* (they leave your team because they are burned out and don't want to work for you anymore), you'll end up with a win/win relationship in the mid to long term (they are happy, less stressed, and more-productive, and get more work done). Have the vision. Choose the win/win. Be a hero. Hire heroes."
    - Gabriel Staples
    See the full context in my post here, including the post I re-shared, by Alex Nguyen. It's about being a good manager who values people and treats them well and has a long-term win/win vision in mind:
    https://www.linkedin.com/posts/gabriel-staples_alexcancode-career-engineer-activity-7029863104406593536-JtYI?utm_source=share&utm_medium=member_desktop


"Just keep trying. Care enough to make it right, and it will really separate you from a staggering amount of more-talented wood-workers." [GS: or engineers, software developers, or whatever it is you do].
    - Blacktail Studio owner (Cameron Banderson, I think, based on his [Ebay auctioneer name](https://www.ebay.com/itm/195320349148), at 22:50 in this YouTube video here: https://www.youtube.com/watch?v=8wYDq9F8J7M&t=1370s
    GS notes: I think this applies to any talent or profession. See my comment here: https://www.youtube.com/watch?v=8wYDq9F8J7M&lc=UgzAaYEFmsJd5-K_bOd4AaABAg

"Computer Science: solving today's problems, tomorrow."
    - One of the many random quotes displayed on the Eclipse IDE splash screen during startup when you have the "Darkest Dark Theme with DevStyle 2022.6.13a" plugin installed

"Whatever the cause of such strife may be, simply ruminating on the issue — or deliberately engaging in conflict avoidance tactics (i.e. people-pleasing), will do nothing to resolve said contention. The fact of the matter is, confrontation is necessary, and if done properly can dramatically increase the quality of our lives — in addition to that of our relationships."
    - A.J. Deveaux, Why Confrontation is Good, How to properly handle conflict, medium.com (https://medium.com/swlh/why-confrontation-is-good-20aa32a69dd1), 23 May 2019.
    - On confrontation, and how to handle conflicts [Applies to *most* people and situations, NOT all. Some people you *do* need to avoid and not confront, esp. if they are manipulative and/or continually contemptuous towards you, or if they have antisocial personality disorder (ASPD: https://www.webmd.com/mental-health/antisocial-personality-disorder-overview)].

"Programming isn't what you know; it's what you can figure out." <===
    - One of the many random quotes displayed on the Eclipse IDE splash screen during startup when you have the "Darkest Dark Theme with DevStyle 2002.5.5" plugin installed; seen 13 Apr. 2022
    - GS: in other words: really expert and skilled programmers do NOT know how to do everything! Rather, they simply know **how to figure it out**. They know that to solve the problem, they will have to:
        1. Identify the problem and the skills they need to solve it.
        2. Identify which skills they are lacking.
        3. Find resources and teach themselves these new skills, documenting as they go so they can A) refer to their notes later, and B) share them with others to help others learn too.
        4. Use the new skills to solve the problem!
      For a task which takes 4 days to "just do" if you already know how to do it, this total process might take:
        1. 2 days, spread throughout the project ["just-do-it"_time x 0.5]
        2. continuously being done
        3. 8~12 days ["just-do-it"_time x 2~3]
        4. 4 days ["just-do-it"_time]
        Total: 14~18 coding work days. 
          Since there are 10 work days per 2-week sprint, a standard 0.6 workload to account for meetings and fluff leaves you with 10x0.6 = 6 coding work days per sprint. So, 14 coding work days is 14/6 = **2.33 sprints** ~ 18/6 = **3 sprints**.
          
      vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv TIME ESTIMATION SKILLS vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
      ==> TIME-ESTIMATION SKILLS: a "4-day" task (meaning: 4 days if you know **exactly** how to do it) which you have never done yourself should take you **2~3 sprints**, for a total of 14~18 head-down coding work days! <==== TIME ESTIMATION SKILLS ====
      - Looking back at my work and time estimates, this seems very accurate, especially when factoring in writing unit tests, doing quick bench testing, and the code review process, as well as other unfamiliarities which pop up during the process, such as the build system or new syntax or libraries you aren't familiar with. 
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

"The best code is the 'done' code. (Meaning: it is functional [basic features] and works [runs/accomplishes the need])."
    - Gabriel Staples, 24 Jan. 2021

> Being in debt is hard. Being financially disciplined is hard. Choose your hard.  
> Communication is hard. Not communicating is hard. Choose your hard.  
> Obesity is hard. Being fit is hard. Choose your hard.  
> Marriage is hard. Divorce is hard. Choose your hard.  
> Life is rarely easy. It will be hard. But we can choose our hard.  
    - Swish Goswami, ~24 Dec. 2020 [on LinkedIn](https://www.linkedin.com/posts/swishgoswami_being-in-debt-is-hard-being-financially-activity-6747804403127910400-Clwh)

"If you love it, you'll teach yourself. If you don't love it, others teach you."
    - Yukitaka Yamaguchi, the "Tuna King", Youtube video: "The Tuna King Reigns at Tsukiji Fish Market — Omakase Japan", [11:33](https://youtu.be/trbl4RNgKO0?t=693)
"I have a great love for programming, so I taught myself."
    - Gabriel Staples, 18 Dec. 2020

"It's better to be done well and on time, than perfect and late."
    - Gabriel Staples, ~2008, while studying at the US Air Force Academy and trying to figure out how to balance time

Or, otherwise stated:
"Done well and on time is better than perfect and never."
    - Gabriel Staples--one of my main maxims. I learned this through my experiences at the US Air Force Academy where we were pressured into situations intentionally (primarily academic situations in our university studies, but also in other training environments and settings) where there literally wasn't time for the perfect answer--as happens frequently in war. So, if you're a struggling perfectionist, just get it done well enough and be done!

"Done is good enough."
    - Gabriel Staples (inspired by a conversation with Anton Scherbakov), 8 Dec. 2020; a variation to ["Done is better than perfect."](https://lifehacker.com/done-is-better-than-perfect-5870379).

"Document what you know when you know it."
    - [Great advice that I truly take to heart!]
    - One of the many random quotes displayed on the Eclipse IDE splash screen during startup when you have the "Darkest Dark Theme with DevStyle 2002.5.5" plugin installed

"I understand crossing your fingers is a form of debugging. If it doesn't pass, cross your fingers and try again."
    - said nobody ever
    (by Gabriel Staples, 25 June 2020)

"You are making progress if each mistake is a new one."
    - One of the many random quotes displayed on the Eclipse IDE splash screen during startup when you have the "Darkest Dark Theme with DevStyle 2002.5.5" plugin installed

"Programming isn't what you know; it's what you can figure out." <=====
    - One of the many random quotes displayed on the Eclipse IDE splash screen during startup when you have the "Darkest Dark Theme with DevStyle 2002.5.5" plugin installed

"Cost of copying code from Stack Overflow: $1. Cost of knowing which code to copy from Stack Overflow: $100k~$300k/year."
    - This is my rewording of a quote from Jessica Su, CS PhD student at Stanford (see: https://www.linkedin.com/posts/stevenouri_datascience-machinelearning-programming-activity-6696689805528571904-BIxM).

Me: "I am a documentation expert." Boss: "What about diagramming?" Me: "Oh...(foot in mouth)." [I'm great at documentation, just not drawing diagrams to demonstrate designs.]
New assertion: Me: "I am a foot-in-mouth expert." Boss: "Yep."
That should be a comic.

"There are two ways to code bug-free; only the third one works."
    - One of the many random quotes displayed on the Eclipse IDE splash screen during startup when you have the "Darkest Dark Theme with DevStyle 2002.5.5" plugin installed

"Confusion and clutter are the failure of design, not the attributes of information."
    - Edward Tufte
    - I first saw this posted on Adafruit.com's order checkout page, here, near the bottom-right: https://www.adafruit.com/index.php?main_page=checkout_success
      Keep refreshing the page for more quotes each time!

"The only valid measurement of code quality: WTFs/minute." 
    - Robert C. Martin
      Where I saw it: https://stackoverflow.com/users/583833/borgleader
    - *****My thoughts: this is actually a pretty insightful. I have VERY OFTEN looked at code and thought to myself: "What the heck does this mean!?" "Why are they doing that!?" etc. Apparently, I am not alone, which is good to know. I wasn't sure if it was just me, as I frequently wonder if most other programmers are just much smarter than me and I'm the only one "not getting it". This quote seems to indicate that is not the case. I have also noticed that the less often I have to wonder what the heck is going on when reading someone else's code, the better and higher-quality I consider that code to be, so I can affirm the validity of this quote!

"Any technology distinguishable from magic is insufficiently advanced."
    - One of the many random quotes displayed on the Eclipse IDE splash screen during startup when you have the "Darkest Dark Theme with DevStyle 2002.5.5" plugin installed
    - This is super funny! 😂 Actually made me laugh out-loud since they're making a joke of the other phrase similar to it.

"Maybe it's overconfidence, but I have a mentality that another human figured it out, so I can, too, even if maybe it takes me longer."
    - Sam Zeloof, home-made garage IC chip designer and fabricator, doing it in his parents' garage since high school
    - https://arstechnica.com/information-technology/2022/01/this-22-year-old-builds-chips-in-his-parents-garage/
  ..."The reason for doing it was honestly because I thought it would be funny,"" he says. "I wanted to make a statement that we should be more careful when we hear that something's impossible."


====================================================================================================
= My Thoughts on C++: =
====================================================================================================

"Every chance you get, eliminate a template. If you can write _clean_ code without using a template, do so. Simplicity is better."
    - Gabriel Staples, 22 Oct. 2020

My jab against C++ developers [a little "tongue in cheek", but also true]:
- A C developer prides himself in using a programming language to produce a desired outcome. 
- A C++ developer prides himself in producing the world's most complicated language **as** the desired outcome.

C++'s syntax alone is, unfortunately, a never-ending story [C++'s syntax is nuts!]: 
    "C++ is completely nuts."
        - Gabriel Staples, 15 May 2020. See here: https://stackoverflow.com/questions/47002799/what-does-the-ampersand-at-the-end-of-member-function-signature-mean/47003980?noredirect=1#comment109357350_47003980
    "After having used C++ since the late 80's, I still feel the same way [that "C++ is completely nuts"]. As more and more corner-case niceties are added to the endless string of value-types, deductions, ranges, views, chronos, etc.. it feels a lot more like Python than it does C++. Don't get me wrong, I'm not saying additional features and capabilities are a bad thing, there is someone out there that will use the feature, but to say you can remain current without continually re-learning C++ is just that -- nuts. The language seems to have fragmented into an ever increasing number of specialized subcomponents."
        - David C. Rankin, 3 Sept. 2023, experienced software developer, engineer, lawyer, and open-source advocate. See here: https://stackoverflow.com/questions/47002799/what-does-the-ampersand-at-the-end-of-member-function-signature-mean/47003980?noredirect=1#comment135796477_47003980

I frequently tell people:
> If the syntax of C is like Spanish, the syntax of C++ is like Spanish + English + French + Italian + Portuguese + German.
> 
> And the problem is that even if you write the most perfect and beautiful Spanish in C++, the Frenchers will hate it. And even if you write the most beautiful and perfect French in C++, the Germans will hate it.
> 
> That's the problem with C++.  
    ~ Gabriel Staples
    Written down 28 Sept. 2022, even though I've been telling people this for a couple years now.

23 Oct. 2020:

Note: the above quote above (and repeated just below) about eliminating templates does NOT mean: "don't use templates". If you have a function that truly needs to work for many data types, that is a good use for a template, so _use a template!_ BUT, if you can simply reduce your plethora of types and go back to a little more simplicity, something more like _modern_ C (1), between old-school C and modern "go-nuts" C++, you are better off. It seems to me the simplicity will pay off dividends in the long run, enabling you ultimately to have fewer hurdles for new developers to contribute, faster progress for the whole team, and safer code because it is understandable and more likely to be correct and do what you want it to do. 

This is my hypothesis. I am still testing it, but right now, that's what I recommend: "every chance you get, eliminate a template."

(1) For some examples of code I've written where I demonstrate aspects of what I mean when I say "modern C", and/or "simple C++", see here:
    1. [my answer] https://stackoverflow.com/questions/3965279/opaque-c-structs-how-should-they-be-declared/54488289#54488289
    2. [my answer] https://stackoverflow.com/questions/34196663/stm32-how-to-get-last-reset-status/54728664#54728664
    3. [my answer] https://stackoverflow.com/questions/21856025/getting-an-accurate-execution-time-in-c-micro-seconds/49066369#49066369
        - NB: this is C++, but this is a **great** illustration of what I mean when I say "simpler types" with fewer templates! Instead of this craziness: `std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::high_resolution_clock::now().time_since_epoch()).count()`, PLEASE just use `uint64_t microseconds` or `uint64_t us` instead!
        - See also my comments underneath my answer. 
        - This is also an **excellent** demonstration of what I mean when I say I aim to "have fewer hurdles for new developers to contribute". The `std::chrono` library is a HUGE hurdle for someone to conquer when moving from C to C++! IT **ALONE** could set back an expert C developer from making strong C++ contributions **FOR _WEEKS_**! I say: "Every chance you get, eliminate a template. If you can write _clean_ code without using a template, do so. Simplicity is better."


17 Sept. 2020:

As compared to C, or even better, "C+" (more on this later), I personally dislike the "hard-core" C++ "type-safety-first" mentality common to modern application-level C++.

But, I'm still forming an opinion, and have much to learn.

As an embedded software developer first, I definitely prefer a more C-like style, which I call "C with classes", or "C+", when programming with the C++ compiler. This consists of using many C styles but with a C++ compiler and with C++ classes, C++ features like default values in function prototypes and structs, function overloading, etc. I think C++ has many wonderful things to offer, but is just too huge. Using only C, on the other hand, is just too redundant and limiting. The C++ compiler has many beautiful and wonderful features which can make programming a true joy, when done in the "C+" style I describe above.

Since I speak multiple languages (English, Spanish, + quite a bit of French, and I read and write Arabic) and have a passion for learning and studying foreign languages and cultures, I frequently make the following analogy to foreign languages:

    Imagine **C is Spanish**. It is well-defined, well-scoped, and follows nice, fixed rules and patterns in its syntax. Its syntax follows rules very well, and when there are exceptions to these rules, you can write them out in a list and that's it! Those are the rules, and those are the exceptions to those rules! Done! At the architectural level, many options exist, but a few well-accepted architectures have arisen.

    **C++ is Spanish, German, French, English, Italian and Portuguese** all rolled into one. The problem is that if you write perfect Spanish in C++, the (Portuguese + French)ers in C++ will tell you how horrible your code is because it looks like Spanish, even if the Spanish you wrote and compiled with the C++ compiler is perfect, flawless, bug-free, functional C++, **since C++ includes Spanish**. C++ is HUGE. You have many many ways to use C++, and no matter how long you study it, you have never even covered all of its _syntax_, let alone its extensive libraries and multiplicitous architectural options.

In C, architecturally, I am quite familiar with and fond of "object-based C". I have written a thorough example of this architectural style here: https://stackoverflow.com/questions/3965279/opaque-c-structs-how-should-they-be-declared/54488289#54488289. An alternative "object-based C" style exists which allows static memory allocation instead, for your "objects", and I'd probably prefer this more over what's in my answer, but what's in my answer happened to be what I was more familiar with. This "object-based" C style does not prohibit procedural code and functions mixed throughout.

In programming paradigms, I am fond mostly of **procedural** programming, which is a subset of **imperative** programming. Here's what I wrote in a comment [under this answer](https://stackoverflow.com/questions/6295148/what-is-the-opposite-of-oop/6295260#6295260) to the question of, "What is the opposite of OOP? [Object-Oriented Programming]":

    > I'd say based on what the asker is after, **procedural** is the opposite of **object-oriented** programming. Procedural is a subset of **imperative**, but more narrowly defined as being imperative + relying on blocks & scope (source: https://en.wikipedia.org/wiki/Procedural_programming#Imperative_programming). With this in mind, in a sense, C (a primarily procedural programming language) is the opposite of C++ (a primarily object-oriented programming language).

So, I prefer **procedural** programming to pure OOP.  If taken too far, OOP gets huge, ugly, and utterly obnoxious to use. This contributes to my occasional hatred towards C++, when all I want to use is "C+." C++, for instance, can make better and cleaner and more beautiful **procedural** code than C could ever dream of. Some of the aspects of C++, like function overloading and setting default members in structs, are wonderful to use. Regarding the ugliness of OOP, however, which for some reason is the dominant form of C++ even when it doesn't make any sense for the problem being solved and ends up creating a dozen singleton classes everywhere, Joe Armstrong, creator of Erlang, had the following to say:

    > I think the lack of reusability comes in object-oriented languages, not functional languages. Because the problem with object-oriented languages is they’ve got all this implicit environment that they carry around with them. **You wanted a banana but what you got was a gorilla holding the banana and the entire jungle.**

    > If you have referentially transparent code, if you have pure functions — all the data comes in its input arguments and everything goes out and leave no state behind — it’s incredibly reusable.

    (Source: ["Coders at Work" book](https://amzn.to/2LUe3aO), requoted by John D. Cook, PhD, here: https://www.johndcook.com/blog/2011/07/19/you-wanted-banana/)

So, when using the C++ compiler, please, I don't need the whole gorilla holding the banana, and the entire jungle too! Sometimes, simplicity is best. Step back for a moment and consider trying to create something a little less OOP, a little less type-safe (because the extreme complexity of overly-type-safe code can be very dangerous too!), a little more simple and usable and procedural, and in fine, a litte more "C+".

Also, I think my core skillset and interests lie in the realm of programming on microcontrollers, and that paradigm is inherently bad for use with the STL and is tightly coupled with and benefited by the use of raw pointers, raw structs, raw buffers, and register memory mapping. I am generally opposed to increased type safety at the cost of reduced simplicity / greater verbosity and greater complexity. This frequently puts me at odds with many other C++ developers, but when I look at the massively-complex systems produced by choosing type-safety first, it leaves a lot to be desired, and the increased mental overload, potentially-increased propensity for human errors, and decreased speed isn't worth the cost. I hypothesize that reducing complexity and choosing simplicity over type-safety will ultimately make your code cleaner and safer, more efficient, easier to maintain, less expensive, and better all around.


====================================================================================================
= Time Estimation of Projects/Tasks/Tickets/Pull-Requests: =
====================================================================================================

THE PROBLEM:
I find that I am pretty bad at time estimations, so I want to jot down some notes here to help me think about the problem better. I'm frequently off by as much as a factor of 2x to 5x, which is horrible. Ex: I estimate a certain task will take 2 days. I forget, however, that that is **ideal**, uninterrupted, "in the zone" time, and even then it's optimistic because I'm **hoping** to get it done sooner by just working really hard, or really long hours. So, that ends up being two 13 or 14 hour days, which sucks and is unsustainable, and that's only to get my project prototyped and pushed for review, NOT to get it also tested, approved, or merged, or in the case of free-lance work, polished off and fully handed over and paid for.

THE FIX:
Have realistic time estimates. So, if I think to myself "this'll take 2 days," then I need to remind myself: "Oh, wait, that's 2 **ideal** days, possibly even 13 hours each day. This isn't BattleBots anymore. I can't work like that." "Ok, so this is really 4 days + 1 day for testing. ===> This'll take 5 days. <=== SOLVED!"

A programming task/project might take:

  * 2 ideal "Battlebots" prep/build days of work. That means 13-hour days with no human interaction, little food, no showers, and pure focus. This isn't practical, and definitely doesn't work in a corporate environment, **especially** where others control your work and determine whether or not it's "good enough" (or, more frequently: it must meet their subjective standards) to land on the code base.

So, the REAL ESTIMATE IS:   <======== THIS! ======= (2 days is actually 5 days--possibly even 6)

  * 2 normal human (8 hrs.) days of work for me to do the main coding (bug fix or new feature)
  * + 2 days for writing unit tests, doing bench or field testing, etc.
  * + 1 day *minimum* for review, fixing, merging the code, etc.
  = 5 days total. You may even throw in a 6th day (ie: 1 more day) for researching, as that is inevitably required if there are a lot of unknowns or you are not already **intimately** familiar with the code, project, technology, libraries, code base, etc.
  - AND THEN, ***ON TOP OF THIS***, you must assume that these 5 days of work will be done at 60% efficiency, due to meetings and things, meaning it will actually take 5/0.6 = 8.33 days, or 1 week 3.33 days, assuming 5-day work weeks and 8-hr work days.
  **************************************************************************************************
  vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
  So...in actual, real-life timeline days for project planning and making Gant charts and finding critical paths and things, "2 days" of work (according to how I used to think about work in my BattleBots-mentality build days) will take **1 week 3.33 days** in the corporate environment or work-place, where you work 5-day work weeks, 8~9-hr. days, at 60% time efficiency. <===== THIS IS THE KEY TAKEAWAY! ===
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  **************************************************************************************************

***Start multiplying all your estimates by 2.5 from now on*** until you can get this cemented into your brain about how real-world projects go, especially when you're working on a team or working with others, and even more-so when you don't own the project and get to make every executive decision by yourself like your own little project dictator. This is the reality of corporate programming/software development, and probably how it would be in the true customer-focused world as well, where you are not essentially your own customer and micro-dictator.

ANOTHER WAY TO LOOK AT IT:
(ESTIMATING EXAMPLE/COMPARATIVE ANALYSIS):
(In parenthesis is an example number of days for each task for relative comparison between these tasks):
  1. (2 days) doing the actual coding work and pushing my code change for review, considering 8 hr. days where I might only be productive for 4 or 5 of those hrs., or ~60% max efficiency due to meetings and things.
  2. (1 day) fixing broken modules or having to dig into things I didn't expect, due to large, complex projects; this might include having to do additional research and things
  3. (2 days) writing unit tests and doing testing; ex: bench, running and fixing unit tests, etc.
  4. (1 day) code review and merging, assuming ideal conditions (this could easily be 2 to 6+ days if a bunch of changes are requested)

  Total = 2 + 1 + 2 + 1 = 6 days of actual work for a task which I might take only 2 days to do if it was a 100% self-owned project I am familiar with, in my personal time. And...if big changes are requested during code review, these 6 days quickly become 7 to 11+ days, especially if new bench and field testing and new unit tests are required for a major change or re-architecture as well.
  BREAKDOWN:
    1. 2/6 days = 1/3 = 33% of my total time is actually coding up the new feature or bug fix.
    2. 1/6 days = 17% might be just researching new tools or code syntax or modules or tools or whatever, again, in ideal conditions. In completely brand-new conditions this could be as high as 2 or 3 up to 5 or 6+ days.
    3. 2/6 days = 1/3 = 33% is writing new tests or doing testing
    4. 1/6 days = 17% is getting review, writing descriptions and updating documentation, and that's assuming NO or MINIMAL changes are requested. If they request an entire re-architecture or rip-up, this could easily expand to 2 or 3+ days just to go back and repeat step 1 above ALONE, which originally took 2 days. Then, you'd have to redo steps 2 to 4 as well which would take ANOTHER 4+ DAYS ON TOP OF THAT. So, if major re-architecture is required, this is a good time to notify your boss (or customer, if you are your own boss/a freelancer or sole proprietor), and inform him/her of the delay, request more time, and re-evaluate how code review and new design is handled and discussed on the team, as it *may* (but doesn't necessarily) indicate a failure to plan ahead and communicate in advance, which could need addressing at a procedural/systemic level.

I talked to a smart guy who said, ***"no ticket [task] takes less than 2 hrs."*** He said, "If I have a task to send an email, I schedule 2 hours"..."because inevitably you will be interrupted or something will happen and that 2 hours will quickly be filled up."
KEY TAKE-AWAY: scheduling *at least* 2 hours for even the most minute of tasks is required if you hope to become a person who can (quote/un-quote) "get things done 'on time'". <====== KEY TAKEAWAY! ======

So, ***NEVER SCHEDULE LESS THAN 2 HRS FOR ANYTHING--NOT EVEN THE MOST TRIVIAL OF TASKS AT WORK (OR ON OTHER PAID OR SCHEDULE-BASED PROJECTS)!*** AND IF SOMETHING MUST LAND ON A LARGE CODE BASE WHERE LOTS OF OTHER PEOPLE ARE INVOLVED, MAKE IT NO LESS THAN 4 HRS.! <========== REMEMBER THIS! ==========


====================================================================================================
= Stack Overflow and Other Stack Exchange Sites: =
====================================================================================================

== How to NOT get suspended from Stack Exchange sites: ==
[SEE ALSO THE UPDATE/OFFICIAL CORRESPONDENCE BELOW!]

1. Follow the **Full Disclosure rule:** EVERY time you post ANYTHING to a personal or professional site, project, tool, or product to which you are affiliated, ESPECIALLY when you solicit donations, have ads, sell it, or otherwise might many money from it, even if only $1 over the course of a year, EXPLICITLY STATE YOUR AFFILIATION! Ex:

    "Full Disclosure: I wrote/helped write/build/help build/maintain/help maintain this [tool] which can do ___."

  Or perhaps just:

    "Full Disclosure: I wrote this."

  Then state how and why it is useful and relevant to the Original Poster's exact question, and not just a random act of self-promotion or spam.

2. "**You have to show your tool/library actually solves the problem:** that means you have to write the 10 lines of code that call your library, and it is helpful if you **show an actual result,** and even better if you [show] a result based on the code in [the OP’s (Original Poster's) example code]."
  ~Source: direct quote from Ira Baxter (this quote isn't from here, but here's who he is: https://stackoverflow.com/users/120163/ira-baxter).

  My own summary of this quote: _provide an actual example, **including output or screenshots**, of your external tool, library, or resource. Preferably make it exactly specific to the question at hand._

  This demonstrates your tool 1) actually works, and 2) actually solves the OP's problem and hence isn't just random spam or random self-promotion.

=== Related References, Sources, and Resources: ===
1. [How to not be a spammer](https://arduino.stackexchange.com/help/promotion) - very important link which backs up the above two main rules! Two key takeaways are: 1) "you _must_ disclose your affiliation in your answers", and 2) "Don't tell - show!"..."demonstrate a solution rather than simply asserting the problem can be solved." They also have other great points, such as "always solve the asker's problem," and "avoid poorly-written questions", because a well-written answer to a poorly-worded question looks even more spammy to many other people than a poorly-worded answer to a poorly-worded question, oddly enough (personal note: this is an example of the conundrum of "if it looks like you tried too hard, it's probably because you're getting paid to do it" [and therefore what you say isn't as true or as valid], which is asinine and ridiculous but this is what "normal" people think apparently).
2. https://arduino.stackexchange.com/help/behavior
3. [very interesting real-life case] https://meta.stackexchange.com/questions/57497/limits-for-self-promotion-in-answers/59302#59302
4. [my own question] https://meta.stackexchange.com/questions/351349/is-the-new-software-recommendations-stack-exchange-a-trap-to-catch-people-who?noredirect=1#comment1176694_351349

See also:
1. https://stackoverflow.com/help/deleted-answers
2. https://stackoverflow.com/help/locked-posts

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
== UPDATE: Official and personal correspondence with me from a Stack Overflow employee (not moderator, but actual, paid employee): ==
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> In terms of official guidance regarding your personal website links being included, I would recommend you to read these two answers:
> 
> 1. [What is the exact definition of "spam" for Stack Overflow?](https://meta.stackoverflow.com/questions/260638/what-is-the-exact-definition-of-spam-for-stack-overflow/260641#260641)
> 2. [What are the "spam" and "rude or abusive" (offensive) flags, and how do they work?](https://meta.stackexchange.com/questions/58032/what-are-the-spam-and-rude-or-abusive-offensive-flags-and-how-do-they-wor/58035#58035)
> 
> You can include links to your site, but please be careful with that and make sure that:
> 
> 1. The person can understand the answer fully without having to follow the link.
> 2. You disclose that it is your personal website. [My notes: according to the 2nd link he gave me just above, "a simple 'my' may suffice", so simply saying something like this (emphasis added): "refer to **my website** here for more information on ___" is perfectly acceptable].

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
== How to appeal a Code of Conduct violation or suspension if you ever get wrongfully suspended from a Stack Exchange/Stack Overflow Site: ==
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Examples:

1. From any page on https://arduino.stackexchange.com/: scroll to the bottom of the page --> click the "Contact" link (https://arduino.stackexchange.com/contact) --> click the "What can we help you with?" dropdown menu --> choose the "I want to appeal a Code of Conduct violation" option --> politely explain your situation and submit it. Note that your description must be < 5000 chars, which apparently includes any HTML/XHTML/XML? post-formatting they add to your description, so that gives you about 4800~4900 or so chars to write your description. This will be sent to a paid Stack Overflow employee, *not* an unpaid community moderator, a Jira ticket will be opened for your case, you will be sent an email with instructions to open a Jira account to monitor and reply to your case, and they will work on it over the next 3 to 4 or so weeks. 

2. From any page on https://stackoverflow.com/: scroll to the bottom of the page --> click the "Contact Us" link (https://stackoverflow.com/company/contact) --> click the "contact us" link now at the top of the page under the "Support & Feedback" heading (https://stackoverflow.com/contact?referrer=https%3a%2f%2fstackoverflow.com%2f) --> --> click the "What can we help you with?" dropdown menu --> choose the "I want to appeal a Code of Conduct violation" option --> politely explain your situation and submit it (see above for more details and notes about the character limits for the description section).


====================================================================================================
= Doxygen: =
====================================================================================================

See other examples here:
1. http://www.doxygen.nl/manual/commands.html
1. https://stackoverflow.com/questions/15398711/whats-the-right-way-to-reference-a-parameter-in-doxygen/56745246#56745246
1. https://stackoverflow.com/questions/34196663/stm32-how-to-get-last-reset-status/54728664#54728664
1. https://stackoverflow.com/questions/385975/error-handling-in-c-code/59221452#59221452

Here's a bunch of Doxygen examples for easy copy/pasting into your code when you are frequently writing Doxygen:

Full Doxygen function header example:

    /// \brief          A brief one or two line description of the function.
    /// \note           An important note the user should be aware of--perhaps many lines.
    /// \details        Extra details.
    ///                 Perhaps
    ///                 even
    ///                 a long
    ///                 paragraph.
    /// \param[in]      var1            Description of variable one, an input
    /// \param[in]      my_longer_var2  Description of variable two, an input
    /// \param[out]     var3            Description of variable three, an output (usu. via a pointer
    ///                                 to a variable)
    /// \param[in,out]  var4            Description of variable four, an input/output (usu. via a
    ///                                 pointer) since its initial value is read and used, but then
    ///                                 it is also updated by the function at some point
    /// \return         Description of return types. It may be an enum, with these
    ///                 possible values:
    ///                 - #ENUM_VALUE_1
    ///                 - #ENUM_VALUE_2
    ///                 - #ENUM_VALUE_3
    my_enum_t myFunc(int var1, int var2, int* var3, int* var4)
    {
        // function implementation here

        my_enum_t error = ENUM_VALUE_1;

        // Check for NULL pointers
        if (!var3 || !var4)
        {
            // var3 or var4 are NULL pointers, which means they can't be dereferenced
            error = ENUM_VALUE_2;
            goto done;
        }

        if (something_else)
        {
            error = ENUM_VALUE_3;
            goto done;
        }

    done:
        return error;
    }

You may also use `@` instead of `\`:

    /// @brief          A brief one or two line description of the function.
    /// @param[in]      var1            Description of variable one, an input
    /// @param[in]      my_longer_var2  Description of variable two, an input
    /// @param[out]     var3            Description of variable three, an output (usu. via a pointer
    ///                                 to a variable)
    /// @param[in,out]  var4            Description of variable four, an input/output (usu. via a
    ///                                 pointer) since its initial value is read and used, but then
    ///                                 it is also updated by the function at some point
    /// @return         None
    void myFunc(int var1, int var2, int* var3, int* var4)
    {
        // function implementation here
    }

And here's this shorter version again now with `\` again instead of `@`:

    /// \brief          A brief one or two line description of the function.
    /// \param[in]      var1            Description of variable one, an input
    /// \param[in]      my_longer_var2  Description of variable two, an input
    /// \param[out]     var3            Description of variable three, an output (usu. via a pointer
    ///                                 to a variable)
    /// \param[in,out]  var4            Description of variable four, an input/output (usu. via a
    ///                                 pointer) since its initial value is read and used, but then
    ///                                 it is also updated by the function at some point
    /// \return         None
    void myFunc(int var1, int var2, int* var3, int* var4)
    {
        // function implementation here
    }

And the more compact versions of the above (assumes shorter parameter names, and only [in] or [out] params but no [in,out] params):

    /// @brief      A brief one or two line description of the function.
    /// @param[in]  variable_1  Input parameter
    /// @param[in]  variable_2  Another input parameter
    /// @param[out] variable_3  Output parameter
    /// @param[out] variable_4  Another output parameter
    /// @return     None
    void myFunc(int var1, int var2, int* var3, int* var4)
    {
        // function implementation here
    }

    /// \brief      A brief one or two line description of the function.
    /// \param[in]  variable_1  Input parameter
    /// \param[in]  variable_2  Another input parameter
    /// \param[out] variable_3  Output parameter
    /// \param[out] variable_4  Another output parameter
    /// \return     None
    void myFunc(int var1, int var2, int* var3, int* var4)
    {
        // function implementation here
    }


====================================================================================================
= Python Docstrings: =
====================================================================================================

Useful for documenting Python functions and classes. Python docstrings are like the "doxygen" of Python. ~GS

References:
1. https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format
1. My own examples from my own code: https://github.com/ElectricRCAircraftGuy/git-tree/blob/master/git-tree.py

General format:

    def my_func(self, param1, param2, param3, param4):
        """
        Function to do whatever.

        Parameters:
            param1 (string): string to do ___
            param2 (int):    integer between the range of __ and __ to be used for __
            param3 (list of MyClass objects):  list of myClass objects for __
            param4 (dict of string:string key:values): map from something1 to something2, to be used
                for __ and __ in order to __

        Returns:
            dict of string:MyClass key:value pairs mapping a name string to a MyClass object
        """

Another random "Returns" example:
        """
        Returns:
            (string, list of dicts, list of numbers) tuple
        """

Example from my own code (see my git-tree.py link above):

    def __init__(self, name, parent = None):
        """
        Constructor to create a new Node.

        Parameters:
            name (string):  the name of this node
            parent (Node):  the parent node of the node being created; note: obviously the parent node must already
                exist in order to be passed in as a parameter here

        Returns:
            NA
        """
        # Do constructor stuff here

Alternative General format [MY PREFERRED PYTHON DOCSTRING FORMAT NOW I THINK]:
- Note: see Python Built-in Exceptions here: https://docs.python.org/3/library/exceptions.html

    def my_func(self, param1, param2, param3, param4):
        """
        Function to do whatever.

        For python exception-handling help and examples, see: 
        https://www.w3schools.com/python/python_try_except.asp

        -----------
        Parameters:
        -----------
        param1: str
            String to do ___.
        param2: int
            Integer between the range of __ and __ to be used for __.
        param3: list of MyClass objects
            List of myClass objects for __.
        param4: dict of {string:string} key:value
            Map from something1 to something2, to be used for __ and __ in order to __.
        param5: list of ints
            List of integers representing __.

        --------
        Returns:
        --------
        dict of {string:MyClass} key:value pairs 
            Map of a name string to a MyClass object.
        
        -------
        Raises:
        -------
        TypeError:
            If `param2` is not an integer.
        ValueError:
            If input parameter `param2` has the right type but an invalid (out-of-range) value. 
            See: https://docs.python.org/3/library/exceptions.html#ValueError
        SystemError:
            If whatever (detailed description goes here).
        """

        if not type(param2) is int:
            raise TypeError("param2 must be an int.")

        if not (0 <= param2 <= 100):
            raise ValueError("param2 must be between 0 and 100, inclusive.")

        try:
            # do some stuff here
        except SystemError:
            print("Some descriptive message; output_data = \n{}.".format(output_data))
            raise  # re-raise the exception to crash the program

        my_class = MyClass(param1, param2)
        some_str = "hello"
        my_class2 = MyClass(param1 + some_str, param2 + 724)
        
        my_dict = {param1: my_class, some_str: my_class2}

        return my_dict


====================================================================================================
= bazel: =
====================================================================================================

Good example to get started in Bazel: https://github.com/ElectricRCAircraftGuy/eRCaGuy_gtest_practice

Config files:
1. BUILD (old, but still widely-used)
1. BUILD.bazel (new, but still not widely-accepted, and is somewhat debated) [see note 1 below]
1. WORKSPACE
1. .bazelrc in your workspace directory (next to the main WORKSPACE file); see: https://docs.bazel.build/versions/master/guide.html#where-are-the-bazelrc-files
    1. user.bazelrc in your workspace directory (next to the main .bazelrc file); see: https://docs.bazel.build/versions/master/best-practices.html#bazelrc. Add an entry for `user.bazelrc` to your ".gitignore" file for your git repo, so that this becomes a custom user bazelrc file which does NOT get checked-in to the main git repo! Then, in your main git repo's ".bazelrc" file, add the command `try-import user.bazelrc` at the end to automatically import a user's custom "user.bazelrc" file if it exists!

Notes:
[1] GS: for all new projects, I recommend using `BUILD.bazel` over `BUILD`. See here:
    1. [In Docs: clarify BUILD vs. BUILD.bazel #4517](https://github.com/bazelbuild/bazel/issues/4517) - brings up the fact this is an on-going debate.
    1. https://docs.bazel.build/versions/master/build-ref.html#packages - shows both as valid options: `BUILD.bazel` and `BUILD`.

Bazel Online Documentation:
1. See all Bazel commands here (ie: `bazel --[startup options] <cmd> --[cmd options]`): https://docs.bazel.build/versions/master/command-line-reference.html#commands
1. See all Bazel options online here! https://docs.bazel.build/versions/master/command-line-reference.html. Ex:
    1. Sub-categories of options:
        1. All `bazel build` options: https://docs.bazel.build/versions/master/command-line-reference.html#build-options
        1. All `bazel test`  options: https://docs.bazel.build/versions/master/command-line-reference.html#test-options
        1. All `bazel query` options: https://docs.bazel.build/versions/master/command-line-reference.html#query-options
        1. etc.
    1. To pass in Java Virtual Machine (JVM) options, such as heap size, as Bazel startup options: https://docs.bazel.build/versions/master/command-line-reference.html#flag--host_jvm_args
            --host_jvm_args=<jvm_arg>
    2. To limit how many of your local CPUs Bazel can use. Note that HOST_CPUS here is probably (and usually is) 1/2 the number of cores you have. So, if gnome-system-monitor shows you have 8 cores, you may only have 4 CPUs.: https://docs.bazel.build/versions/master/command-line-reference.html#flag--local_cpu_resources
            --local_cpu_resources=<an integer, or "HOST_CPUS", optionally followed by [-|*]<float>.> default: "HOST_CPUS"
        NB: THIS cpu resource limiter option above doesn't actually work very well! Frequently, even with it in-use, the CPU usage will still lock out at 100% for periods of many minutes at a time! To prevent this, just use the Linux `cpulimit` program in a separate terminal!:
            cpulimit -p <pid> -l 500 # limit your bazel build to 62.5% max CPU usage on an 8-core machine
        Read more about the above command in the "Limit CPU usage" section of this document down below.
    3. To limit local RAM usage: https://docs.bazel.build/versions/master/command-line-reference.html#flag--local_ram_resources
            --local_ram_resources=<an integer, or "HOST_RAM", optionally followed by [-|*]<float>.> default: "HOST_RAM*.67"
    4. To disable remote caching: https://docs.bazel.build/versions/master/command-line-reference.html#flag--remote_cache
            --remote_cache=""
    1. To share build outputs between users, for saving hard drive space, use bazel startup option:
            --output_user_root=<path>
       See: https://docs.bazel.build/versions/master/command-line-reference.html#flag--output_user_root
       Ex:
            bazel --output_user_root="/home/some_other_user/.cache/bazel" build //...
1. "A user's guide to Bazel" - https://docs.bazel.build/versions/master/guide.html
    1. Specifying targets to build (`bazel build //...` [build the whole project], `bazel build //:all` [build just the top-level build targets], etc.) -
       https://docs.bazel.build/versions/master/guide.html#specifying-targets-to-build
1. Macros (Bazel build rule macros--used to generate build targets):
    1. Macros: https://docs.bazel.build/versions/master/skylark/macros.html
        1. Expanding macros [macro expansion in Bazel; Bazel macro expansion; expanding macros in Bazel; Bazel expanding macros]: https://docs.bazel.build/versions/master/skylark/macros.html#expanding-macros. To see their expanded forms:

            time bazel query --output=build //path/to/my/target/... > out.txt  # Store the expanded form of all macros/build rules into out.txt
            subl out.txt  # open out.txt in Sublime Text 3

    1. Creating a macro: https://docs.bazel.build/versions/master/skylark/tutorial-creating-a-macro.html
1. Bazel "Make" Variables [bazel make variables]: *****https://docs.bazel.build/versions/master/be/make-variables.html
    1. Ex: `my_attr = "prefix $(FOO) suffix"` = insert the Bazel "Make" (GNU Make-like) variable `FOO` into this attribute.
    Bigger example, with a `genrule()` (https://docs.bazel.build/versions/master/be/general.html#genrule) which runs during `bazel build` to run some bash command-line call, during the build, to do something like auto-generate some files required as C++ `srcs` and headers later in the build, for example:

        # =================================
        # "src/module1/BUILD" file:
        # =================================

        # `py_binary()`: see: https://docs.bazel.build/versions/master/be/python.html#py_binary
        py_binary(
            name = "generate_files",
            main = "scripts/generate_files.py",
            srcs = [
                "scripts/generate_files.py",
                "scripts/do_xyz.py",
            ],
            deps = [
                "//some/module:py_library_rule",
            ],
        )

        # =================================
        # "src/module2/BUILD" file:
        # =================================

        # The Python script run by the genrule below will need to read in and parse all of these files
        filegroup(
            name = "data_files_for_genrule",
            srcs = [
                "data/file1.txt",
                "data/file2.csv",
                "data/file3.py",
                "yaml/yaml1.yaml",
                ":another_file_group",
            ],
        )

        # See what the variable-substituted version/output of this is with:
        #       bazel query --output=build //src/module2:run_this_python_script_during_build
        genrule(
            name = "run_this_python_script_during_build", # <== (that's what a genrule does!)
            srcs = [
                ":data_files_for_genrule",  # a filegroup from this same BUILD file
                "//some/package:another_filegroup",  # a filegroup from another package
                "data/file10.txt",  # a local file; relative path from this BUILD file's dir
            ],
            # Files not in this `outs` Starlark (Python3-like) list will be deleted by Bazel after
            # this genrule() runs, so any files which this script generates MUST be in this list
            # for them to persist and be available for later parts of this build! So, add all
            # (generated-by-this-script) files to `outs` that you need to NOT be deleted by Bazel!
            outs = [
                "mymodule/autogen/file1.h",
                "mymodule/autogen/file1.cpp",
                "mymodule/autogen/file2.cpp",
                "mymodule2/autogen/file1.csv",
                "mymodule2/autogen/file1.yaml",
            ],
            # See meaning of `execpath`, used in this Bazel "Make" variable, here:
            # https://docs.bazel.build/versions/master/be/make-variables.html#predefined_label_variables
            cmd = (
                '$(execpath //src/module1:generate_files) '
                '--option1 "something" '
                '--option2 "something else" '
                '--option3 12973 '
                # Pass in all `outs` items to the script itself, if desired, to process. `OUTS` here
                # is a Bazel "Make" variable.
                # See: https://docs.bazel.build/versions/master/be/make-variables.html
                '--bazel_outs "$(OUTS)" '
                # Pass in the Bazel `srcs` list too via this Bazel "Make" variable. See link above.
                '--bazel_srcs "$(SRCS)" '
            ),
            visibility = [
                "//visibility:private",
            ],
        )

    NOTES:
    In the `genrule()` above, you could also do the command like this:
            cmd = (
                # I *think* this path relative to the project root dir would work:
                '//src/module1/scripts/generate_files.py '
                # OR if the file was local to this module, just call it with a path relative to this module:
                'scripts/generate_files.py '
                # Instead of this:
                # '$(execpath //src/module1:generate_files) '
                '--option1 "something" '
                '--option2 "something else" '
                '--option3 12973 '
                '--bazel_outs "$(OUTS)" '
                '--bazel_srcs "$(SRCS)" '
            ),

    ...or like this, if you wanted to join the command as a list of strings (joined by a single
    space) instead. Notice the deleted space before the ending single quote on each line, and the
    added comma after the single quote to make this a list of strings now instead of a
    continuous, multi-line string!
            cmd = ' '.join([
                '$(execpath //src/module1:generate_files)',
                '--option1 "something"',
                '--option2 "something else"',
                '--option3 12973',
                '--bazel_outs "$(OUTS)"',
                '--bazel_srcs "$(SRCS)"',
            ]),

    REFERENCES FOR THE ABOVE EXAMPLE:
    1. *****https://docs.bazel.build/versions/master/be/make-variables.html
    1. https://docs.bazel.build/versions/master/be/python.html#py_binary
    1. https://docs.bazel.build/versions/master/be/general.html#genrule
    1. https://docs.bazel.build/versions/master/be/general.html#filegroup
    1. EXAMPLE `genrule()` & BUILD file from Bazel, with a custom rule from a custom `defs.bzl`
       file!: https://github.com/bazelbuild/examples/blob/master/make-variables/testapp/BUILD

1. `bazel query` example to show *exactly* what the above `genrule()` would look like AFTER full
   variable substitution into it:
        bazel query --output=build //src/module2:run_this_python_script_during_build
1. See what predefined Bazel "Make", and Bazel environment variables exist for your Bazel build environment.
   See: https://docs.bazel.build/versions/master/be/make-variables.html#predefined_variables
        bazel info --show_make_env [build options] = shows all predefined "Make" variables in all caps at the top, and bazel environment variables in lowercase thereafter
1. See here for details on the Bazel "output directory layout"!: https://docs.bazel.build/versions/master/output_directories.html
   See also the `bazel info` commands just below!

bazel info --show_make_env [optional: build options]
bazel info --show_make_env
    see just above! It shows all predefined Bazel "Make" variables [bazel make variables] in ALL CAPS at the very top, and then Bazel environment variables, such as genfiles, bin, etc. output and build paths right after that! See here for details on the Bazel "output directory layout"!: https://docs.bazel.build/versions/master/output_directories.html <==== VERY USEFUL TO BE ABLE TO SEE WHERE ALL BUILD OUTPUT WILL BE PLACED FOR A GIVEN SET OF BUILD SETTINGS! ====
bazel info
    <==== VERY USEFUL! ====
    Show ALL the `bazel info` variables at once! 
    Similar to the above, but show JUST the Bazel environment variables (output/build dirs and things), and NOT the Bazel "Make" variables as well! 
    For `bazel info` options, see here: https://docs.bazel.build/versions/master/command-line-reference.html#info.
bazel info bazel-bin
    show the full path to the bazel output "bin" directory

bazel help
    See generic bazel help information, including the `bazel help info-keys` cmd.
bazel --help
    Same as above
bazel help info
    See bazel help for the `bazel info` cmd used just above! This is a lot of information, so, even better: pipe it to `less`!:
bazel help info | less -RFX
    Same as above, except piped to `less` for easy viewing. Note that right aft the top of the help it shows:
        Usage: bazel info <options> [key]
    And: 
        The full list of keys and the meaning of their values is documented in
        the bazel User Manual, and can be programmatically obtained with
        'bazel help info-keys'.
bazel info <options> [key]
    The generic `bazel info` cmd format, as shown in the help menu just above.
bazel help info-keys
    <================
    Print all of the keys which can be queried with the `bazel info` cmd above, and a description of what they mean! Example: `bazel info output_base`.
    Sample output:
            $ bazel help info-keys
            bazel-bin               Configuration dependent directory for binaries.
            bazel-genfiles          Configuration dependent directory for generated files.
            bazel-testlogs          Configuration dependent directory for logs from a test run.
            build-language          A protobuffer with the build language structure
            character-encoding      Information about the character encoding used by the running JVM.
            client-env              The specifications that need to be added to the project-specific rc file to freeze the current client environment
            command_log             Location of the log containing the output from the build commands.
            committed-heap-size     The amount of memory in bytes that is committed for the Java virtual machine to use
            default-package-path    The default package path
            defaults-package        Obsolete. Retained for backwards compatibility.
            execution_root          A directory that makes all input and output files visible to the build.
            gc-count                Number of garbage collection runs.
            gc-time                 The approximate accumulated time spend on garbage collection.
            install_base            The installation base directory.
            java-home               Location of the current Java runtime.
            java-runtime            Name and version of the current Java runtime environment.
            java-vm                 Name and version of the current Java virtual machine.
            max-heap-size           The maximum amount of memory in bytes that can be used for memory management.
            output_base             A directory for shared bazel state as well as tool and strategy specific subdirectories.
            output_path             Output directory
            package_path            The search path for resolving package labels.
            peak-heap-size          The peak amount of used memory in bytes after any call to System.gc().
            release                 bazel release identifier
            repository_cache        The location of the repository download cache used
            server_log              bazel server log path
            server_pid              bazel process id
            starlark-semantics      The effective set of Starlark semantics option values.
            used-heap-size          The amount of used memory in bytes. Note that this is not a good indicator of the actual memory use, as it includes any remaining inaccessible memory.
            used-heap-size-after-gc The amount of used memory in bytes after a call to System.gc().
            workspace               The working directory of the server.
bazel info | grep -o '.*: ' | rev | cut -c3- | rev
    Read just available keys from the output of `bazel info`! 
    See also this help on how to use `rev | cut -c3- | rev`: https://stackoverflow.com/a/39013253/4561887.
    Sample output:
            $ bazel info | grep -o '.*: ' | rev | cut -c3- | rev
            bazel-bin
            bazel-genfiles
            bazel-testlogs
            character-encoding
            command_log
            committed-heap-size
            execution_root
            gc-count
            gc-time
            install_base
            java-home
            java-runtime
            java-vm
            max-heap-size
            output_base
            output_path
            package_path
            release
            repository_cache
            server_log
            server_pid
            used-heap-size
            workspace
bazel info | grep -o '.*: ' | grep -o '[^: ]*'
    Alternative way to get the exact same list of keys from the `bazel info` output as shown just above!
bazel info output_base
    Show the output directory of the bazel build + sources, including external sources. 
    See: https://bazel.build/docs/external?hl=en#layout
    Sample output:
            $ bazel info output_base
            /home/gabriel/.cache/bazel/_bazel_gabriel/04bc77638a312ceaca7e62e095dc00bc
ls "$(bazel info output_base)"
    List all contents of the output_base directory (shown above).
ls -d "$(bazel info output_base)"/*/
    List only the **directories** within the output_base dir!
    See also here for the `/*/` part help at the end: https://stackoverflow.com/a/14352330/4561887
    Example output. Notice the 4 directories in this "output_base" dir!: "execroot", "external", "install", and "server":
            $ ls -d "$(bazel info output_base)"/*/
            /home/gabriel/.cache/bazel/_bazel_gabriel/04bc77638a312ceaca7e62e095dc00bc/execroot/
            /home/gabriel/.cache/bazel/_bazel_gabriel/04bc77638a312ceaca7e62e095dc00bc/external/
            /home/gabriel/.cache/bazel/_bazel_gabriel/04bc77638a312ceaca7e62e095dc00bc/install/
            /home/gabriel/.cache/bazel/_bazel_gabriel/04bc77638a312ceaca7e62e095dc00bc/server/
ls "$(bazel info output_base)/external"
    <======= VERY USEFUL! ========
    IMPORTANT FOLDER! This "external" folder should be considered like an extension of your source code, whenever using bazel! It will house all bazel-downloaded external libraries which are dependencies to your bazel-based projects. So, if you consider your main source code dir PLUS (+) this "$(bazel info output_base)/external" dir to be all part of the source code you are using, then that is correct. 
    Adding this "external" dir to your IDE indexer, and/or `grep`ping within this "external" dir may be useful whenever you are searching for functions or things within certain external dependencies your source code is using! This allows you to see whatever source code or implementation details or code-based documentation you may need to see when browsing your source code and looking in the external libraries used by your source code.
./update_symlink_to_external.sh
    Update the symlink to the Bazel "external" dir found just above, assuming this "update_symlink_to_external.sh" script is executable and contains the following code:
        ```
        #!/bin/bash

        FULL_PATH_TO_SCRIPT="$(realpath "$0")"
        SCRIPT_DIRECTORY="$(dirname "$FULL_PATH_TO_SCRIPT")"

        target_dir="$(bazel info output_base)/external"

        echo "Creating symlink to dir \"$target_dir\" inside \"$SCRIPT_DIRECTORY\"."
        ln -svnrf "$target_dir" "$SCRIPT_DIRECTORY"
        ```
    You should then add this symlink dir to your Eclipse (or other IDE) project, as a virtual folder or otherwise, and as required, to bring them in to be indexed so you can search, navigate, and browse any external source code libraries as needed.
    INSTALLATION:
    Something like this would work:
        ```
        cd path/to/repo
        mkdir -p GS/external
        gedit GS/external/update_symlink_to_external.sh
        # copy and paste the above code into this script now; then:
        chmod +x GS/external/update_symlink_to_external.sh
        # Now you **may** want to either exclude this dir in your `.gitignore` file:
        echo '/GS/' >> .gitignore
        # OR just locally for yourself in your private `.git/info/exclude` file:
        echo '/GS/' >> .git/info/exclude
        ```
bazel fetch //path/to/some_dir:some_target
    Fetch all dependencies (ex: sub-repos, submodules, executables, libraries, etc.) to path "$(bazel info output_base)/external" which are needed by this target!
bazel fetch //path/to/some_dir/...
    Fetch all dependencies (ex: sub-repos, submodules, executables, libraries, etc.) to path "$(bazel info output_base)/external" which are needed by **these several targets!**
bazel fetch <targets>
    General form of the above.
bazel help fetch
    See all options for `bazel fetch`. Note: run `bazel help` or `bazel --help` instead to see a list of all bazel cmds, such as `bazel fetch`.
---
UPDATE: FETCHING IS NOT ENOUGH! 
See my full description of what to do here: https://github.com/bazelbuild/bazel/issues/14058#issuecomment-1055015665
Do this!:
```
BUILD_TARGET="//some/path/to/a/build/target/which:requires_my_dependency"
# manually delete the "external" folder you've edited, once you're done editing it and
# want to restore it to how it was originally
{EXTERNAL_DEPS_ROOT}="$(bazel info output_base)/external"
EXTERNAL_DEP="some_dependency_repo_name" 
rm -rf "${EXTERNAL_DEPS_ROOT}/${EXTERNAL_DEP}"
# force bazel to re-download this dependency!:
# Note: this is a bit of a hack, but it works. 
# See: https://github.com/bazelbuild/bazel/issues/14058#issuecomment-1031520021
time bazel sync --only=$BUILD_TARGET
time bazel fetch $BUILD_TARGET
```
---
time bazel sync --only=//some:build_target && \
time bazel fetch //some:build_target
    <==========
    Re-download (fetch/update) a build dependency into path `"$(bazel info output_base)/external/some_dependency_dir"`.
    See my long comment & description: https://github.com/bazelbuild/bazel/issues/14058#issuecomment-1055015665
time bazel sync --only=<target> && \
time bazel fetch <target>
    The generic form of the cmd just above.

time bazel build //...
    build the whole project
time bazel build //:all
    (apparently) build only the build targets at the **top level** of the project (defined directly in the top-most BUILD or BUILD.bazel file), NOT recursing down and building all lower-level build targets too, like `bazel build //...` would do; 
    See here for more info: https://docs.bazel.build/versions/master/guide.html#specifying-targets-to-build

time bazel query //...
time bazel test //...
bazel --version
bazel help
bazel help build

== bazel query: ==
References:
1. *****[START HERE] https://docs.bazel.build/versions/master/query-how-to.html
   Ex: see dependencies of a build target:
        bazel query 'deps(//path/to/package:target)'
1. *****https://docs.bazel.build/versions/master/query.html

bazel query
    invalid command (missing arguments); it will tell you to type `bazel help query` for help
bazel help query
    see the help for `bazel query`
bazel help query | less -RFX
    same as above, but see the output in the less viewer since it's so long
bazel help --long query
    show the long help menu
bazel help --long query | less -RFX
    same as above, but see the output in the less viewer since it's so long <====== GOOD HELP INFO =====

FIND DEPENDENCIES OF A BUILD TARGET:
bazel query "deps(//foo)"
bazel query "deps(//some/path:my_target)"
bazel query "deps(//some/path/...)"
bazel query 'deps(//path/to/package:target)'
    "find all dependencies of //path/to/package:target"

FIND A DEPENDENCY PATH BETWEEN TWO BUILD TARGETS:
bazel query 'somepath(//path/to/package:target, //dependency)'
    "find a dependency path between //path/to/package:target and //dependency"

== SUMMARY OF GOOD STARTUP OPTIONS (see above or below or online for details): ==
bazel [startup_options] build //...
    --host_jvm_args=-Xmx16g
    --output_user_root="/path/to/custom/dir/bazel_cache"

== SUMMARY OF GOOD BUILD OPTIONS (see above or below or online for details): ==
bazel build [build_options] //...
    --keep_going
        Continue building, despite build errors.
    -k
        Same as above.
    --copt
    --per_file_copt
    --jobs

== BUILD WITH DEBUG SYMBOLS ==
[bazel debug builds; bazel build with gdb debug symbols; bazel gdb debug builds]

(required to debug an executable with gdb or lldb, for instance):
- gdb debugger: https://www.gnu.org/software/gdb/
- lldb debugger: https://lldb.llvm.org/
1) BEST OPTION: use the `--copt` build option:
bazel build --copt="-ggdb" --copt="-Og" //... = add C build options for gdb debugging symbols and Optimization Level "debu'g'" for the entire build! Or, even better, just do it for the taget you care about most:
time bazel build --copt=-ggdb --copt=-Og //path/to/my/target_dir/... = build my required target with the appropriate debug options!
time bazel build --copt=-ggdb --copt=-O0 --strip=never //path/to/my/target_dir/... = [UPDATE: PREFER `-O0` OVER `-Og`! See my ans.: https://stackoverflow.com/a/63386263/4561887] same as above, but also ensure Bazel **never** strips debug information, just to be sure! <=========== BEST DEBUG BUILD OPTIONS! (esp. for the repetitive edit-compile-debug development cycle!) ==========
  See:
    1. *****+https://docs.bazel.build/versions/master/user-manual.html#flag--copt
    2. https://docs.bazel.build/versions/master/command-line-reference.html#flag--copt
    3. [MY OWN Q&A: I discovered it is preferred to use option `-Og` over `-O0` when debugging!] What's the difference between a compiler's `-O0` option and `-Og` option? - https://stackoverflow.com/questions/63386189/whats-the-difference-between-a-compilers-o0-option-and-og-option/63386263
        1. See the official manual here!: https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#Optimize-Options
        2. [UPDATE: PREFER `-O0` OVER `-Og`! See my ans.: https://stackoverflow.com/a/63386263/4561887]
    4. `--strip=never` info: https://docs.bazel.build/versions/master/user-manual.html#flag--strip
2) `copts` addition to the BUILD.bazel file:
- Alternatively, just do this for individual build targets, as desired, in `copts` for cc_library() rules; see here:
https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library.copts
Here is an example of how to use `copts`, partially pulled from the examples here:
https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library

    cc_library(
        name = "bar",
        copts = [
            "-ggdb",  # <=======
            "-O0",    # <=======
        ],
        srcs = [
            "bar.cc",
            "bar-impl.h",
        ],
        hdrs = ["bar.h"],
        deps = [":baz"],
    )

3) Use the `--per_file_copt` Bazel build option instead. NB: this is NOT the best option, and it may even **malfunction** and make full debugging NOT WORK [or perhaps I simply needed to add `--strip=never` too to fix this!?--NEED TO TEST!]! So, prefer the `--copt=` option above instead! See my answer describing this here: https://stackoverflow.com/questions/3758614/gdb-no-symbol-i-in-current-context/63386031#63386031.
Documentation:
1. *****+https://docs.bazel.build/versions/master/user-manual.html#flag--per_file_copt
2. https://docs.bazel.build/versions/master/command-line-reference.html#flag--per_file_copt

    bazel build --per_file_copt=path/to/my/module/.*@-ggdb,-Og //... = build everything, but anything which matches the regular expression `path/to/my/module/.*` will also be built with the appropriate gdb debug symbols (`-ggdb`) and with optimization level debu'g' (`-Og`) for easy debugging! You may also need to add `--strip=never` to keep the linker from stripping debug symbols during linking, like this:

    bazel build --per_file_copt=path/to/my/module/.*@-ggdb,-Og --strip=never //... = same as above, but never strip debugging symbols! See the link above, as well as this: https://docs.bazel.build/versions/master/user-manual.html#flag--strip
- - -
More complicated, generic `--per_file_copt` example:

    --per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-Og,-fprofile-arcs = adds the `-Og` and the `-fprofile-arcs` options to the command line of the C++ compiler for all `.cc` files in [the build *target* path] `//foo/` except `file.cc`.

CLANG/LLVM COMPILER NOTE: to optimize debugging output for clang's lldb debugger instead of GNU's gdb debugger, use option `-glldb` instead of `-ggdb`; see here: https://clang.llvm.org/docs/UsersManual.html#cmdoption-ggdb. Still prefer `-Og` over `-O0` for both options, however. See my ans. here: https://stackoverflow.com/questions/63386189/whats-the-difference-between-a-compilers-o0-option-and-og-option/63386263#63386263, and the official manual here: https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#Optimize-Options. [UPDATE: PREFER `-O0` OVER `-Og`! See my ans.: https://stackoverflow.com/a/63386263/4561887].

== ==

time bazel query --output=build //path/to/my/target/... > out.txt = Store the expanded form of all macros/build rules into out.txt; see above; see this too for more on **expanding Bazel build macros**: https://docs.bazel.build/versions/master/skylark/macros.html#expanding-macros

bazel --host_jvm_args=-Xmx16g build //... = set max java heap size to 16g then build everything; see here for the command above, as well as for how to make a Linux swapfile!
https://stackoverflow.com/questions/55190272/java-lang-outofmemoryerror-when-running-bazel-build/60572662#60572662

*****BEST BAZEL BUILD CMD*****
time bazel --host_jvm_args=-Xmx16g build //...; gs_alert = same as above but better: time the whole thing and do an alert sound (bell character sound) & pop-up notification to notify me when done     <============== OVERALL BEST BAZEL BUILD COMMAND ==========

Other useful options:
1) Specify a custom bazel cache directory (*bazel startup* option `--output_user_root`). Useful, for example, when you have limited space and need to A) put your build cache on another drive, or B) share a bazel build cache with another user, or even multiple users:
- See: https://docs.bazel.build/versions/master/command-line-reference.html#flag--output_user_root
        bazel --output_user_root="/path/to/custom/dir/bazel_cache" build //...
2) Specify the number of "jobs", or threads to run at once during the build (bazel *build* option `--jobs N`). The default is `--jobs=auto`, which tries to "[calculate] a reasonable default based on host resources":
- See: https://docs.bazel.build/versions/master/command-line-reference.html#flag--jobs
        bazel build --jobs 4 //...  # 4 jobs might be good on a 6-core machine, for instance, or perhaps 6 jobs on an 8-core machine, or 16 jobs on a 20-core machine--whatever you think is best for your situation; not using all the cores leaves some for you to continue working while a build is running in the background
#) Now, putting it all together:
        bazel --output_user_root="/home/gabriels/.cache/bazel_cache" build --jobs 4 //...'     <============ VERY USEFUL TO KNOW ABOUT ============

== BAZEL TEST OPTIONS: ==

[keywords: print test output always]
bazel test --test_output=errors //...
    log all errors (failed test results) to stdout--in other words, you'll only see a long output from running the bazel test if it fails!--this is a good setting to use; for help, see: https://groups.google.com/forum/#!topic/bazel-discuss/2mJPklIaCeo; see also: `bazel help test` for other options!
bazel test --test_output=summary //...
    the default (doesn't show errors; just shows a summary)
bazel test --test_output=all //...
    prints ALL output to stdout, even for tests that pass!
    <========
bazel test --test_arg=--some_arg_to_test_program //some/dir:my_test
    Pass argument `--some_arg_to_test_program` to the test program when running the test! 
    See: https://stackoverflow.com/questions/50877601/how-to-pass-custom-flags-to-bazel-test-command
    And (official documentation): 
        CLI reference: https://docs.bazel.build/versions/master/command-line-reference.html#flag--test_arg
        User Manual: https://docs.bazel.build/versions/master/user-manual.html#flag--test_arg
    <========

*****BEST BAZEL TEST CMD (optionally add `--host_jvm_args=-Xmx16g` if needed too)*****
time bazel test --test_output=errors --test_arg=--gtest_color=yes //...
    get color output in the tests! See the readme in my project here for more explanation and a list of references: https://github.com/ElectricRCAircraftGuy/eRCaGuy_gtest_practice. See also: https://stackoverflow.com/questions/50877601/how-to-pass-custom-flags-to-bazel-test-command/50890446#50890446.

== Debugging Bazel Builds: ==
[keywords: bazel debug build flags; bazel build debug flags; *debugging bazel builds*; debug bazel builds; bazel builds debugging; bazel debugging]

--keep_going, -k
    Useful when debugging--tells Bazel to keep going and build/run as much as possible, even if an error is encountered. See: https://docs.bazel.build/versions/master/command-line-reference.html#flag--keep_going. [keep going, keep building, continue building after errors, build through errors]. Ex usage:
time bazel build --keep_going //...
    Keep going/building during a Bazel build/run error, so that you can get and see as many errors as possible at once to speed up the fix/build/test process as you try to debug build or test problems and get your code to work right. <========= VERY USEFUL!--ESP. WHEN DEBUGGING CODE THAT WON'T BUILD! ==========
time bazel build -k //...
    Same as above.
bazel help build | grep '\-k'
    Find the brief `--keep_going` (`-k`) description in the `bazel build` help menu.
--sandbox_debug
    Helps you see more build info. Ex usage:
            time bazel build --sandbox_debug //...
-s
    Outputs all build commands [sort of like you might expect a "verbose" build option to do!?]; see: https://stackoverflow.com/questions/32823625/bazel-build-verbose-compiler-commands-logging/32837180#32837180. Ex usage:
            time bazel build -s //...

== Visualizing your Bazel build using dot/Graphviz ==
See:
1. Bazel info:
    1. https://blog.bazel.build/2015/06/17/visualize-your-build.html
    1. *****https://docs.bazel.build/versions/master/query-how-to.html
1. General dot/Graphviz info:
    1. https://www.graphviz.org/
    1. [Drawing graphs with _dot_](https://www.graphviz.org/pdf/dotguide.pdf)
    1. https://en.wikipedia.org/wiki/DOT_(graph_description_language)


====================================================================================================
= buildroot: =
====================================================================================================

keywords: make:

(and emmbedded Linux)

- a build system to build embedded Linux
- an alternative to yocto
- Note: buildroot may use the meson and ninja build systems under-the-hood, or possibly even cmake?

References:
1. ***** Source code on github: https://github.com/buildroot/buildroot
    1. ***** List of all packages: https://github.com/buildroot/buildroot/tree/master/package
1. https://buildroot.org/downloads/manual/manual.html - The Official Buildroot user manual
    1. https://buildroot.org/downloads/manual/manual.html#adding-packages - Chapter 18. Adding new packages to Buildroot
    1. https://buildroot.org/downloads/manual/manual.html#full-rebuild - 8.2. Understanding **when** a full rebuild is necessary
    1. https://buildroot.org/downloads/manual/manual.html#rebuild-pkg - 8.3. Understanding **how** to rebuild packages
1. 3rd-party
    1. https://bootlin.com/
    1. https://bootlin.com/doc/training/embedded-linux/embedded-linux-slides.pdf
    1. https://bootlin.com/doc/training/buildroot/buildroot-slides.pdf
    1. Getting started with Buildroot - Lab - https://elinux.org/images/4/4b/Getting-Started-With-Buildroot-Lab-ELC2018.pdf 
    1. Google search for "buildroot choose target board": https://www.google.com/search?q=buildroot+choose+target+board&oq=buildroot+choose+target+board&aqs=chrome..69i57.7996j0j4&sourceid=chrome&ie=UTF-8

Buildroot is a build system. It is NOT NEARLY AS ROBUST, RELIABLE, NOR REPEATABLE as Bazel. Bazel will detect even the most-minute changes and rebuild just what it needs to as a result. Buildroot does NOT do this. Rather, YOU must determine when to do a full rebuild, and *what* to build otherwise. It only has **some** ability to incrementally build or rebuild things automatically as you make changes. See the notes and official manual just below.

Note: the default output directory for the built rootfs root file system tarball is: "output/images/rootfs.tar".

I RECOMMEND THAT YOU **PUT `time` IN FRONT OF ALL `make` COMMANDS BELOW** SO YOU CAN SEE HOW LONG THEY TAKE! This is useful to set your expectations as you build your system, so you can get a feel for what commands take how much time, thereby allowing you to more efficiently plan lunch breaks, bathroom breaks, when to build what, etc.

make
    Build for the configured target board.
make all
    Same as above, since `all` is the default `make` target.

------------------------------
**When** to do a full rebuild: 
------------------------------
https://buildroot.org/downloads/manual/manual.html#full-rebuild
1. "Again, Buildroot does not track when a package should be rebuilt: **once a package has been built, it is never rebuilt unless explicitly told to do so**."
1. "Generally speaking, when you’re facing a build error and you’re unsure of the potential consequences of the configuration changes you’ve made, do a full rebuild. If you get the same build error, then you are sure that the error is not related to partial rebuilds of packages..."

make clean all
    Clean AND force a full rebuild right now! This cleans and then rebuilds! It is the equivalent of calling `make clean && make all`, where `make all` is the same as `make`!
    <===============
make clean
    Just clean, which will force a rebuild **next time** you build, but not now. ie: It won't build at this time.
make clean && make all
    Clean (to force a full rebuild) and make. Same as `make clean all`. 
make clean && make
    Same as above; same as `make clean && make all` or just `make clean all`.
make clean; \
make
    Same as above, just written as separate commands. ie: "clean", or delete, the entire "output/my-target-board" dir, then rebuild it all again from scratch.

------------------------------
**How** to rebuild:
------------------------------
https://buildroot.org/downloads/manual/manual.html#rebuild-pkg
- "Removing a package is unsupported by Buildroot without rebuilding from scratch. This is because Buildroot doesn’t keep track of which package installs what files in the output/staging and output/target directories, or which package would be compiled differently depending on the availability of another package."
- "The easiest way to rebuild a single package from scratch is to remove its build directory in output/build. Buildroot will then re-extract, re-configure, re-compile and re-install this package from scratch. You can ask buildroot to do this with the `make <package>-dirclean` command."
- "On the other hand, if you only want to restart the build process of a package from its compilation step, you can run `make <package>-rebuild`. It will restart the compilation and installation of the package, but not from scratch: it basically re-executes make and make install inside the package, so it will only rebuild files that changed."
- "Internally, Buildroot creates so-called stamp files to keep track of which build steps have been completed for each package. They are stored in the package build directory, `output/build/<package>-<version>/` and are named `.stamp_<step-name>`. The commands detailed above simply manipulate these stamp files to force Buildroot to restart a specific set of steps of a package build process."

NB: all `make <package>-...` commands below do NOT trigger recreating the root filesystem image (rootfs)! **If re-creating the root filesystem is necessary**, one should in addition run `make` or `make all` [same thing]" (https://buildroot.org/downloads/manual/manual.html#rebuild-pkg).
<===============

GS: >>> What is a package? <<< Ans: a package is a directory of source code and/or binaries or libraries intended for use on an embedded-linux target board. Package names are simply **folders** or **subfolders** inside one of the "package" directories. You might store your own custom "packages", for instance, inside "br2-external/package", for instance, while storing buildroot's included packages inside "buildroot/package". There are also a few "special" packages which are somehow defined internally in buildroot. These include "linux" and "uboot", for instance. 

Sample commans to rebuild a package:
```bash
make linux-rebuild
make uboot-rebuild
make busybox-rebuild
make dc3dd-rebuild
```
...where the package names above are `linux`, `uboot`, `busybox`, `dc3dd`, etc. 

make <package>-dirclean
    Delete the built package files for <package> from the output build dir. This deletes entire "output/build/<package>" dir. Next time you run `make` (I believe) now, this package will be entirely rebuilt from scratch.
    See: https://buildroot.org/downloads/manual/manual.html#rebuild-pkg
make <package>-rebuild
    Restart the compilation and installation of the package, but **not from scratch**. ie: this "re-executes `make` and `make install` inside the package, so it will only rebuild files that changed."
    This also calls `make <package>-reinstall`!
    See: https://buildroot.org/downloads/manual/manual.html#rebuild-pkg
    <===============
make <package>-reconfigure
    Restart the configuration, compilation, and installation of the package [from scratch, it sounds like!]
    This also calls `make <package>-rebuild`!
    See: https://buildroot.org/downloads/manual/manual.html#rebuild-pkg

make <package>-rebuild && make all
    Rebuild the files that changed in package "<package>", AND also re-create the root file system (rootfs)! (`make all` recreates the file system, as `make <package>-rebuild` only rebuilds the package alone, but does NOT rebuild the file system!). See my "NB" notes above. Source: https://buildroot.org/downloads/manual/manual.html#rebuild-pkg.
    <======= BEST!? ========
make <package>-rebuild && make
    Same as above. `make` calls `make all` since "all" is the default make target (ie: the first-listed name which does not begin with a `.`). See: https://www.gnu.org/software/make/manual/html_node/How-Make-Works.html and https://stackoverflow.com/a/2057716/4561887.

------------------------------
**How** to do a **robust** rebuild:
------------------------------
- Keywords: buildroot build; buildroot robust build; buildroot robust rebuild
- The only reliable or "robust" way I have found, period, to force Buildroot to actually rebuild a package or set of packages, is to DELETE (remove via `rm`) the output build files you'd like to force to rebuild before you begin, like this, for example. You'll probably have to tweak this per your build system and how you have it configured, but this is the idea:

<================ DO SOMETHING LIKE THIS TO TRULY FORCE A REBUILD IN BUILDROOT! ================
```bash
# this is the only reliable way I know to FORCE buildroot to rebuild your code and the
# .swu image
TARGET="some-target"
make "target-${TARGET}"  # set the build target
cat .config  # prove the target is set
# Note: for info on the `time` command here, see my answer: 
# https://unix.stackexchange.com/a/699728/114401
time ( \
    rm -rf \
    output/$TARGET/build/my_module_1* \
    output/$TARGET/build/my_module_2* \
    output/$TARGET/build/my_module_3* \
    output/$TARGET/build/host-my_module_1* \
    output/$TARGET/build/host-my_module_2* \
    output/$TARGET/build/host-my_module_3* \
    output/$TARGET/images/image.swu && \
    time make br-my-module-1-reconfigure && \
    time make br-host-my-module-1-reconfigure && \
    time make \
); gs_alert
```
- The `time make br-my-module-1-reconfigure` cmd above builds "my_module_1" for the target (embedded Linux board).
- The `time make br-host-my-module-1-reconfigure` cmd above builds "my_module_1", including its unit tests, for the host (the Linux build computer).
- The `time make` cmd builds the `.swu` rootfs (root filesystem) image file for the target (embedded linux board).
- Manually running unit tests after the build commands above can be done with something like this, which you could append to the end of the build command above if you wanted:
    ```bash
    time output/${TARGET}/build/host-my_module_1-custom/build/test/__test_my_module_1
    ```
- `br-` vs `brna-` **offline** builds; building remotely withOUT internet: notice the `br-` part above. This stands for "buildroot". Some customized build systems may build remotely with secure authentication when you choose the `br-<package>` package name to build, and build **locally** and withOUT authentication if you choose the `brna-<package>` instead! In this case, `brna-` stands for "BuildRoot No Authentication". 
    - Using `brna-` **offline** builds can be 30% faster and allow you to build while on-the-go and traveling, even withOUT internet, which is great!

time make br-all
    <===========
    Force-rebuild the rootfs .swu image and rootfs overlay (similar to force-removing "output/$TARGET/images/image.swu" first, as shown above).
time make brna-all
    Same as above, but via an offline build.

TO ADD OR USE A NEW BUILDROOT PACKAGE IN YOUR PACKAGE:
    See the "CORRECT WAY" description in the "meson" section below!


====================================================================================================
= yocto: =
====================================================================================================

- a build system to build embedded Linux
- an alternative to buildroot


====================================================================================================
= make: =
====================================================================================================
[make and makefiles make files]


====================================================================================================
= cmake: =
====================================================================================================
- Part of GNU Autotools.

See: 
1. https://opensource.com/article/19/7/introduction-gnu-autotools
1. https://www.gnu.org/software/automake/faq/autotools-faq.html
1. Google search for "make autotools": 
   https://www.google.com/search?q=make+autotools&oq=make+autotools&aqs=chrome..69i57j69i65.3920j0j7&sourceid=chrome&ie=UTF-8


====================================================================================================
= meson: =
====================================================================================================
[meson build system and meson.build files; and some Buildroot and make .mk file integration info]

References:
1. https://mesonbuild.com/
1. https://mesonbuild.com/Comparisons.html
1. https://github.com/mesonbuild/meson/blob/master/docs/markdown/FAQ.md#but-i-really-want-to-use-wildcards

Using wildcards in meson search patterns:
Wildcards are *not* natively supported in meson! If you REALLY need to do a wildcard search for some reason in a meson.build file, here is how. 
See: https://github.com/mesonbuild/meson/blob/master/docs/markdown/FAQ.md#but-i-really-want-to-use-wildcards
    1. Create a custom .sh shell script, such as this:
        "find_some_lib_dir.sh":
        ```bash
        #!/usr/bin/env bash

        # Find a directory named "somedir-1234", for instance, one level up, knowing
        # that the "1234" part changes each build. This is a bash shell script "glob"
        # pattern.

        ls -d -1 ../somedir-*
        ```
    2. In your meson.build file, call `run_command('find_some_lib_dir.sh')` to run the script and capture and use its output, like this:
        In your module's meson.build file:
        ```meson
        # Find the directory of interest; ex: "../somedir-1234"
        some_lib_directory_list = run_command('find_some_lib_dir.sh')
        # Assume that directory contains a folder we really need to include as a C++ 
        # "include" dir. Let's obtain that path and include it. 
        # Note: the `[0]` part indexes into the first element in this list. If there are
        # multiple folders matching the pattern in the shell script, only the first one
        # in the list is obtained in this way.
        some_lib_directory_name = some_lib_directory_list.stdout().strip().split('\n')[0]
        some_lib_dep = declare_dependency(
            include_directories: include_directories(
                '../' + some_lib_directory_name + '/path/to/include',
            ),
        )

        # Now include the above `some_lib_dep` dependency for that library as part of
        # our total dependency list
        all_deps = [
            some_lib_dep,
            # other meson library dependencies
            dependency('some_other_lib2'),
            dependency('some_other_lib3'),
            dependency('some_other_lib4'),
        ]
        ```

[Keywords: Buildroot json library; json for modern cpp c++; nlohmann json library]

Example (THIS IS A HACK!--but it works. See further below for the CORRECT way) for the `json-for-modern-cpp` library in buildroot.
Here is where that library is in buildroot: https://github.com/buildroot/buildroot/tree/master/package/json-for-modern-cpp:

    find_json_for_modern_cpp_dir.sh
    ```bash
    # find the directory, whatever its version number may be attached to that directory name
    ls -d -1 ../json-for-modern-cpp-*
    ```

    In your module's meson.build file:
    ```meson
    # Find the directory of interest; ex: "../json-for-modern-cpp-3.10.5"
    json_for_modern_cpp_directory_list = run_command('find_json_for_modern_cpp_dir.sh')
    json_for_modern_cpp_directory_name = json_for_modern_cpp_directory_list.stdout().strip().split('\n')[0]
    json_for_modern_cpp_dep = declare_dependency(
        include_directories: include_directories(
            # This is a header-only library with the single header located at this path, for example:
            # "../json-for-modern-cpp-3.10.5/single_include/nlohmann/json.hpp"
            # See: https://github.com/nlohmann/json/tree/develop/single_include/nlohmann
            '../' + json_for_modern_cpp_directory_name + '/single_include',
        ),
    )

    # Now include the above `json_for_modern_cpp_dep` dependency for that library as part of
    # our total dependency list
    all_deps = [
        json_for_modern_cpp_dep,
        # other meson library dependencies
        dependency('some_other_lib2'),
        dependency('some_other_lib3'),
        dependency('some_other_lib4'),
    ]
    ```

    Now you can include this library in any source or header in this module like this:
    ```cpp
    #include <nlohmann/json.hpp>
    ``` 

    Note: in your module's buildroot "my-module-name.mk" file, you *might* also need to do this:
    ```make
    MY_MODULE_NAME_DEPENDENCIES += \
        some-other-lib1 \
        some-other-lib2 \
        json-for-modern-cpp

    HOST_MY_MODULE_NAME_DEPENDENCIES += \
        host-some-other-lib1 \
        host-some-other-lib2 \
        json-for-modern-cpp
    ```

    Note: the host dependency should actually be `host-json-for-modern-cpp`, but that doesn't work yet in this hack! See below for the proper fix instead!:


CORRECT WAY! This is the **correct way** to bring in the json-for-modern-cpp library into your module in Buildroot!

    1. Delete the "find_json_for_modern_cpp_dir.sh" script above. You don't need it.
    2. Delete all "meson.build" file additions above, and do this instead:
        ```meson.build
        # bring in all required libraries as dependencies
        all_deps = [
            # NB: this `nlohmann_json` meson.build name can be identified from its public repo's 
            # meson.build file here: https://github.com/nlohmann/json/blob/develop/meson.build#L1
            dependency('nlohmann_json')
            dependency('some_other_lib2'),
            dependency('some_other_lib3'),
            dependency('some_other_lib4'),
        ]
        ```
    3. Update this file in the Buildroot repo: https://github.com/buildroot/buildroot/blob/master/package/json-for-modern-cpp/json-for-modern-cpp.mk
        Add this line to the very bottom: `$(eval $(host-cmake-package))`. Now you have the following, with the last line being what we just added:
        json-for-modern-cpp.mk: 
        ```make
        ################################################################################
        #
        # json-for-modern-cpp
        #
        ################################################################################

        JSON_FOR_MODERN_CPP_VERSION = 3.10.5
        JSON_FOR_MODERN_CPP_SOURCE = json-$(JSON_FOR_MODERN_CPP_VERSION).tar.gz
        JSON_FOR_MODERN_CPP_SITE = $(call github,nlohmann,json,v$(JSON_FOR_MODERN_CPP_VERSION))
        JSON_FOR_MODERN_CPP_LICENSE = MIT
        JSON_FOR_MODERN_CPP_LICENSE_FILES = LICENSE.MIT
        JSON_FOR_MODERN_CPP_CPE_ID_VENDOR = json-for-modern-cpp_project

        JSON_FOR_MODERN_CPP_INSTALL_STAGING = YES
        # header only library
        JSON_FOR_MODERN_CPP_INSTALL_TARGET = NO
        JSON_FOR_MODERN_CPP_CONF_OPTS = -DJSON_BuildTests=OFF -DJSON_MultipleHeaders=ON

        $(eval $(cmake-package))
        $(eval $(host-cmake-package))
        ```

        The `$(eval $(cmake-package))` line is what creates the `json-for-modern-cpp` dependency used by the "my-module-name.mk" Buildroot file above. This is used for the **target embedded Linux board**. 
        The `$(eval $(host-cmake-package))` line is what creates the `host-json-for-modern-cpp` dependency needed in that Buildroot file for the **host Linux computer** (build machine), so that it can use the json-for-modern-cpp module **in unit tests** on the host build machine!

    4. Update your module's buildroot "my-module-name.mk" file to properly use this newly-available `host-json-for-modern-cpp` library now for the host, instead of **incorrectly** trying to use `json-for-modern-cpp` on the host!:
        "my-module-name.mk":
        ```make
        MY_MODULE_NAME_DEPENDENCIES += \
            some-other-lib1 \
            some-other-lib2 \
            json-for-modern-cpp

        HOST_MY_MODULE_NAME_DEPENDENCIES += \
            host-some-other-lib1 \
            host-some-other-lib2 \
            host-json-for-modern-cpp
            # This last line just above is now **fixed**!
        ```

    That's it!


Adding dependencies from other meson.build files:
If you need to add a dependency on a 3rd-party library or something, such as JSON for Modern C++ (https://github.com/nlohmann/json), simply do this:
    [See the "CORRECT WAY" just above for a full example!]
    1. Find that project's meson.build file. Ex: https://github.com/nlohmann/json/blob/develop/meson.build
        Notice the `'nlohmann_json'` project name at the top. Use that in your module's meson.build file:
        ```meson.build
        all_deps = [
            # NB: this `nlohmann_json` meson.build name can be identified from its public repo's 
            # meson.build file here: https://github.com/nlohmann/json/blob/develop/meson.build#L1
            dependency('nlohmann_json')
            dependency('some_other_lib2'),
            dependency('some_other_lib3'),
            dependency('some_other_lib4'),
        ]
        ```
    2. Add `$(eval $(host-cmake-package))` to the bottom of the `json-for-modern-cpp.mk` file in Buildroot.
    3. Use the proper dependencies in your module's Buildroot "my-module-name.mk" file:
        ```make
        MY_MODULE_NAME_DEPENDENCIES += \
            some-other-lib1 \
            some-other-lib2 \
            json-for-modern-cpp

        HOST_MY_MODULE_NAME_DEPENDENCIES += \
            host-some-other-lib1 \
            host-some-other-lib2 \
            host-json-for-modern-cpp
            # This last line just above is now **fixed**!
        ```
    Again, see the "CORRECT WAY" above for more details!


====================================================================================================
= embedded Linux: =
====================================================================================================

References:
1. https://bootlin.com/
1. [NEED TO STUDY & READ!] https://bootlin.com/doc/training/embedded-linux/embedded-linux-slides.pdf
1. https://bootlin.com/doc/training/buildroot/buildroot-slides.pdf
1. https://en.wikipedia.org/wiki/Sysfs


====================================================================================================
= gdb and gdbgui: =
====================================================================================================

Keywords: help gdb, gdb help

== General Debugging Advice: ==

> The general debugging methodology for segfaults:
> 1) Run it in a debugger, print a backtrace, fix the issue.
> 2) If (1) doesn't work add debug symbols and other stuff and try again.
> 3) If (2) doesn't work, run it under the sanitizers + Valgrind and fix the issue.
> 4) If (3) doesn't work, start to bisect the program until all that is left is the bug.
> Another powerful methodology is just to step through the program with a debugger. That will give you a coarse idea of where the issue is.
    ~ [Victor Robertson](https://github.com/vmrob)

My notes:
1. Use gdb or lldb to "run it in a debugger". Start (`run`) the program to completion until the segfault or other error occurs which crashes the program. With the program crashed, run `bt` (in either gdb OR lldb) to print the backtrace and see what happened from there.
1. The "other sanitizers" include LLVM's `asan`, `tsan`, `ubsan`, etc. You can see this list at the top of slide 2 here: https://llvm.org/devmtg/2015-10/slides/SerebryanyCollingbourne-BeyondSanitizers.pdf. Just Google for "llvm asan", for instance, for more info.
    1. Apparently, asan is an "address sanitizer" and looks for memory bugs where you're accessing "out of bounds" memory. It can potentially tell you the exactly where the out-of-bounds memory read/write bug is, including file and line number. (I need to look into this more and verify if this is all correct, or perhaps if it's one of the other LLVM sanitizers that can do this). Either way, I need to check out and learn how to use the LLVM sanitizers--I've never used them before.
        1. See also:
            1. https://stackoverflow.com/questions/57733527/how-to-configure-bazel-to-run-address-memory-sanitizer
                Ex:
                        bazel build -c dbg --config=asan path/to/module:target

                1. https://docs.bazel.build/versions/0.26.0/bazel-container.html
                1. https://github.com/bazelment/trunk/blob/master/tools/bazel.rc
            1. https://github.com/google/sanitizers/wiki/AddressSanitizer
1. Note that if your crash is a "signal SIGSEGV" "invalid address" and shows that all of your stack frames are 0s and at address 0, it may be because you are _writing outside of bounds of your memory pool or array or whatever_, corrupting the stack frame pointer and other debugging info with a bunch of 0x00s! Here's a sample crash printed in lldb when this happened:

        * thread #1, name = 'my_executable', stop reason = signal SIGSEGV: invalid address (fault address: 0x0)
            frame #0: 0x0000000000000000
        error: memory read failed for 0x0

    And here's a sample lldb backtrace (bt) printout from when this happened:

        (lldb) bt
        * thread #1, name = 'my_executable', stop reason = signal SIGSEGV: invalid address (fault address: 0x0)
          * frame #0: 0x0000000000000000

    So, look for these types of problems with your backtrace as signs that your bug may be that you are writing outside of your allocated (statically or dynamically) memory blocks, arrays, buffers, or other variables or objects. That's what my bug turned out to be in this case. <========== THIS! ==========

1. "Bisecting" the code (Victor's #4 above) means:
    A. (if at all possible) using `git bisect` to identify which commit introduced the change that caused the bug, or
    B. (if just looking at a large chunk of code that doesn't contain smaller, intermediate git commits) simply commenting out large sections of code half at a time, as able (in a binary search, or "bisecting" manner), until you get the bug. This can be really challenging in C or C++ where so much depends on each other, but if that's what you've got to do, that's what you've got to do! In languages like HTML this is much easier to do.

== General Debugger Setup: ==

1. If you need help locating your binary executable in your build output, try using `locate name_of_executable` to search your system for it.
1. Be sure to buld with debug symbols on: `-ggdb` (or `-glldb` for LLVM/clang's `lldb` debugger) and `-Og`, for instance, are recommended. `-g` and `-g3` may also work in place of `-ggdb`, but `-ggdb` is the best. Also, `-O0` may work in place of `-Og`, but the official gcc user manual recommends `-Og` over `-O0` for debugging. See my ans. here: https://stackoverflow.com/questions/63386189/whats-the-difference-between-a-compilers-o0-option-and-og-option/63386263#63386263, and the official manual here: https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#Optimize-Options. [UPDATE: PREFER `-O0` OVER `-Og`! See my ans.: https://stackoverflow.com/a/63386263/4561887]. For Bazel, see the `--copt` option described above to easily add these C build options in while building. Ex:

    time bazel build --copt=-ggdb --copt=-O0 --strip=never //path/to/my/target_dir/...  <=========== BEST DEBUG BUILD OPTIONS! (esp. for the repetitive edit-compile-debug development cycle!) ==========

  OR to build ALL:

    time bazel build --copt=-ggdb --copt=-O0 --strip=never //...

== gdb: ==

References:
1. https://www.gnu.org/software/gdb/
1. https://en.wikipedia.org/wiki/GNU_Debugger
1. https://www.onlinegdb.com/
    1. http://www.gdbtutorial.com/
    1. https://www.onlinegdb.com/blog/brief-guide-on-how-to-use-onlinegdb-debugger/
1. "Watchpoints" (AKA: "data breakpoints"): https://sourceware.org/gdb/onlinedocs/gdb/Set-Watchpoints.html
1. Google search for "gdb load relative path" [NEED TO STUDY!]: https://www.google.com/search?q=gdb+load+relative+path&oq=gdb+load+relative+path&aqs=chrome..69i57.3790j0j9&sourceid=chrome&ie=UTF-8
    1. How to point GDB to your sources [NEED TO STUDY!] - https://alex.dzyoba.com/blog/gdb-source-path/
1. Google "gdb tutorial" - https://www.google.com/search?q=gdb+tutorial&oq=gdb+tutorial&aqs=chrome.0.69i59l2j69i60j69i65l3.1554j0j7&sourceid=chrome&ie=UTF-8
    1. Super simple GDB intro from U of Maryland: https://www.cs.umd.edu/~srhuang/teaching/cmsc212/gdb-tutorial-handout.pdf

Note: it is a good idea to launch gdb from your root source directory, ie: at the base directory where your source code begins, so that if your source code paths for your symbols are relative, gdb can automatically find your source code! Otherwise, it will say `No such file or directory.`

Also google for "gdb cheatsheet" to find helpful resources online. Ex:
[Google search for "gdb cheat sheet"](https://www.google.com/search?q=gdb+cheat+sheet&oq=gdb+cheat+&aqs=chrome.0.69i59j69i57j69i60l3.3061j0j4&sourceid=chrome&ie=UTF-8)
1. *****https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf

TO LEARN:
1. Google "how to run crash dumps with GDB"
1. Google "core dump handler"
1. Google "gdb tutorial" - https://www.google.com/search?q=gdb+tutorial&oq=gdb+tutorial&aqs=chrome.0.69i59l2j69i60j69i65l3.1554j0j7&sourceid=chrome&ie=UTF-8

GDB USAGE:
1) Be sure to run gdb from the root of the source code so that all paths to the source code will work! Otherwise, paths may be broken and the source code may not be able to be displayed!
        cd /path/to/root/of/source/code
2) Run gdb, passing it the executable to load
        gdb /path/to/root/of/source/code/path/to/executable/compiled/with/debug/symbols/on
3) (Optional) Now press Ctrl + X, then A to enter the GUI/TUI (Textual User Interface) ncurses mode; see: https://undo.io/resources/gdb-watchpoint/5-ways-reduce-debugging-hours/
   Press Ctrl + 2 to cycle through 2-view modes. Press Ctrl + 1 to go back to 1-view mode. Press Ctrl + X, then A to exit or re-enter the TUI mode.
4) Add a breakpoint in main.cpp, at line 100 for instance
        break main.cpp:100
5) Run to that point, then wait about 3 to 5 seconds or whatever for it to run and stop at your break point
        run
6) Use gdb as desired; see the shortcuts and commands below and online on cheat sheets. The main ones are essentially this:
break file.cpp:100, r = run (restart from beginning), c = continue (until next break point), Ctrl + C = pause (send SIGINT interrupt to gdb), n = next (step over), s = step into, fin = finish (step up)

------------------------------------------------------
GDB debugging steps example:
- Full steps for how to build with Bazel, for example, then begin a gdb debug session!
------------------------------------------------------
[gdb example, full gdb debug example, full bazel gdb example, full bazel gdb debug example, example gdb debug, gdb debugging, gdb instructions, gdb demonstration]
    # Build (or build then test: replace `build` with `test`) with gdb debug symbols
    time bazel build --copt=-ggdb --copt=-O0 --strip=never //my/target_to_debug_1/... //my/target_to_debug_2/...; gs_alert
    # cd to where the (post-processed and with-auto-generated-files-added, if applicable) source code is
    cd ~/GS/dev/my_bazel_repo/build/my_bazel_repo
    # start gdb
    gdb
    # load the executable file to debug (I *think* it requires an absolute path, but it does
    # accept "~" just fine)
    file ~/GS/dev/my_bazel_repo/build/bin/path_to_my_executable
    # list first 10 lines of loaded source code
    l
    # (Optional) open the TUI (Text User Interface) window
    Ctrl + X, A
    # (Optional) switch the active window back to the gdb command prompt so arrow keys will
    # work here to look up old commands from the command history and all
    Ctrl + X, o
    # set break points wherever you want them; ex: in file main.cpp on line 75
    b main.cpp:75
    # when done setting break points, run `info break` to see all that are set, and use
    # `del <NUM>` to delete any you no longer need
    info break
    # run
    r
    # C'l'ear and refresh the screen in case any text printed by printf() or cout to stdout
    # has occured
    Ctrl + L
    # See what frame and line number the code is currently on
    frame
    # Now use `bt` or `where` to get a current stack frame `backtrace` to see `where` we are!
    # (ie: what calls exactly led to this location in the code).
    bt
    # C'l'ear and refresh the screen again when done studying the backtrace.
    Ctrl + L
    # Then use 'n'ext, 's'tep down, c'ontinue, 'fin'ish (step up), etc., as desired.
    # You can also use 'watch <var_name>` to watch variables (thereby setting a "watchpoint",
    # AKA "data breakpoint" to see when the variable changes), or 'print <var_name>' to print them,
    # or `x &my_var` to e'x'amine the **memory** at the address of variable 'my_var',
    # Etc. etc.
    # NB: Many commands, such as 'n'ext, 'c'ontinue, 'l'ist, etc, can be repeated simply by
    # pressing Enter again and again once you have typed the command the first time. This saves
    # a lot of time and allows you to rapidly go through the code.

------------------------------------------------------
gdb_short_cmd (or long_cmd) (gdbgui keyboard shortcut)
------------------------------------------------------

TUI (Text User Interface) shorcut keys ("Key Bindings")
See:
1. GDB User Manual: https://sourceware.org/gdb/current/onlinedocs/gdb/TUI-Keys.html
2. https://undo.io/resources/gdb-watchpoint/5-ways-reduce-debugging-hours/
Ctrl + X, A = enter/exit ncurses user interface mode (TUI--Text User Interface)
Ctrl + X, 2 = cycle through 2-window TUI modes
Ctrl + X, 1 = return to 1-window TUI mode
Ctrl + X, o = change active window to the 'o'ther window; allows you to change active view between the gdb command prompt and the TUI code window so that the arrow keys will change from scrolling the code window to recycling old commands, or vice versa.
Ctrl + L = refresh (c'l'ear and reload) the screen

help = see in-application help
help <cmd> = see help about command cmd; ex: `help watch`

file path/to/my_prog_to_execute = execute my_prog_to_execute

directory /path/to/my/source/code/rootdir
    set the source code root dir to this path so gdb knows where to find the source code! See: https://alex.dzyoba.com/blog/gdb-source-path/.
set substitute-path <from_path> <to_path>
    see here: https://alex.dzyoba.com/blog/gdb-source-path/; ex:
set substitute-path /home/avd/dev/cpython /usr/src/python
    [see also this cflag prefix option!]
gcc -fdebug-prefix-map=$(pwd)=/usr/src/python
    see here: https://alex.dzyoba.com/blog/gdb-source-path/; search for "" in `man gcc`:
  -fdebug-prefix-map=old=new
    "When compiling files in directory old, record debugging information describing them as in new instead." [this makes them instantly debuggable in gdb because they know right where to look for the source code!]. See: https://alex.dzyoba.com/blog/gdb-source-path/.

frame
    See what frame and line number the code is currently on. See also `l -` below.
list
    List the code lines around the current frame, or based on the last list end point if we just called `list`.
l
    'l'ist (list; same as above)
l <LINE_NUM>
    list 10 lines of source code centered at <LINE_NUM>; ex: `l 97`; note: just keep pressing "Enter" to keep listing 10 more lines of source code again and again, essentially scrolling down the file!
l -
    List the current line you are on, apparently? (need to test). Similar to `frame` above I think. See also `frame` above.
    Source: https://stackoverflow.com/questions/17480107/lldb-list-source-code.

info sources
    list all available source files; see: https://stackoverflow.com/questions/22821344/gdb-how-to-list-all-source-files-used-for-compilation/22821599#22821599
info functions
    list all available functions; see URL above
    [weird work-around to grep the above output]: https://stackoverflow.com/questions/41965454/gdb-grep-info-sources-files/41965636#41965636
info locals
    List all local variables on the current stack. These are all variables you can print with `p` or `print`. 
    See: https://stackoverflow.com/a/6261502/4561887

info break
    show all break points (delete them with `del <NUM>`); see: https://stackoverflow.com/questions/4340718/how-do-i-remove-a-single-breakpoint-with-gdb/11799263#11799263
del <NUM>
    delete a break point based on its NUMber shown by `info break`
del <NUM1> <NUM2> <NUM3> ...
    same as above; notice you can delete multiple breakpoints at once

break main.cpp:100
    set a break point in main.cpp at line 100
b main.cpp:100
    same as above
b 100
    set a break point **in the current file** at line 100
clear main.cpp:100
    clear/remove/delete the breakpoint you previously set at line 100 of main.cpp; NB: you can also use `info break` and `del <NUM>`; see: https://stackoverflow.com/questions/4340718/how-do-i-remove-a-single-breakpoint-with-gdb/11799263#11799263
bt
    backtrace: display the program stack (AKA: stack trace or stack frames)
where
    similar to backtrace; print backtrace of current stack frames. "Same as backtrace; you can think of this version as working even when you’re still in the middle of the program" (Slide 15 of https://www.cs.umd.edu/~srhuang/teaching/cmsc212/gdb-tutorial-handout.pdf).
up
    go up to higher stack frame
down
    go down to lower stack frame

watch foo
    set a "watchpoint" (AKA "data breakpoint") on variable `foo` to see when it changes! See: https://sourceware.org/gdb/onlinedocs/gdb/Set-Watchpoints.html
info watchpoints

----------------
PRINT
----------------
print my_var
    print current value of variable my_var (see Slide 12 of: https://www.cs.umd.edu/~srhuang/teaching/cmsc212/gdb-tutorial-handout.pdf)
print/x my_var
    print value of variable my_var in hex format (slide 12 above)
print/d my_var
    print my_var as decimal (signed integer)
print/u my_var
    print my_var as unsigned integer
print/<format> my_var
    print my_var according to the general `printf()`-style format chars, <format>
print my_ptr
    print the value of my_ptr, which contains the address the pointer is holding
    [See slides 20-21 of this intro. for the following use-cases: https://www.cs.umd.edu/~srhuang/teaching/cmsc212/gdb-tutorial-handout.pdf]
print &my_var
    print the address of (pointer to) my_var
print my_ptr->name
    print the "name" member of this pointer, assuming it is a ptr to a struct or class which contains this member
print my_ptr->value
    print the "value" member of this pointer, assuming it is a ptr to a struct or class which contains this member
print (*my_ptr).value
    same as above; this is also valid C/C++ syntax
print *my_ptr
    print the entire contents of this pointer! (not so easy to do in C or C++)
----------------
PRINT ARRAYS:
See my own ans: https://stackoverflow.com/questions/14502236/how-to-view-a-pointer-like-an-array-in-gdb/64055978#64055978
----------------
print *my_array@len
    Print the first `len` elements of `my_array`. See my answer here!: https://stackoverflow.com/questions/14502236/how-to-view-a-pointer-like-an-array-in-gdb/64055978#64055978
    Examples:
p *byteArray@16
    Print 16 bytes from `byteArray`. Result: `"\000\001\002\003\004\005\006\a\370\371\372\373\374\375\376\377"`
print/x *byteArray@16
    Print 16 bytes from `byteArray`, in hex format. Result: `{0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff}`
print/d *byteArray@16
    Print 16 bytes from `byteArray`, in signed integer format. Result: `{0, 1, 2, 3, 4, 5, 6, 7, -8, -7, -6, -5, -4, -3, -2, -1}`
print/u *byteArray@16
    Print 16 bytes from `byteArray`, in unsigned integer format. Result: `{0, 1, 2, 3, 4, 5, 6, 7, 248, 249, 250, 251, 252, 253, 254, 255}`

OBTAIN TYPES
ptype my_var
    Returns things like `type = unsigned short`
print &my_var
    Returns things like `(uint16_t *) 0x7ffffffefc2c`, revealing the pointer type is `uint16_t *`, meaning the variable type is just `uint16_t`! See my ans. here: https://stackoverflow.com/questions/9568201/gdb-show-typeinfo-of-some-data/63404160#63404160.

EXAMINE MEMORY
x <memory_addr>
    examine the memory at address memory_addr
x &my_var
    e'x'amine (examine) the memory at the address of variable 'my_var'! ie: see what bytes it contains!
x my_var_p
    same as above, assuming that my_var_p is already defined as a pointer to my_var.
help x
    learn more about the e'x'amine command.

(commands in parenthesis are for gdbgui, not gdb directly)
-----
r [run] (or run)
    run (start from beginning)
c [continue]
    continue until breakpoint
Ctrl + C
    send SIGINT interrupt signal to gdb to pause gdb and let you interact with it
n [next] (or right arrow)
    next (step over)
s [step] (or down arrow)
    step into
fin [finish] (or finish) (u) (or up arrow)
    step out or up out of a lower-level function or scope; 
    see:
    - https://unix.stackexchange.com/questions/297982/how-to-step-into-step-over-and-step-out-with-gdb and
    - https://stackoverflow.com/questions/24712690/step-out-of-current-function-with-gdb/24712736#24712736
(m)
    execute one machine instruction, stepping OVER function calls (cmd in parens is for gdbgui)
(,)
    execute one machine instruction, stepping INTO function calls (cmd in parens is for gdbgui)

STILL NEED TO STUDY & LEARN THESE ONES:
print <var_name>
display <var_name>
delete
    delete all breakpoints?
delete 1
    delete the 1st breakpoint

GDB LOGGING:
[gdb log to file, gdb file logging, gdb logging to file, logging gdb to file, log gdb to file; logging in gdb debugger]
See: https://sourceware.org/gdb/current/onlinedocs/gdb/Logging-Output.html

set logging on
set logging off
set logging file <file>
    default is gdb.txt
set logging file ~/temp/gdb.txt
    set to log here (then call `set logging on` to begin)
show logging
set trace-commands on
    echo (and log if logging is on) the command itself too! See: https://stackoverflow.com/questions/37530271/how-to-include-gdb-commands-in-logging-file/52146678#52146678.
flush
    Call this if logging doesn't seem to be showing up live in the file
----
So, here's how I like to start the logger! See my own ans. here: https://stackoverflow.com/questions/37530271/how-to-include-gdb-commands-in-logging-file/63403856#63403856.
----
set logging file ~/temp/gdb.txt
set logging on
set trace-commands on
show logging
flush
set pretty print on

== lldb: ==

References:
1. *****+GDB to LLDB command map: https://lldb.llvm.org/use/map.html

Best Bazel build command aliases to use the lldb debugger, assuming you have the `-glldb` build option available since you're using the clang compiler.
(Note: if you were using the gcc compiler instead, all you'd have to change I think is from `--copt=-glldb` to `--copt=-ggdb` [even for use with lldb] or perhaps to `--copt=-g3` or something).:

    ```bash
    alias bazel_build_lldb='time bazel build --copt=-glldb --copt=-O0 --strip=never \
    //my/target1/... //my/target2/...; gs_alert'
    alias bazel_test_lldb='time bazel test --copt=-glldb --copt=-O0 --strip=never \
    //my/target1/... //my/target2/...; gs_alert'

    # where you also have:
    alias gs_alert='gs_sound_bell; alert "task complete"'
    alias gs_sound_bell='echo -e "\a"'
    ```

Sample workflow:

    ```bash
    # make a code change, then do the "build --> fix the code --> build again" cycle repeatedly
    # until you get the build to pass:
    bazel_build_lldb
    # once it builds, run your unit tests:
    bazel_test_lldb
    # Oh no! A unit test fails but you can't figure out why! Go run `lldb` manually to investigate
    # and debug it.
    # Great, you found the bug! Make the code change, then build and run the tests again:
    bazel_test_lldb
    # Nice! All unit tests pass. Commit the code and create a GitHub PR (Pull Request) to bring
    # it into the main code base.
    ```

LLDB COMMANDS:

help cmd_name
    See the help menu and more info for command `cmd_name`.

breakpoint set -f main.cpp -l 100
    Set a breakpoint in file main.cpp on line 100.
    Same as `break main.cpp:100` in gdb.
br set -f main.cpp -l 100
    Same as the `breakpoint set` cmd above.
breakpoint list
    Show all breakpoints.
    Same as `info break` in gdb.
br l
    Same as the `breakpoint list` cmd above.
br delete
    Delete all breakpoints! See: https://gist.github.com/ryanchang/a2f738f0c3cc6fbd71fa#gistcomment-2137933.

bt
    backtrace (same cmd in gdb)

frame select
f
    Show the current lines and frame again.
    Same as `frame` (or perhaps `l -` too?) in gdb.
    Source: https://stackoverflow.com/a/17484386/4561887 and [my ans]: https://stackoverflow.com/a/64165024/4561887.

print
p var_name
    Pretty-print variable var_name. Can be used on structs, classes, other objects, etc. Its output looks really nice.

==================================
== gdb & lldb examples & notes: ==
== gdb: == lldb: ==
==================================

GDB to LLDB command map: **REALLY** USEFUL!: https://lldb.llvm.org/use/map.html  <================= **REALLY USEFUL** GDB <--> LLDB COMMAND MAP! ===============

REMEMBER: prefer optimization level `-O0` over `-Og` when debugging, as `-Og` may actually optimize out your ability to print certain variables! See my own answer here: https://stackoverflow.com/a/63386263/4561887.

`gdb` has `set print pretty on` to make printing a little nicer, like lldb does by default. Run this in gdb:

    set pretty print on
    p my_class
    p my_struct.whatever

To print a couple variables in GDB:

    time bazel build --copt=-ggdb --copt=-O0 --strip=never //path/to/target/...
    cd path/to/full/source/code
    gdb
    file path/to/executable
    Ctrl + X, A
    Ctrl + X, o
    break main.cpp:100
    r
    Ctrl + L
    print my_var_1
    print my_var_2

To print a couple variables in LLDB
(doing the same thing as above, but in LLDB):

    time bazel build --copt=-glldb --copt=-O0 --strip=never //path/to/target/...
    # [now start lldb here--I think this is just with `lldb`? Perhaps it has to be from the correct
    # source code dir too!? Then I have to load the executable somehow?]
    breakpoint set -f main.cpp -l 100
    thread continue
    print my_var_1  # or just `p my_var_1`
    p my_var_2

SUMMARY:
Notice that lldb *automatically* pretty-prints all objects/classes/structs, whereas in gdb you have to call `set pretty print on` first to get a similar effect! LLDB is a bit more modern and looks a bit nicer overall. It can also easily do **syntax highlighting** in the code lines it outputs (gdb can too, but I think it requires more work/external plugin support to do this). However, LLDB does NOT have a GUI nor TUI mode, whereas gdb *does* have a TUI mode. Overall, though, this isn't a big detractor from lldb because I usually end up navigating around to look at the code in my main source code editor or IDE anyway, so the TUI really isn't all that useful, even though I do like having it.


== gdbgui: ==

References:
1. https://www.gdbgui.com/
    1. Lots of great usage details in the screenshot tour! https://www.gdbgui.com/screenshots/
    1. Examples: https://www.gdbgui.com/examples/
    1. FAQ: https://www.gdbgui.com/faq/
        - esp. see the section titled "How do I make program output appear in a different terminal?"
1. GitHub: https://github.com/cs01/gdbgui/

Installation:
See: https://www.gdbgui.com/installation/
In short:

    sudo apt install python3-pip
    python3 -m pip install --user pipx
    python3 -m userpath append ~/.local/bin
    . ~/.bashrc  # re-source to make sure user PATH is up-to-date
    pipx install gdbgui

If you're missing any dependencies, you may get a warning. Install those as well, then try the `pipx install gdbgui` command again. Ex:

    # Install missing dependencies
    sudo apt install python3-venv
    # Try gdbgui pipx install command again
    pipx install gdbgui

To upgrade:

    pipx upgrade gdbgui

To uninstall:

    pipx uninstall gdbgui

Keyboard shortcuts: see (gdbgui keyboard shortcut) above.

USAGE:
- see the Examples in the References above.
1) Load the gdbgui server
gdbgui -h     = help menu
gdbgui --help = help menu
gdbgui = most basic usage; do auto-open a browser
gdbgui -r --project="/path/to/root_execute_dir" --remap-sources='{"/old/base/path": "/path/to/root_execute_dir"}' --gdb-args="--tty=$(tty)" = run the gdbgui server on a remote machine (-r, so don't auto-open a browser), setting the root dir for all source (--project) files to "/path/to/root_execute_dir", and remapping all source code paths from "/old/base/path/whatever.cpp" to the correct source code location on the remote machine of "/path/to/root_execute_dir/whatever.cpp". The `--gdb-args="--tty=$(tty)"` part at the end is a work-around for a [bug](https://github.com/cs01/gdbgui/issues/333), to redirect all stdout (ex: from `printf()`-type statements) to the terminal in which you launch `gdbgui`, so that it won't get lost and not published in the `gdbgui` either. This is the bug report: https://github.com/cs01/gdbgui/issues/333. Just be sure to watch for all stdout messages in the terminal where you launched gdbgui instead of in the console in the gdbgui in the browser!
2) In the "Load Binary" box at the top, type in the path to the binary (use the path from the *remote* machine's perspective if gdbgui is running on a remote machine): "/path/to/root_execute_dir/my/binary", and click "Load Binary". Now it will automatically load and display the source code, so long as you compiled it with `-g` (ok), `-g3` (better), or `-ggdb` (best I think), AND you properly set up your `--remap-sources` option, if required.
3) Click the "Run" button (the far left of the 6 buttons in the top-right of the browser window), and wait up to 5 or 6 seconds or so for the binary to begin executing.
4) Now debug with the 6 main buttons in the top-right, and be sure to watch the *terminal* from which you launched gdbgui for all stdout (`printf()`-like) output if you have used the `--gdb-args="--tty=$(tty)"` option. Otherwise, the output will be right inside the console at the bottom of the gdbgui.

Here's some gdbgui debug tips:
- Learn more in the screenshot tour here: https://www.gdbgui.com/screenshots/
- and in the FAQ here:
    1. Hover your mouse over the code to see clickable links and pop-up information on functions and variables and things.
    2. Use the search bar at the left to do a hash-table-based fuzzy search lookup of any source files, in order to load them. The root path it shows here is what your `--project=` option configured above.
    3. Use the gdb input text bar at the very bottom of the screen to input any gdb command manually. This gives you FULL access to ALL gdb commands, even those which are not integrated into the gui otherwise.
    4. In the right-hand panel you have a bunch of options. You can select threads and view the stack trace of the threads, for instance.
The gdbgui tool makes gdb much more intuitive and easy to use!


====================================================================================================
= googletest (gtest) / googlemock (gmock): =
====================================================================================================

See the "eRCaGuy_dotfiles/googletest" directory, **especially** the "eRCaGuy_dotfiles/googletest/insights.md" file, which has a bunch of my own personal documentation, notes, and insights!

== test (`TEST() {}`, `TEST_F() {}`) order: ==

You can NOT rely on google tests to be run in any particular order. Also, the order can be shuffled with `--gtest_shuffle`; see: https://github.com/google/googletest/blob/master/googletest/docs/advanced.md#shuffling-the-tests


====================================================================================================
= linters, Static Code Analyzers, clang-format, etc.: =
====================================================================================================
[linters, clang-format]

GENERAL LIST OF TOOLS:
NAME                LANGUAGE
------------        -------------
clang-format        C/C++
clang-tidy          C/C++
clang sanitizers    C/C++
shellcheck          Linux/Posix shell: bash/sh, etc. <=== really useful!
flake8              Python
mypy                Python static type checker (http://mypy-lang.org/, https://mypy.readthedocs.io/en/stable/)
black               Python (https://pypi.org/project/black/)
pylint              Python (https://pypi.org/project/pylint/)
roslint             Python (for ROS packages?) (http://wiki.ros.org/roslint)
yamllint            YAML (https://yamllint.readthedocs.io/en/stable/quickstart.html) (http://www.yamllint.com/)
buildifier          Bazel BUILD/*.bzl files (https://github.com/bazelbuild/buildtools/tree/master/buildifier)

== clang-format: ==
[C/C++]

A source code automatic style formatting tool for C and C++.

References:
1. Main documentation, setup, instructions, etc! https://clang.llvm.org/docs/ClangFormat.html
2. Download the Windows & other installers/executables: https://llvm.org/builds/
3. Clang-Format Style Options: https://clang.llvm.org/docs/ClangFormatStyleOptions.html

Install in Ubuntu with `sudo apt install clang-format`; source (note I also have an answer here): https://stackoverflow.com/questions/20756924/how-can-i-install-clang-format-in-ubuntu

Help:
    clang-format --help
    man clang-format

To generate a .clang-format file as a starting point:
-See: https://clang.llvm.org/docs/ClangFormat.html
    clang-format --style=llvm --dump-config > .clang-format
    OR
    clang-format --style=google --dump-config > .clang-format

Main clang-format tools & commands include:
    clang-format [options] [<file> ...] = the main command; see: https://clang.llvm.org/docs/ClangFormat.html

    clang-format-diff = a python script that allows you to format a git diff patch; see: https://clang.llvm.org/docs/ClangFormat.html

    git clang-format = a tool blended in with git to allow you to format just the lines you touched before you git commit them [GS: I don't like this work-flow; I'd rather do a commit and THEN go back and run a command to format *the entire file* for any file I touched, instead. Then, I'll make that format run a separate commit.]

Example usages:
    clang-format --style=google my_file.cpp > my_file_formatted.cpp = format a file and send the output to a separate file, using a preconfigured style
    clang-format -i --style=google my_file.cpp = format this file in-place!
  Use `--verbose` to also print the file names processed!
    clang-format -i --verbose --style=google my_file.cpp = same as above, but print the name of the file processed (particularly useful when you have a script which processes many files and you want the user to see as output a list of the files processed!)
  Use `--style=file` to "load style configuration from .clang-format file located in one of the parent directories of the source file (or current directory for stdin)".
    clang-format --verbose -i --style=file my_file.cpp = format my_file.cpp in place, using the .clang-format file located in one of the parent directories of the source file, printing the name(s) of the file(s) processed. <======= BEST OPTION FOR MANUALLY-SPECIFIED FILE(S)! =======
    clang-format --verbose --style=file my_file.cpp | diff -u --color=always my_file.cpp - = do a PREVIEW of the command just above! ie: run the clang-formatter with the same commands, except NOT modifying the file 'i'n-place, and send the output to stdout (which is the default of clang-format), where it will then be piped via stdin to the `diff` command as the right file (-) to compare to the left file, which is the original my_file.cpp! In this way, you've manually created a means of PREVIEWING a clang-format change to see what changes WILL be made, withOUT actually making these changes! See the == diff: == section below for further details. <========= BEST **PREVIEW** COMMAND FOR CLANG-FORMAT! =========
  See here for where I've used clang-format in a project before!
    https://github.com/AmboVent-1690-108/AmboVent/blob/master/3-Software/Arduino/run_clang-format.sh
    And it's format file:
    https://github.com/AmboVent-1690-108/AmboVent/blob/master/3-Software/Arduino/.clang-format

Whenever I do a `git commit`, however, I'd like to format *all parts of all files I have touched*. To do this, you can see which files were changed between two commits like this:
    git diff --name-only commit1~..commit2  # Note that the tilde (~) is required to specify the commit *before* commit1, because otherwise commit1 would *not* be included in determining which files were changed.
Then you can manually clang-format all of those files, OR (I think--needs to be tested), you can automate the process like this:
    clang-format --verbose -i --style=file $(git diff --name-only commit1~..commit2)  <======= NEEDS TO BE TESTED, BUT SHOULD BE THE BEST OPTION FOR AUTOMATICALLY-SPECIFIED FILES! ======

== clang-tidy: ==
[C/C++]

A source code static analysis (programming errors, style, best practices, bug checker) tool.

References:
1. https://clang.llvm.org/extra/clang-tidy/
1. [What's the difference between clang-format and clang-tidy? Do they have different configuration options? I'm only using clang-format so far.](https://news.ycombinator.com/item?id=19349009)

== clang sanitizers: ==
[C/C++]

Sanitizers are built into the clang (LLVM) compiler, and designed to find problems, such as undefined behavior.

1. There are a bunch of sanitizers; see them all here: https://clang.llvm.org/docs/index.html; search this page for "sanitizer"; ex:
    1. https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
        1. Finds undefined behavior, such as signed overflow
    1. https://clang.llvm.org/docs/AddressSanitizer.html
        1. Finds address problems, such as use after free, out of bounds access, double free, etc.
    1. https://clang.llvm.org/docs/ThreadSanitizer.html
        1. Detects data races.
    1. https://clang.llvm.org/docs/MemorySanitizer.html
        1. Detects uninitialized reads.
    1. etc.

Example of using the undefined behavior sanitizer:
- Read more here: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
Normal clang build command for a single-file project, test.cc:
    clang++ test.cc  # build it
    ./a.out          # run it
And now building the same project, but "sanitizing" for (looking for) undefined behavior:
    clang++ -fsanitize=undefined test.cc  # build it in sanitize mode
    ./a.out  # run it
    # Results: undefined behavior found while running the application!
    #       test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'

== shellcheck: ==
[Linux/Posix shell/sh/bash]
- bash/shell script file checker/linter;
- **VERY HELPFUL** when writing bash (or other Linux shell) scripts!

REFERENCES:
1. https://www.shellcheck.net
1. https://github.com/koalaman/shellcheck

shellcheck -x file1.sh file2.sh file3.sh = check the shell program; the `-x` means "e'x'ternal sources", and apparently allows shellcheck to follow any file the script may source, thereby checking it as well [I think--I need to play around with this some more still].
shellcheck --external-sources file1.sh file2.sh file3.sh = same as above
optionally use `-e ERR_CODE1,ERR_CODE2,ERR_CODE3` to ignore ('e'xclude) certain 'e'rror codes that `shellcheck` might otherwise output, but that you don't care about; see `man shellcheck` for details! Ex:
shellcheck -x -e CODE1,CODE2,CODE3 file1.sh file2.sh file3.sh = see explanation just above

== Python linters (General): ==
[Python]

REFERENCES:
1. https://realpython.com/python-code-quality/
1. https://dbader.org/blog/python-code-linting

== mypy: ==

I need to look into this more!
Python static type checker (http://mypy-lang.org/, https://mypy.readthedocs.io/en/stable/).

== flake8: ==
[Python]
*****If in doubt, just start here when it comes to choosing a Python linter! It seems to be the most-recommended and the easiest to get started with.

REFERENCES:
1. https://flake8.pycqa.org/en/latest/

python3 -m pip install flake8
flake8 some/folder/myfile.py
flake8 some/folder/

== black: ==
[Python]

https://pypi.org/project/black/

== yamllint: ==
[yaml]

REFERENCES:
1. http://www.yamllint.com/
1. https://yamllint.readthedocs.io/en/stable/quickstart.html
1. https://yamllint.readthedocs.io/en/stable/configuration.html - learn how to set up your .yamllint configuration file here!

yamllint myfile.yaml = lint myfile.yaml
yamllint -c path/to/.yamllint myfile.yaml = lint myfile.yaml according to the config rules declared in your "path/to/.yamllint" config file; see more here for a default config file and info on how to use and configure it! https://yamllint.readthedocs.io/en/stable/configuration.html.
yamllint -c .yamllint myfile.yaml = same as above, but specify the path to the ".yamllint" config file to be right here in the current directory we are in!
yamllint -c myfile.yaml = same as above, but "look for a configuration file in the [default] locations (by order of preference)". See: https://yamllint.readthedocs.io/en/stable/configuration.html. The first place it looks is for a ".yamllint" file in the current working directory, for instance.
    UPDATE: actually, I think you must simply leave off the `-c` to get the default behavior it describes on where it will search for a config file. Sooo, do this instead (I think):
yamllint myfile.yaml = correct form (I think) to get the default behavior described just above.


====================================================================================================
= tmux: =
====================================================================================================

EXCELLENT how-to video! https://www.youtube.com/watch?time_continue=5&v=BHhA_ZKjyxo&feature=emb_logo
EXCELLENT SHORTCUTS & CHEAT-SHEET!: https://gist.github.com/MohamedAlaa/2961058  <=========

tmux = create a new tmux session
tmux new = same as `tmux`
tmux new -s <session_name> = create a new tmux session called "session_name"
tmux ls = list open tmux sessions
tmux list-sessions = same as `tmux ls`!
tmux attach -t <session_num> = re-attach back to 't'arget session session_num!   <===== ATTACH!
tmux a -t <session_num> = same as above ("a" is an alias for "attach")
tmux a = attach the only available session (assuming only one is available) <======= MY MOST COMMON USAGE!
tmux kill-session -t <session_name_or_num> = kill this session! (or, you can just attach to it then type `exit` repeatedly until it's all exited/killed)
tmux rename-session [-t current_name] [new_name] = rename a tmux session! See: https://superuser.com/questions/428016/how-do-i-rename-a-session-in-tmux/428025#428025

exit = exit the window

Ctrl + B, then <cmd> = have tmux run <cmd>:  <=======
== LIST OF CMDS: ==
:<manual_cmd> = run <manual_cmd>
:split-window = do horizontal split (same as " below!)
=== Windows: ===
c = create window
, = rename window
p = previous window
n = next window
w = list windows
=== Panes (splits): ===
% = vertical split
" = horizontal split
o = swap panes [ie: change from one pane to another, within the same window]
x = kill pane
=== Sessions: ===
d = detach session (leaving it running on the server)!                                  <===== DETACH!
$ = rename current session

tmux source-file ~/.tmux.conf = (unconfirmed--maybe is the wrong command?) re-source your ~/.tmux.conf tmux config file to bring in its latest changes! See here: https://sanctum.geek.nz/arabesque/reloading-tmux-config/
tmux source ~/.tmux.conf = (try this instead maybe--looks more legitimate!) same as above apparently--need to try it out still; see here: https://unix.stackexchange.com/questions/66606/tmux-not-sourcing-my-tmux-conf/66607#66607; has lots of upvotes, so looks more legitimate

====================================================================================================
= git: =
====================================================================================================

GENERAL REFERENCES:
1. Stack Overflow (do general searches)
2. [GitHub git cheat sheet](https://github.github.com/training-kit/downloads/github-git-cheat-sheet/)

MY QUICK-REFERENCE SHEET (frequently my own notes/answers):  <========= VERY USEFUL TO HELP MYSELF AND OTHERS =========
1. BEGINNER:
    1. [my ans] https://stackoverflow.com/questions/4470523/create-a-branch-in-git-from-another-branch/63418267#63418267
2. INTERMEDIATE:
    1. [my ans] https://stackoverflow.com/questions/1670970/how-to-cherry-pick-multiple-commits/69472178#69472178
    1. [my ans] https://stackoverflow.com/questions/5738797/how-can-i-push-a-local-git-branch-to-a-remote-with-a-different-name-easily/70302053#70302053
    1. Each branch is actually 3 branches: https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely/23961231#23961231
    1. [my info] resolving merge conflicts: search this document for the section titled "RESOLVING MERGE CONFLICTS"
3. ADVANCED:
    1. [my ans] https://stackoverflow.com/questions/2364147/how-to-get-just-one-file-from-another-branch/65258783#65258783
    1. [my ans] https://stackoverflow.com/questions/21025314/who-is-us-and-who-is-them-according-to-git/63911630#63911630

.gitignore
    [a gitignore file for EVERYONE for just this repo!] a file commited into a repository to specify files to ignore and not commit in that repository; you can have multiple copies of this file by putting a different copy of the file in a sub-folder in your repo, to apply to only that folder and down
.git/info/exclude
    [a gitignore file JUST FOR ME for just this repo!] same as .gitignore, but does NOT get commited into the repo; therefore, it ONLY applies to your specific clone of the repo, which is nice if you have certain things you'd like to exclude but your teammates don't, so they don't want your list of exclusions commited into the main, shared .gitignore file in the repo; see: https://stackoverflow.com/questions/22906851/when-would-you-use-git-info-exclude-instead-of-gitignore-to-exclude-files/22906950#22906950

git alias = print out all of your aliases you have defined in your config file(s), such as in "~/.gitconfig" (or locally in a single repo I think too, in "/path/to/myrepo/.git/config")

"git-" + [TAB] [TAB] = see all programs or commands in your PATH (from git directly OR custom or 3rd-party git programs) whose names begin with "git-" (convention: name + the dash symbol), such as "git-alias". These programs can automatically be run withOUT the dash, because git automatically searches your PATH for this naming convention and makes them available. Therefore, a program named "git-alias", for example, can be run as `git alias`, withOUT the dash! [git-whatever]
See here for where I first learned this: http://barkas.com/2018/git-alias-bash-functions-with-arguments/#git-alias-in-your-path

git config <variable_name> [value]
    Read and write git variables. Read and print the value of the git variable `variable_name`, optionally setting it to `value`. 
    From `man git config`: "Get and set repository or global options."
git config [file-option] <variable_name> [value]
    See above, except read/write explicitly to the 'file-option' configuration file. Options include, in order from widest to narrowest scope: '--system', '--global', '--local', and '--file'. See `man git config` for details. 
git config --global <variable_name> [value]
    See above, except read/write explicitly to the '--global' configuration file, which is stored in "~/.gitconfig". See details above.
---------
EXAMPLES:
---------
git config merge.renameLimit
    Read the value of the `merge.renameLimit` variable, if it is set. 
git config merge.renameLimit 10000
    Set the value of the `merge.renameLimit` git variable to `10000`. 
    See my comment under this answer, where I do this: https://stackoverflow.com/questions/7830728/warning-on-diff-renamelimit-variable-when-doing-git-push/28064699#28064699.
git config branch.main.remote
    <===============
    Read out the `main` branch's default-tracking `remote` name. Ex: if ".git/config" contains this:
    ```
    [branch "main"]
        remote = origin
        merge = refs/heads/main
    ```
    ...then `git config branch.main.remote` will return `origin`. 
---------
YOU CAN INVENT VARIABLES AS YOU SEE FIT. (I am inventing the `blametool.editor` variable below):
---------
Example: this command: `git config --global blametool.editor subl` adds these lines to the bottom of your global "~/.gitconfig" file:
```
[blametool]
    editor = subl
```
And you can read out that variable value, 'subl', with: `git config blametool.editor`.
---------
SUMMARY:
---------
git config --global blametool.editor subl
    Writes this to your global "~/.gitconfig" file:
            [blametool]
                editor = subl
git config blametool.editor
    Reads 'subl' from the settings you just set above. Since we didn't specify '--global' when reading here, this will read all of the git config files, retaining the variable value found in the narrowest scope (ie: any value found in the '--local' config files takes precedent over '--global', which takes precedent over '--system', etc.).

git branch -a
    show ALL branches, even remote-only branches
git branch -r
    show ONLY 'r'emote branches
git branch -r | grep gabriel.staples
    show all of my remote branches (which, by my convention, begin with "gabriel.staples_")
git branch -d -r origin/mybranch
    delete remote branch; see: https://stackoverflow.com/questions/5094293/git-remote-branch-deleted-but-still-it-appears-in-branch-a/5096739#5096739
git branch -rd origin/mybranch
    same as above
git branch -vv
    <===============
    Show all branches, including their locally-stored remote-tracking ("upstream", '-u') branches. Ex: branch "main" might track the locally-stored remote-tracking branch named "origin/main", which tracks the "main" branch on the remote named "origin".  This might be shown like this. Notice the "[origin/main]" part:
    ```
    * main                       c99f1f0 [origin/main] README: improve ex. `rg` to `fzf` cmd to add color and line numbers
    ```
    See: https://stackoverflow.com/a/23998108/4561887

git checkout <branch_name> -- <paths>
    Check out just the file or files in `<paths>` from branch or commit hash `<branch_name>`.
    See: original source: http://nicolasgallagher.com/git-checkout-specific-files-from-another-branch/
    [my ans] https://stackoverflow.com/questions/2364147/how-to-get-just-one-file-from-another-branch/65258783#65258783

git fetch <remote> <srcBranch>:<destBranch>
    Fetch and pull the latest `srcBranch` from `remote` to both `origin/srcBranch` AND to local `destBranch`, withOUT checking out `destBranch` first! 
    See: https://stackoverflow.com/questions/18857570/git-pull-without-checkout/25776415#25776415
    Ex:
git fetch origin master:master
    Fetch and pull (merge) the latest `master` branch from remote `origin` to both `origin/master` AND to local `master` withOUT checking out `master` first!
    See source from above: https://stackoverflow.com/questions/18857570/git-pull-without-checkout/25776415#25776415

git add -A = add (stage changes for) all changes and files, including new files or actions to delete files
git add . = add (stage changes for) only those files which are already tracked (have been previously commited)
git add --patch <filename> = interactively add hunks/parts/chunks of filename, as desired! See here: https://stackoverflow.com/questions/1085162/commit-only-part-of-a-file-in-git/1085191#1085191
git add -p <filename> = same as above

git gui
    Open the GUI tool to do things like stage hunks, lines, or files; very useful for breaking up diffs/PRs! See: https://stackoverflow.com/questions/1085162/commit-only-part-of-a-file-in-git/1085202#1085202
tig
    A fancy ncurses-based GUI-*like* tool to navigate local or locally-pulled git repos

git remote update origin --prune
    Update the **local list** of remote branches, (I think) pruning all locally-stored branch names which exist locally but NOT remotely.
    See: [When does Git refresh the list of remote branches?](https://stackoverflow.com/a/36358502/4561887)

git difftool 
    Show just the changes that are NOT staged for commit (ie: in the index, or "added") since the last commit (HEAD).
git difftool --cached
    Show just the changes that ARE staged for commit (ie: in the index, or "added") since the last commit (HEAD).
git difftool HEAD
    <====== BEST COMMAND! ======
    Show BOTH SETS OF CHANGES ABOVE: ie: everything that has changed since the last commit (HEAD), meaning: any changes since then, including both _staged_ (in the index, or "added") AND _unstaged_ (not yet "added") changes!
    Therefore, `git difftool HEAD` is essentially the combination of `git difftool` PLUS `git difftool --cached`:
        `git difftool HEAD` = `git difftool` + `git difftool --cached`
---
git diff = look at all **unstaged** changes (those NOT yet added with `git add`)
git difftool = same as above, except view the changes in your "git difftool" (ex: meld) instead of via the `git diff` command line
git diff --cached = look at just the **staged** changes (those added with `git add`)
git difftool --cached = same as above, except view the changes in your "git difftool" (ex: meld) instead of via the `git diff` command line
git diff --name-only   commit_hash
    Only see a list of changed files by filename. See: https://stackoverflow.com/questions/1552340/how-to-list-only-the-file-names-that-changed-between-two-commits. 
    Sample output:
            $ git diff --name-only
            file1.h
            file2.h
            file3.h
git diff --name-status commit_hash
    <======= VERY USEFUL! ========
    [MUCH MORE USEFUL THAN THE CMD ABOVE!] see a list of filenames and status! Ex: indicators for modified, deleted, added, etc.
    From `man git diff`: "Show only names and status of changed files. See the description of the `--diff-filter` option on what the status letters mean."
    Sample output ('M' means "'m'odified"--see `man git diff` and search for "--diff-filter="):
            $ git diff --name-status
            M       file1.h
            M       file2.h
            M       file3.h
git diff --name-only --diff-filter=d commit_hash
    <======= VERY USEFUL to see all changes EXCEPT file deletions! ========
    Do NOT include (ie: filter out) all 'd'eleted files! See `man git diff` and search for "--diff-filter=".
    Replace `--name-only` with `--name-status` for details about how each file was changed. 
    See my answer here!: https://stackoverflow.com/questions/30905086/git-list-of-all-changed-but-not-deleted-files-in-a-commit/66649684#66649684
    See also this particular answer: https://stackoverflow.com/questions/5096268/how-to-get-a-list-of-all-files-that-changed-between-two-git-commits/50521039#50521039
    [keywords: git diff filter; filter git diff].
====vvvv `git whatchanged` and `git log --name-status` vvvv====
git whatchanged
    <======= [recommended to use `git log --name-status` instead] ========
    See all changed files over time. Like `git log`, but showing all files changed too and whether they were `A`dded, `M`odified, etc.
    See my answer here!: https://superuser.com/a/1636160/425838
git whatchanged --diff-filter=A
    Same as above, but show only Added files.
    See my answer here!: https://superuser.com/a/1636160/425838
git log --name-status
    <======= VERY USEFUL ========
    See all changed files over time. Like `git log`, but showing all files changed too and whether they were `A`dded, `M`odified, etc.
    Very similar to `git whatchanged`, but even simpler output, with slightly less information at the left-hand-side of each file shown.
    See my answer here!: https://superuser.com/a/1636160/425838
git log --name-status --diff-filter=AM
    Same as above, but show only Added and Modified files.
    See my answer here!: https://superuser.com/a/1636160/425838
====^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^====
git diff --stat commit_hash...
    [keywords: standup update stats; update stats for standups]
    <=================== BEST DETAILED STATUS! ===================
    Show detailed statistics of what you've added on your branch since commit `commit_hash`.
    This is a graphical +++--- representation of changes, with color! Very nice! See the last line of this output for totals. 
    Github uses this to show changes in your PR, I think!
    Sample output:
            $ git diff --stat
             file1.h      |  2 +-
             file2.h      | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------------
             file3.h      |  9 ++++++++
             3 files changed, 84 insertions(+), 21 deletions(-)
git log --oneline commit_hash...HEAD | wc -l
    [keywords: standup update stats; update stats for standups]
    <================ GOES WELL WITH STATS ABOVE! ================
    Count and display the number of commits I have added after commit `commit_hash` through to the current commit, `HEAD`.
    This is a useful statistic to display along with the one above! 
    Useful to report during team "standup" meetings, for instance, so people can be aware of the quantity of changes you're making.
git diff --numstat commit_hash
    if you sum all the numbers in both columns this outputs, you'll get the same results as `--shortstat` below, which is what GitHub uses to show the number of files changed, lines added, and lines deleted! See the last line of this output for that done for you. 
    Sample output: 
    (notice that the 1st column is _lines added_, and the 2nd column is _lines deleted_):
            $ git diff --numstat
            1       1       file1.h
            74      20      file2.h
            9       0       file3.h
git diff --shortstat   commit_hash
    "Output only the last line of the --stat format containing total number of modified files, as well as number of added and deleted lines." (from `man git diff`). 
    A 1-line summary showing number of files changed, number of lines added ("insertions(+)"), and number of lines deleted ("deletions(-)"). This is how GitHub gets their +N_added/-N_substracted number summary for each PR! To see a more detailed view for each individual file, use `git diff --numstat` or `git diff --stat`!
    Sample output:
            $ git diff --shortstat
             3 files changed, 84 insertions(+), 21 deletions(-)
    - this shows the GitHub-like output with the numbers of files and lines added and deleted!
    <======= MY FAVORITE SHORT STATUS I THINK (^^^) =======
git diff --dirstat     commit_hash
    Show the percent of changes by directory.
    Sample output:
            $ git diff --dirstat
              86.1% dir1/
              12.6% dir2/
git diff --word-diff
    Highlight changes on a word-by-word basis, rather than a line-by-line basis
git diff --cached --ignore-all-space --word-diff=color | sed -E "s/\033\[3[12]/\0;7/g"
    <==== NEED TO STUDY THIS AND TRY IT OUT STILL! ====
    See here: https://github.com/ymattw/ydiff/issues/99#issuecomment-803365676
git diff --word-diff=plain
    Same as above (`plain` is the default word-diff _mode_).
git diff --word-diff[=<mode>]
    Optionally insert a mode: `color`, `plain` (default), `porcelain`, `none`
git diff --word-diff=color
    [nice for a human to look at] just use colors to distinguish added (green) and deleted (red) parts, rather than also including [-some deleted wods-] and {+some added words+} markers <=========== GOOD! ===========
git diff --word-diff=porcelain
    a good format to be parsed by computers/scripts
git diff --word-diff-regex=<regex>
    use a custom regex to define what a word is
git diff --word-diff-regex=.
    do a diff on a CHARACTER-BY-CHARACTER BASIS!--showing deleted chars in [-some chars-] and added ones in {+some chars+}
    See: https://stackoverflow.com/questions/3231759/how-can-i-visualize-per-character-differences-in-a-unified-diff-file/7870727#7870727
    [keywords: word diff, char diff, diff by characters, char by char diff, git diff chars, git diff words, git diff by chars, git diff char-by-char, git diff letters, git diff letter-by-letter, git diff letter by letter, letter diff, char diff]
git diff --color-words=.
    do a diff on a CHARACTER-BY-CHARACTER BASIS, except just showing COLORS only, instead of the [- -] and {+ +} symbols too! THIS IS THE BEST FOR CHAR-BY-CHAR COMPARISONS! DO THIS! <=========== BEST CHAR-BY-CHAR DIFFS! [this must be what meld uses under the hood] =============
    See the comment under this answer: https://stackoverflow.com/questions/3231759/how-can-i-visualize-per-character-differences-in-a-unified-diff-file/7870727#7870727
etc. etc.
SUMMARY (see: https://makandracards.com/makandra/28067-git-diff-per-word-or-character):
git diff
    git diff **line-by-line** comparison  <===== LINE-BY-LINE! ======
git diff --color-words
    git dif **word-by-word** comparison   <===== WORD-BY-WORD! ======
git diff --color-words=.
    git diff **char-by-char** comparison  <===== CHAR-BY-CHAR! ======

git log = show the git log history
git log --oneline = show each commit as a single line only
git lg = show the git log history in a condensed form, with graphics lines to show forks, branches, and merges; this is VERY USEFUL! <========
    See: "eRCaGuy_dotfiles/home/.gitconfig" for how to create this `lg` alias for git, and
    https://coderwall.com/p/euwpig/a-better-git-log for where I originally got it from!

-----
RESOLVING MERGE CONFLICTS  <=========== VERY USEFUL! ============
- Imagine you are on `feature_branch`, merging in the latest `master` into it, to bring the latest upstream changes from `master` into your `feature_branch`. Here's how: 
[keywords: fix merge conflicts, fixing git merge conflicts, fixing git merge conflicts, git merge help, git merge find changes, find git merge changes, find changes in git merge, find changes during git merge, see git merge changes, seeing git changes during merge, seeing git merge changes, advanced merge conflict resolution, advanced git merge conflict resolution]
-----
        # fetch latest master changes from GitHub; use `upstream` instead of `origin` if necessary
        git fetch origin master:master
        git checkout feature_branch
        git merge master
        # merge conflicts result here
        # 1. see and make a mental note of what changes happened **on `master`** in your files with conflicts
        git difftool $(git merge-base master feature_branch)..master file1.cpp file2.cpp file3.cpp
        # 2. see and make a mental note of what changes happened **on `feature_branch`** in your files with conflicts
        git difftool $(git merge-base master feature_branch)..feature_branch file1.cpp file2.cpp file3.cpp
        # manually resolve conflicts
        # then add (stage) your fixed files into the git index
        git add file1.cpp file2.cpp file3.cpp
        # finish the merge
        git merge --continue

-----
FIND ALL GIT COMMITS WHICH ARE ON ONE BRANCH BUT NOT ON ANOTHER!
-----
[keywords: git commits on one branch but not another, git commits not on branch, git commits in one branch but not another]
git log --no-merges branch1 ^branch2 ^branch3
    show all commits which are ONLY on branch1, but NOT on branch2 or branch3, omitting all merge commits since they aren't new changes! See: https://stackoverflow.com/questions/1710894/using-git-show-all-commits-that-are-in-one-branch-but-not-the-others/4207176#4207176 <========== SUPER USEFUL TO SEE WHAT CHANGES A BRANCH CONTAINS ON IT! ============
    This is VERY USEFUL to see, for instance, what are all of the feature commits we've added to a long-running release branch named "branch1", into which which we have periodically been merging the latest master. Now, we can see which commits are in any given branch but not in master! Ex:
git log --no-merges branch1 ^master
    show all NON-merge commits in branch1 which are NOT in master!
git log --oneline --no-merges branch1 ^branch2 ^branch3
    same as above, but show only one line per commit! <======= EXCELLENT! (& SIMPLEST) ========
git lg --no-merges branch1 ^branch2 ^branch3
    same as above, but using the `git lg` git alias instead, to show condensed (one-line) output with extra information! <======= BEST! (perhaps) ========
-----
HOW TO **COUNT** HOW MANY COMMITS ARE IN ONE BRANCH BUT NOT ANOTHER:
-----
git log --oneline ^master HEAD | wc -l
    Count how many commits are on the current branch (`HEAD`), but NOT on `master`. 
    See my answer here: https://stackoverflow.com/questions/1710894/using-git-show-all-commits-that-are-in-one-branch-but-not-the-others/66201217#66201217

git log -p
    See the git log view except showing a "patch", or `git diff` type output for each commit as well, so you can see exactly what the changes were for each commit in the log!
git log --patch
    Same as above (the longer version of it is all). 

SEE ALL GIT COMMITS WHICH TOUCHED A SPECIFIC FILE. See also my Q on Stack Overflow here!: https://stackoverflow.com/questions/65929317/whats-the-difference-between-git-log-some-file-and-git-log-follow-some
[keywords: git commit one file, git commit 1 file, got log one file, git log 1 file, git patch 1 file, git log specific files]
-----
git log -- file.cpp
    View just the commits which touched this file!
git log --follow file.cpp
    Similar to the cmd above, but more specific just to this file (seems to ignore merges)
git log --follow master...HEAD file.cpp
    Show all changes in file 'file.cpp', following it through file renames (if applicable), over the "revision range" from branch `master`...(to) `HEAD`, or current state.
    SUPER USEFUL! <===============
git log --follow --patch master...HEAD file.cpp
    Same thing as above, except also show the `git diff`-style "patch" changes too.
    SUPER USEFUL! <======== SUPER USEFUL! ========
git log --follow --patch -U20 master...HEAD file.cpp
    Same as above, but show more "git diff" type context (lines) above and below the changes--namely: 20 lines each above and below, instead of the default 3 lines or whatever.
    SUPER USEFUL! <======== SUPER USEFUL! ========
git log -p -- file.cpp
    Same thing as `git log -- file.cpp`, except view the "patch view" of the git log, which shows a git diff output to show the changes introduced by this commit too! Note that `-p` is short for `--patch`.
git log --patch -- file.cpp
    Show patches for the commits in this log for this file only! (same as `git log -p -- file.cpp`)
-----
git log --follow <one_single_filename> = [VERY USEFUL!] Show the `git log` history which affected JUST THIS ONE SINGLE FILE YOU TOLD IT TO FOLLOW! This is VERY helpful to track and follow all of the commits which touched a certain file, in order to go back commit by commit until you find out **which commit** introduced the changes to that file that you care about!
    See: https://github.github.com/training-kit/downloads/github-git-cheat-sheet/ and `man git log` (then search for "--follow")
    [keywords: show file history]
git log --follow some/file/name | grep --color=always commit | head -n 10 = output just the FIRST 10 commits, hashes ONLY (ie: only the line containing the word "commit"), which have changed file some/file/name; ex:
    $ git log --follow "git & Linux cmds, help, tips & tricks - Gabriel.txt" | grep --color=always commit | head -n 10
    commit c6b9afa08d2b54ac80de3a5348f2d3455755a2b3
    commit c15c92170a00481c2a0f2fed9293e29b3209f3fd
    commit 47707a49d2789f218ae1b0a12e46e9c447a5b546
    commit bcd1674fb2576dd5ae8c0bc040496a087650f03a
    commit 4a01aa865add7bfe216ed408d2ea35c79704b59b
    commit f28e233e2e6727c60e6b2e6c6bba620515ecc41b
    commit ca451665a170a277aecc244bd76d98623b864590
            git show <commit_hash>
    commit 343f51041afcbc0984a123bc6e72d21c60cd95ce
    commit 3583e6d05b5505e9c40d00ade448bd1a3ba3e11d
- But, notice the extraneous "commit" keyword was picked up above, so remove it by forcing a search for the word "commit" followed by a 30+ char hex-only hash! Add `-E` for extended regex search, and `[0-9a-f]{30,}` to find 30 or more chars in a row which are 0-9 or a-f (lower-case hex chars)!
git log --follow "git & Linux cmds, help, tips & tricks - Gabriel.txt" | grep -E --color=always "commit [0-9a-f]{30,}" | head -n 10 = does the above! <====== EXCELLENT; WORKS GREAT! ======
  Ex:
    $ git log --follow "git & Linux cmds, help, tips & tricks - Gabriel.txt" | grep -E --color=always "commit [0-9a-f]{30,}" | head -n 10
    commit c6b9afa08d2b54ac80de3a5348f2d3455755a2b3
    commit c15c92170a00481c2a0f2fed9293e29b3209f3fd
    commit 47707a49d2789f218ae1b0a12e46e9c447a5b546
    commit bcd1674fb2576dd5ae8c0bc040496a087650f03a
    commit 4a01aa865add7bfe216ed408d2ea35c79704b59b
    commit f28e233e2e6727c60e6b2e6c6bba620515ecc41b
    commit ca451665a170a277aecc244bd76d98623b864590
    commit 343f51041afcbc0984a123bc6e72d21c60cd95ce
    commit 3583e6d05b5505e9c40d00ade448bd1a3ba3e11d
    commit 00138466c643736cecc6f26e5255a6180a950890
- Now, to see what changes a given commit has done to this file, do this!
    git difftool commit_hash~..commit_hash some/file/name
  Ex:
    git difftool c6b9afa08d2b54ac80de3a5348f2d3455755a2b3~..c6b9afa08d2b54ac80de3a5348f2d3455755a2b3 "git & Linux cmds, help, tips & tricks - Gabriel.txt"
- Better than all of the above, use this script: "eRCaGuy_dotfiles/useful_scripts/git-filechange-search.sh"
  Examples: <=============== BEST WAY TO SEARCH FOR WHICH COMMIT CAUSES A GIVEN CHANGE ============
    gs_git-filechange-search "git & Linux cmds, help, tips & tricks - Gabriel.txt" = display a list of all commit hashes which change this file
    gs_git-filechange-search -v "git & Linux cmds, help, tips & tricks - Gabriel.txt" = same as above, but 'v'erbose (ie: also print out the commit log headers for these commits)
    gs_git-filechange-search -vv "git & Linux cmds, help, tips & tricks - Gabriel.txt" = same as above, but extra 'v'erbose
    gs_git-filechange-search "git & Linux cmds, help, tips & tricks - Gabriel.txt" "difftool" = display only those commits which change this file AND contain changes which contain the word "difftool"
    gs_git-filechange-search -v "git & Linux cmds, help, tips & tricks - Gabriel.txt" "difftool" = same as above, but 'v'erbose (ie: also print out the commit log headers for these commits)
    gs_git-filechange-search -vv "git & Linux cmds, help, tips & tricks - Gabriel.txt" "difftool" = same as above, but extra 'v'erbose

git log --author="name or email regex search pattern" = show an abridged git log with ONLY commits by an author which matches this regex search pattern. Ex:
    git log --author="Gabriel Staples"
    git log --author="some_email@gmail.com"
git log --pretty=fuller
    <============ SHOW BOTH THE AUTHOR AND COMMITTER DATE! =============
    Show the AuthorDate (author date, "%ad") **and** the CommitDate (committer date, "%cd") for each commit!
    See:
    1. [My Q, & @TTT's answer] How to make `git log` show only the commit date, nothing else: https://stackoverflow.com/a/71385517/4561887
    1. Comment by @TTT: https://stackoverflow.com/questions/71384830/how-to-make-git-log-show-only-the-commit-date-nothing-else/71384831?noredirect=1#comment126178271_71385517
    1. Why git AuthorDate is different from CommitDate?: https://stackoverflow.com/q/11856983/4561887
    [git author date; git commit date]

[keywords: git log and git show equivalents; git log equivalent; git show equivalent; equivalent to git log; equivalent to git show]
git show <commit_hash>
    Show the commit message that was stored (for just this *one* commit), as well as a `git diff` of the changes this commit introduced, and to which files!
    See: https://github.github.com/training-kit/downloads/github-git-cheat-sheet/
    NB: THIS IS **EXACTLY** EQUIVALENT TO: `git log -p -1 <commit_hash>`. 
git log -p -1 <commit_hash>
    The **exact** same thing as above! (`git show <commit_hash>`): show the "diff" style log output of just this one commit at `commit_hash`.

git reset <commit_hash>
    Uncommit your changes on this branch going back to commit `commit_hash`, but NOT including that commit. In other words, all changes AFTER commit `commit_hash` will be UNCOMMITED, but retained as unstaged changes in your repo.
git reset --soft <commit_hash>
    Same as above, except leave the changes all **staged** for commit (added).
git reset --hard <commit_hash>
    WARNING WARNING WARNING! ALL CHANGES YOU ARE UNCOMMITTING WILL BE **LOST**! Same as above, except DELETE the changes instead of just uncommitting and unstaging them. DANGER DANGER DANGER! This cannot be easily undone (you'd need to go back to a backup branch or use `git reflog` to find the HEAD you were on before calling this command), so be careful when doing this.

-------------------------------------------------------------
TWO WAYS (Nay, 3) TO "REBASE" (`git merge`-style "rebase" vs `git rebase`-style rebase)
== THREE WAYS TO "REBASE" ONTO "LATEST `MAIN` BRANCH" ==
-------------------------------------------------------------
keywords: git merge rebase; git rebase; git merge-style rebase; git merge style rebase; 2 ways to rebase; two ways to rebase; 3 ways to rebase; three ways to rebase; rebase styles; git rebase techniques; ways to merge; how to rebase; how to merge; how to git rebase; how to git merge; how to do a git rebase; how to do a git merge; rebase onto latest master branch; rebase onto latest main branch; rebase onto latest develop branch

In this context, "rebase" colloquially means to "put your changes onto the latest changes", or otherwise stated, "bring in the latest upstream changes (which occurred since you forked off of the main branch some time ago) back into your feature branch." Therefore, BOTH the `git merge` and `git rebase` commands can be used to accomplish this "rebase". 

STEPS:

1. `git rebase`-style rebase
    ```
    # update main branch, withOUT having to check out main first
    git fetch origin main:main

    # back up your branch just in case you botch it!
    # See my answer here on branching: 
    # https://stackoverflow.com/a/63418267/4561887
    git branch feature_branch_BAK_20200814-1320hrs_about_to_rebase
    
    # rebase your currently-checked-out branch onto latest main
    git rebase -i main
    # OR
    git rebase -i my_first_commit~

    # manually resolve any conflicts, then `git add` the resolved files and
    # do `git rebase --continue` to finish up.
    # - Search this document for "RESOLVING MERGE CONFLICTS" (whole word, case-sensitive) for my own
    # detailed instructions on how to resolve conflicts. 
    #
    # If you find yourself resolving the same conflict again and again, once
    # per commit you have, you might want to `git rebase --abort` and then 
    # squash your commits into 1 commit and start again, OR do the merge-style
    # rebase instead!

    # force-push to upstream (using `-f` is required just **the first time** pushing
    # after rebasing)
    git push -f
    ```
2. `git merge`-style "rebase" [GENERALLY THE EASIEST STYLE TO USE; IF IN DOUBT, JUST DO THIS ONE]
    ```
    # update main branch, withOUT having to check out main first
    git fetch origin main:main

    # back up your branch just in case you botch it!
    # See my answer here on branching: 
    # https://stackoverflow.com/a/63418267/4561887
    git branch feature_branch_BAK_20200814-1320hrs_about_to_rebase

    # merge in the latest upstream changes from main to your feature branch
    # you currently have checked-out
    git merge main

    # Manually resolve conflicts if necessary, then `git add` the resolved files
    # and do `git merge --continue` to finish up.
    # - Search this document for "RESOLVING MERGE CONFLICTS" (whole word, case-sensitive) for my own
    # detailed instructions on how to resolve conflicts. 
    #
    # Once you have merged, however, `git log` will show your commits all 
    # intermingled with a bunch of upstream commits from other people which
    # you just merged in! This is confusing. To force `git log` to NOT show
    # those other commits, simply do this:
    #
    # Show only commits which are NOT in `main` (hence `^main`) but which ARE in your 
    # currently-checked-out feature branch (`HEAD`)
    git log ^main HEAD

    # push to upstream (force-push is NOT required, which is good!)
    git push
    ```
There is actually a 3rd "rebase" style which uses "cherry-picking". It looks like this:
3. `git cherry-pick`-style "rebase"
    ```
    # update main branch, withOUT having to check out main first
    git fetch origin main:main

    # back up your branch just in case you botch it!
    # See my answer here on branching: 
    # https://stackoverflow.com/a/63418267/4561887
    git branch feature_branch_BAK_20200814-1320hrs_about_to_rebase

    # check out a new branch from main
    # See my answer here on branching: 
    # https://stackoverflow.com/a/63418267/4561887
    git checkout -b new_feature_branch main

    # cherry-pick your commits onto it
    # See my answer here on cherry-picking: 
    # https://stackoverflow.com/a/69472178/4561887
    git cherry-pick my_first_commit~..my_last_commit

    # Manually resolve conflicts if necessary, then `git add` the resolved files
    # and do `git rebase --continue` to finish up.
    # - Search this document for "RESOLVING MERGE CONFLICTS" (whole word, case-sensitive) for my own
    # detailed instructions on how to resolve conflicts. 
    #
    # Done! Now you have a new feature branch with your changes on top of the 
    # latest changes. The end result is the same as the `git rebase`-style 
    # rebase above.

    # push to upstream (since it's your first time pushing to upstream, after running the below
    # command it should tell you to add `-u` or something to "set your upstream"; just do whatever
    # it says)
    git push
    ```

PROS AND CONS LIST OF EACH STYLE OF "REBASE":
1. `git rebase`-style rebase [HARDER, BUT CLEANER RESULT]
    1. PROS:
        1. keeps a clean, linear `git log` history
        1. If there are no conflicts, it's **super easy!**
    1. CONS:
        1. If you have a ton of commits and there are conflicts, you may end up resolving the same conflict once per commit, which is **horrible**! In that case you should either A) squash all your commits into a single commit and then do it again, OR B) do a `git merge` style "rebase" instead.
        1. Squashing all your commits into 1 single commit first is recommended.
        1. Since this is rewriting your history, you must force push (`git push -f`) the first `git push` when done
2. `git merge`-style "rebase" [IF IN DOUBT, JUST CHOOSE THIS ONE!]
    1. PROS:
        1. easiest
        1. if there are conflicts, you always resolve them **once**, no matter how many commits you have! (unlike rebase and cherry-pick styles)
    1. CONS:
        1. Creates a non-linear `git log` history. Once you do a `git merge` into your feature branch, from that point on you need to do `git log ^main HEAD` to see ONLY commits which *are* in your HEAD (feature branch) but which are NOT in main (hence the `^main`).
3. `git cherry-pick`-style "rebase" [SOMETIMES USEFUL IF YOU JUST WANT TO "START OVER" on your feature branch]
    1. PROS:
        1. Easy to "start over" your feature branch in case you botch a `git rebase`.
        1. keeps a clean, linear `git log` history (like `git rebase`)
    1. CONS:
        1. Similar to `git rebase`, you may end up having to resolve the same conflict once per commit unless you squash first.
        1. The process requires creating a **new branch** and cherry-picking your changes onto it, rather than just **working on the branch you already had**. 
        1. When done, you have to push to remote and set your "upstream" branch again for this new branch you created. Setting upstream can be a little confusing and is annoying to have to do each time you "rebase" when you use this style.


-------------------------------------------------------------
== TWO WAYS TO SQUASH == 
-------------------------------------------------------------
keywords: "git squash"; squash in git; git squash

1) `git rebase`-style squash
The `git rebase -i <commit_hash>` way (this keeps and combines all commit messages)
<========== BEST WAY TO SQUASH IN GIT if squashing a **linear** git history and you want to preserve commit messages! ===========
    ```
    git checkout feature_branch
    git rebase -i master
        ...then manually change all "pick" commit entries in the editor to "squash", or just "s" for short.
        Done!
    ```
    OR:
    ```
    git checkout feature_branch
    git rebase -i my_first_commit~
    # manually "pick" first entry and set all others afterwards to "squash", or just "s" for short.
    ```
2) `git reset --soft`-style squash [GENERALLY THE EASIEST STYLE TO USE; IF IN DOUBT, JUST DO THIS ONE]
The `git reset --soft <commit_hash>` way (you lose the commit messages this way though) []
<========== BEST WAY TO SQUASH IN GIT if squashing across merges or branches! ===========
    ```
    # 1. generally the safer approach (does NOT also bring in upstream changes during the squash); 
    #    see details below
    git branch my_branch_BAK  # create backup branch just in case
    git reset --soft my_first_commit~
    git commit
    ```
    OR:
    ```
    # 2. also brings in upstream changes from `master` at the same time; see details below
    git checkout feature_branch
    git reset --soft master
        uncommit all changes which are in the `feature_branch` but NOT in the `master` branch; `--soft` leaves all these changes "staged", however.
    git commit -m "Commit all \"squashed\" feature_branch branch changes not in master"
        Commit these "squashed" changes now.
        Done!
    ```
-------------------------------------
CONCISE SQUASH SUMMARY (2 MAIN WAYS):   <=========== SUPER HELPFUL! ===========
-------------------------------------
[keywords: git squashing, squashing in git; squash rebase; rebase squash; reset squash; squash reset; reset style squash; rebase-style squash]
1) `git rebase -i` way (keeps and combines all commit messages)
        ```
        # Step 1 of 2
        
        git checkout feature_branch
        git branch my_branch_BAK  # create backup branch just in case
        
        # Step 2 of 2 (two options)

        # A. [SAFER/GENERALLY RECOMMENDED--only squashes your changes **you** made]
        git rebase -i my_first_commit~ 

        # B. OR [WILL ALSO BRING IN UPSTREAM CHANGES FROM MASTER if you've recently pulled latest
        # master and it has upstream changes]:
        git rebase -i master
        
        # For both Options A and B just above:
        # 1. Now, in editor, manually "pick" first entry and set all others afterwards to "squash", or just "s" for short.
        # 2. When you close the editor, the squashing rebase will begin. When it's done, the editor will open again,
        #    with all commit messages from all squashed commits in it, and you can manually edit the messages into a 
        #    single, unified commit message.

        # IMPORTANT NOTE ABOUT OPTION B: if you have recently pulled the latest `master` and it 
        # has upstream changes not yet on your `feature_branch`, then Option B like this:
        #       git rebase -i master
        # ...ALSO pulls in those changes and is kind of like doing Option A **plus** bringing in 
        # those latest changes from `master` by rebasing onto latest `master`, like this!:
        #       git rebase -i my_first_commit~  # rebase-style squash
        #       git fetch origin master:master  # pull latest changes from remote `master` into local `master`
        #       git rebase master               # Bring those upstream changes from `master` into your `feature_branch`
        #                                       # by rebasing your `feature_branch` on top of them.
        ```
2) `git reset --soft` way (you lose the commit messages this way though, but it squashes over merge commits really easily)
        ```
        # Step 1 of 2

        git checkout feature_branch
        git branch my_branch_BAK  # create backup branch just in case

        # Step 2 of 2 (two options)

        # A. [SAFER/GENERALLY RECOMMENDED--only squashes your changes **you** made]
        git reset --soft my_first_commit~
        git commit  # Manually add a new and complete commit message in the editor that opens.

        # B. OR [WILL ALSO BRING IN UPSTREAM CHANGES FROM MASTER if you've recently pulled latest
        # master and it has upstream changes]:
        git reset --soft master
        git commit  # Manually add a new and complete commit message in the editor that opens.
        
        # IMPORTANT NOTE ABOUT OPTION B: if you have recently pulled the latest `master` and it 
        # has upstream changes not yet on your `feature_branch`, then Option B like this:
        #       git reset --soft master
        #       git commit
        # ...ALSO pulls in those changes and is kind of like doing Option A **plus** merging in 
        # those latest changes from `master`, like this!:
        #       git reset --soft my_first_commit~  # reset-style squash
        #       git commit
        #       git fetch origin master:master  # pull latest changes from remote `master` into local `master`
        #       git merge master
        # ...except that instead of **merging** in those latest upstream changes into your 
        # `feature_branch` as a **new commit**, you're **squashing them in** as part of **the same
        # commit**.
        ```
MORE-DETAILED REBASE AND SQUASH NOTES:
[TWO DISTINCT "SQUASH" AND "REBASE" STYLES!]:
There is no "squash" command in git. There *is* a "rebase" command in git, but "merging" or "cherry-picking" can also be used as a form of "rebasing". The concept of "squashing" and "rebasing" can mean multiple things. Here are two common work-flow styles and what "squashing" and "rebasing" means in each:
1. In a merge-based-workflow-style where you are continually **merging the latest "master" branch** into your feature branch to keep your feature up-to-date with upstream changes in "master", you can "squash and rebase" like this (assuming "master" is already fully up-to-date with the latest upstream changes). First, we use `git reset --soft` to "squash" all feature branch commits into one, then we cherry-pick this onto the latest master!:

        git checkout feature_branch
        # "squash" all feature_branch changes into one single commit!
        git reset --soft master && git commit
        # create a new feature branch from latest master
        git checkout -b feature_branch2 master
        # cherry-pick your squashed commit onto this new branch
        git cherry-pick feature_branch
        # Resolve conflicts as required, then use `git add <file>` or `git add -A`, and
        # `git cherry-pick --continue` to finish it up.

2. But, in a rebase-based-workflow-style where you are continually **rebasing onto the latest "master" branch** to incorporate its upstream changes into your feature branch, you can "squash and rebase" like this (assuming "master" is already fully up-to-date with the latest upstream changes). First, we use `git rebase -i <commit_just_before_our_first_feature_branch_commit>` to "squash" all of our feature branch commits into one, then we do `git rebase master` to rebase this one, squashed commit onto the latest master. Rebasing only one commit vs many commits avoids merge conflict hell where you find yourself fixing the same conflicts again and again and again in a single rebase (once per commit, for instance) instead of just once (once per squashed commit which contains *all* commits). So, these are the steps for this workflow style:

        git checkout feature_branch
        # "squash" all feature_branch changes into one single commit!
        git rebase -i $(git merge-base master HEAD)
        # Now in the editor that comes up, change all but the first "pick" entry to "s" for
        # "squash", then save and close the editor, and the "squash" will happen!
        # Now rebase your single, squashed commit onto latest master:
        git rebase master
        # Resolve conflicts as required, then use `git add <file>` or `git add -A`, and
        # `git rebase --continue` to finish it up.

git cherry-pick <commit_hash>
    cherry-pick (apply) commit_hash onto your currently-checked-out branch; if there are any conflicts, resolve them manually, use `git add` on the files you manually fixed, and then run `git cherry-pick --continue` to finish the cherry-pick and apply the commit with the original commit message (giving you a chance to edit it first, however, before it is applied)!
git cherry-pick <commit_start>..<commit_end>
    cherry-pick (apply) the range of commits from commit_start (NOT including this commit) to commit_end (including this commit); very useful in place of a rebase onto latest master once you have landed/merged some upstream commits into master and don't want to have to unnecessarily deconflict them via the `git rebase` process now instead; see: https://stackoverflow.com/questions/1994463/how-to-cherry-pick-a-range-of-commits-and-merge-into-another-branch/1994491#1994491
git cherry-pick commit_start~..commit_end
    same as above, except **inclusive**! ie: cherry-pick (apply) the range of commits from commit_start (including this commit) to commit_end (also including this commit); see: https://stackoverflow.com/questions/1994463/how-to-cherry-pick-a-range-of-commits-and-merge-into-another-branch/1994491#1994491
git cherry-pick commit_start^..commit_end
    alternative form of the above line--does the exact same thing
git cherry-pick commit1 commit2 commit3
    cherry-pick these commits (up to any number--add as many commit hashes as you want!) onto the current branch; NOT the same as using commit1..commit2, which selects a **range** of commits from 1 commit after commit1, through commit2!

git for-each-ref --sort=-committerdate --format='%(committerdate:iso8601) %(refname:short)' refs/remotes/origin/release/* | head -n 1
    See which remote branch named `release/*` was most recently updated. 
    This is useful to see which release branch is the active one being worked on so you can know which branch to fork off of and merge your next feature into.
    - I learned this by asking GitHub Copilot AI: 
        > git find the branch that is named `origin/release/*` and that has the most recent commits
git for-each-ref --sort=-committerdate --format='%(committerdate:iso8601) %(refname:short)' refs/remotes/origin/release/*
    <======
    Same as above, but show the entire sorted list in order of most-recently-updated on top to least-recently-updated on bottom.
    - I learned this by asking GitHub Copilot AI: 
        > git find the branch that is named `origin/release/*` and that has the most recent commits
    [find recently updated branch commit]

== `git tag`: ==

See:
1. https://stackoverflow.com/questions/8044583/how-can-i-move-a-tag-on-a-git-branch-to-a-different-commit/28280404#28280404 - How to delete local and remote tags and remake them...TODO [FINISH TAG COMMANDS HERE WHEN ABLE!]
1. [my answer] https://stackoverflow.com/questions/6269927/how-can-i-list-all-tags-in-my-git-repository-by-the-date-they-were-created/69241512#69241512

git tag
    List all tags
git tag -l
    List all tags (same as above)

== `git ls-files` and `git ls-tree`: ==

HOW TO LIST (ls) FILES IN A GIT REPO: `git ls-files` and `git ls-tree`

References:
    - `man git ls-files`: https://git-scm.com/docs/git-ls-files
    - `man git ls-tree`: https://git-scm.com/docs/git-ls-tree

1. GIT LS-FILES:

git ls-files = list (`ls`-like) all files in the git repo in the directory you are currently in
cd $(git rev-parse --show-toplevel) = cd into the absolute path of the top-level (root) of this git repo; see: https://stackoverflow.com/questions/957928/is-there-a-way-to-get-the-git-root-directory-in-one-command/957978#957978
cd $(git rev-parse --show-toplevel) && git ls-files = list all files in this git repo
git ls-files | wc -l = count all files in this repo, at this dir level or lower

find | wc -l = count all files in this directory or lower, including those NOT part of the checked-in files to this repo, and including all .git hidden metadata files to describe the branches and content of this repo; so...kind of similar to the above, except counting MORE than what is actually checked-in to this repo!

2. GIT LS-TREE:

git ls-tree -r HEAD = list (`ls`-like) all files in the git repo in branch/commit HEAD in the directory you are currently in
    See: https://stackoverflow.com/questions/277546/can-i-use-git-to-search-for-matching-filenames-in-a-repository/277557#277557
git ls-tree --full-tree -r HEAD = same as above, except list ALL files in the repo, as if you were in the repo's root dir when making this call
cd $(git rev-parse --show-toplevel) && git ls-tree -r HEAD = same effect as the above, simply by `cd`ing into the repo's root dir first.
git ls-tree -r HEAD | wc -l = same as `git ls-files | wc -l`: count all files in this repo, at this dir level or lower
git ls-tree --full-tree -r HEAD | wc -l = count all files in this repo, period
cd $(git rev-parse --show-toplevel) && git ls-tree -r HEAD | wc -l = same as above, but in a different way; count all files in this repo, period

git ls-tree -r HEAD | grep "my_filename" = search for file "my_filename" in branch/commit HEAD at this dir level or lower <========= VERY USEFUL! =========
git ls-tree --full-tree -r HEAD | grep "my_filename" = search for file "my_filename" in branch/commit HEAD in ALL dirs! <========= VERY USEFUL! (MORE THOROUGH) =========
git ls-files | grep "my_filename" = same as above, except no need to explicitly set the branch/commit you'd like to search in! (It just searches the currently-checked-out branch/commit you're in). <========= VERY USEFUL! (MY FAVORITE) =========
    See: https://stackoverflow.com/questions/277546/can-i-use-git-to-search-for-matching-filenames-in-a-repository/24289481#24289481

3. To find a long-lost file that could be in ANY of your repo's branches or commits!
    See: https://stackoverflow.com/questions/277546/can-i-use-git-to-search-for-matching-filenames-in-a-repository/34100574#34100574
    and the gist it references: https://gist.github.com/dirkjot/073ffac502567e32f7ad
    - It relies on `git rev-list --all` as well as `git ls-tree --full-tree -r COMMIT | grep "search_term"`, and is quite ingenious and useful!

4. Related:
git rev-list --all = list all commits in reverse-chronological order which are traceable from your currently-checked-out commit...I think?
git rev-list HEAD --max-count=10 = list only the last 10 commits in reverse-chronological order which are traceable starting from "parent commit" HEAD; note that this is identical to doing `git log` (or `git lg`) and then looking back at ONLY the commit hashes for ONLY the last "--max-count" commits!

== ==

git merge-base branch1 branch2
    find the common ancestor between branch1 and branch2; see: https://stackoverflow.com/questions/1549146/git-find-the-most-recent-common-ancestor-of-two-branches/1549155#1549155
git checkout branch1 && git merge -X theirs branch2
    <====== PRO TIP =======
    merge branch2 into branch1, ACCEPTING ALL OF branch2's CHANGES IN THE EVENT OF ANY MERGE CONFLICTS! The `-X theirs` flag says to always accept the changes from the branch we are *not* on, in the event of conflicts! This can be very useful to run if you first run `git merge branch2` alone and see you have like 10 to 20+ files with conflicts, for ALL (100%) OF WHICH YOU NEED TO KEEP THE CHANGES FROM branch2 and NOT from branch1! You can then cancel the merge with `git merge --abort` and go back and run `git merge -X theirs branch2` to just accept all of their changes.
    See:   1) https://stackoverflow.com/questions/50991701/merging-two-branches-how-do-i-accept-one-branch-for-all-conflicts/50994582#50994582.
    *****  2) My work-around described in my question here!: https://stackoverflow.com/questions/63623581/how-do-i-accept-git-merge-conflicts-from-their-branch-for-only-a-certain-direc
    *****+ 3) My answer here: https://stackoverflow.com/questions/21025314/who-is-us-and-who-is-them-according-to-git/63911630#63911630
git merge -X theirs <branch_or_commit>
    merge <branch_or_commit> into the currently-checked-out branch. In the event of conflict, accept ALL changes from the <branch_or_commit>, NOT from your currently-checked-out branch (HEAD). See just above for details and links.
git checkout --ours -- path/to/somefile1.c path/to/somefile2.c path/to/somefile3.c
    <====== PRO TIP =======
    When in the middle of a `merge` or other type of conflict, check out these files from the `ours` side. 
    - See my answer here for what that means in each conflict-resolution context: `git merge`, `git cherry-pick`, `git rebase`, `git revert`, etc.: 
    https://stackoverflow.com/questions/21025314/who-is-us-and-who-is-them-according-to-git/63911630#63911630
    - See also this answer to check out `branch_name` instead of just `--ours` or `--theirs`: 
      https://stackoverflow.com/a/63624168/4561887
git checkout --theirs -- path/to/somefile1.c path/to/somefile2.c path/to/somefile3.c
    <====== PRO TIP =======
    When in the middle of a `merge` or other type of conflict, check out these files from the `theirs` side. 
    - See my answer here for what that means in each conflict-resolution context: `git merge`, `git cherry-pick`, `git rebase`, `git revert`, etc.: 
    https://stackoverflow.com/questions/21025314/who-is-us-and-who-is-them-according-to-git/63911630#63911630
    - See also this answer to check out `branch_name` instead of just `--ours` or `--theirs`: 
      https://stackoverflow.com/a/63624168/4561887
git checkout [--ours|--theirs] -- path/to/some/dir
    <====== PRO TIP =======
    [WORKS!] You can check out all files from an ENTIRE DIRECTORY too instead of just specifying files individually!
    See this answer to my Q here: 
    https://stackoverflow.com/questions/63623581/how-do-i-accept-git-merge-conflicts-from-their-branch-for-only-a-certain-direc/63624168#63624168

HOW TO CHECK OUT A FILE FROM A COMMIT_HASH INTO A NEW FILE LOCATION:
git show HEAD~:somefile.cpp > temp/somefile_old.cpp
    <====== PRO TIP ======= VERY USEFUL! =======
    Similar, apparently, to `git cat-file`: check out file "somefile.cpp" from commit/branch `HEAD~` into new path location "temp/somefile_old.cpp". 
    See this answer here: https://stackoverflow.com/a/888623/4561887

Assuming you just did this to rebase your feature branch onto latest master:
    git checkout master
    git pull origin master
    git checkout my_branch
    git rebase master  # or `git rebase -i master` to do it interactively
THEN HERE'S HOW TO COMPARE A JUST-REBASED BRANCH (`my_branch`) TO ITS OLD BACKUP (`my_brank_BAK`) FROM BEFORE REBASING (or rebasing + cherry-picking):
[keywords: post-rebase compare, after-rebase compare, after rebase compare, compare files after rebase]
(Assuming you're still on the newly-rebased branch `my_branch`):
    git difftool my_branch_BAK $(git diff --name-only $(git merge-base my_branch_BAK master) my_branch_BAK) = description: the inner-most $() finds the merge-base between the backup branch and the old master, and the outer $() finds the *list of filenames* which changed from that merge-base to the backup branch. This way, we end up `difftool`ing between the backup branch and the rebased branch, ONLY LOOKING AT THE FILES WE KNOW WE HAD PREVIOUSLY CHANGED!
  Better (easier to read):
    BRANCH_BAK=my_branch_bak && git difftool $BRANCH_BAK $(git diff --name-only $(git merge-base $BRANCH_BAK master) $BRANCH_BAK) <======= QUICKLY CHECK NEWLY-REBASED BRANCH AGAINST ITS BACKUP BRANCH! ======= [be sure to change `master` near the end to whatever upstream you have if necessary too!] <=======
   UPDATE: USE THIS SCRIPT INSTEAD NOW!: "eRCaGuy_dotfiles/useful_scripts/git-changes.sh".
    git changes <common_base> <backup_branch> [any other args to pass to git difftool]
   Ex:
    git changes master my_branch_bak <===== BEST! ======
  OR, if you're not on the newly-rebased `my_branch` anymore:
    git difftool my_branch_BAK..my_branch $(git diff --name-only $(git merge-base my_branch_BAK master) my_branch_BAK)

man git commit
git commit --date "Wed Jan 01 23:00:00 2020 -0700"
    Set the **author** date (`%ad') when committing.
    - See `git log` for what various date formats look like; keywords: git date
GIT_COMMITTER_DATE="Wed Jan 01 23:00:00 2020 -0700" git commit --date "Wed Jan 01 23:00:00 2020 -0700"
    <===== BETTER ======
    Set both the **author** date (`%ad`) **and** the **committer** date (`%cd`) when committing! 
    - See the extra info. at the bottom of my Q here: 
      How to make `git log` show only the commit date, nothing else: https://stackoverflow.com/q/71384830/4561887
    - To see both dates, run `git log --pretty=fuller`. 
DATE="Wed Jan 01 23:00:00 2020 -0700"; GIT_COMMITTER_DATE="$DATE" git commit --date "$DATE"
    <======== BEST!: CORRECT both your **author** AND **committer** dates! =========
    Same as above (set both the **author** date (`%ad`) **and** the **committer** date (`%cd`) when committing!), except you only have to specify the date once. 
    - The `--date` option sets the **author** date stamp, and the variable `GIT_COMMITTER_DATE` sets the **committer** date stamp.
    - NB: you must NOT have a semicolon after the `GIT_COMMITTER_DATE="$DATE"` part and before the `git commit --date "$DATE"` part or else it will NOT work to set the **committer** date!
    - To see both types of dates in your `git log` output, run:
            git log --pretty=fuller
    - To get the date _now_ in the same format as git would use, run: 
            date +"%a %b %-d %H:%M:%S %Y %z"
    - See:
        1. My `gs_git_commit_r` alias in "eRCaGuy_dotfiles/home/.git_aliases".
        1. My Q here: How to make `git log` show only the commit date, nothing else: https://stackoverflow.com/q/71384830/4561887
        1. How can one change the timestamp of an old commit in Git?: https://stackoverflow.com/a/9701130/4561887
DATE="Wed Jan 01 23:00:00 2020 -0700"
GIT_COMMITTER_DATE="$DATE" git commit --date "$DATE"
    <========== BEST!: CORRECT both your **author** AND **committer** dates! ===========
    Same as above, but split the two commands onto two separate lines.
GIT_COMMITTER_DATE="Wed Jan 01 23:00:00 2020 -0700" git commit --amend
    <========
    Keep the same **committer** date as before when amending too!
DATE="Wed Jan 01 23:00:00 2020 -0700"; GIT_COMMITTER_DATE="$DATE" git commit --amend
    <================
    Same as above, but easier.


git push origin my_local_branchname:my_remote_branchname = push my_local_branchname to origin/my_remote_branchname; normally `git push`ing only allows pushing to a remote branch of the *same* branch name, so this is the work-around! See: https://stackoverflow.com/questions/13897717/push-commits-to-another-branch/13897766#13897766.

== GitHub: ==

----- Quick (PR review with meld) demo START -----
- I'd like to review a PR with meld **locally** withOUT checking out any other branches, so I can stay on the "dirty" branch I'm working on. Here are the 3 commands I just ran:

time git fetch origin master:master
    Fetch the latest content from the remote "origin" `master` branch into the locally-stored remote-tracking `origin/master` branch, and also into local `master` branch. 
time git fetch origin feature_branch_from_github
    Fetch the remote `feature_branch_from_github` into the locally-stored remote-tracking `origin/feature_branch_from_github` branch.
git difftool master...origin/feature_branch_from_github
    Difftool (compare with meld) the changes on `origin/feature_branch_from_github` since it diverged from my (now-updated) local `master` branch. 
    Yes, those 3 dots (`...`) in this command are important. 2 dots (`..`) means something else entirely. 3 dots looks at the changes since the common merge-base (which is how GitHub shows changes as well, in the PR); 2 dots looks at the direct changes side-by-side (which will show TONS of files, potentially, this PR doesn't touch, simply because changes exist on one side [branch] compared to the other, even though this PR didn't introduce them). 
----- Quick (PR review with meld) demo END -----

To *locally* view, review, and compare changes from a GitHub PR, in the (fantastic) "meld" file comparison tool:
[keywords: github review PR, github local review in meld, local github review in meld, github review locally, locally review github PR, local github PR review in meld, github PR review, PR review in github, github meld pr, github pr review in meld, meld github pr review]
Note: despite being able to locally view the changes, you'll still have to use the GitHub interface for all comments and things in the review process.

A) *Locally* look at changes in meld from a GitHub PR:  <========= VERY USEFUL FOR REVIEWING GITHUB PRs! ===========
1. Set up `meld` as your `git difftool`: https://stackoverflow.com/questions/14821358/git-mergetool-with-meld-on-windows/48979939#48979939
2. See the changes in meld as your `git difftool`:
    # 1)
    git fetch --all
    # OR, if on a HUGE repo with thousands of branches, `git fetch --all` can take a long time (1 to 2+ minutes), so instead just fetch the 2 branches you need to check out: 1) the remote branch of interest from the GitHub PR, and 2) the latest remote master
    git fetch origin branch_from_github_PR master
    # 2) Then check out this remote GitHub branch locally (ie: check out your locally-stored remote-tracking branch [of this branch] which just got updated by the `fit fetch` above!)
    git checkout branch_from_github_PR
    # 3) This allows you to see all changes introduced by this feature branch, as compared to the
    # original origin/master the author last rebased against or merged into their feature branch!
    git difftool $(git merge-base origin/master HEAD)   <========= VERY USEFUL FOR REVIEWING GITHUB PRs *in meld*! ===========
    # OR: more explicitly stated, and required to be this way in case the GitHub PR is trying to merge into a different base:
    MERGE_INTO=origin/master && git difftool $(git merge-base $MERGE_INTO HEAD)   <========= VERY USEFUL FOR REVIEWING GITHUB PRs *in meld*! ===========

    # OR <========= EASIEST! ===========
    # [WORKS!]
    git difftool origin/master...HEAD   # <============== NOTICE THE 3-DOT SYNTAX! ==============
        SEE HERE: https://stackoverflow.com/questions/7251477/what-are-the-differences-between-double-dot-and-triple-dot-in-git-dif/7252067#7252067
    git difftool origin/master...       # <======== BEST & SHORTEST! =======
        Also works! This is the same as above!
    git difftool $(git merge-base origin/master HEAD) HEAD
        (The longer and more-explicit version). EXACT SAME THING AS ABOVE! So, use the git 3-dot (...) syntax above instead!

- Optionally, see the *names of files changed* with this:
    git difftool --name-only $(git merge-base origin/master HEAD)
- And the *number of files changed* with this:
    git difftool --name-only $(git merge-base origin/master HEAD) | wc -l
- And the *commit hashes* for all commits that created the feature branch (where I learned about `git cherry`: https://stackoverflow.com/questions/7566416/how-to-see-which-commits-in-one-branch-arent-in-the-other/7566523#7566523; also sort of related (my own ans): https://stackoverflow.com/questions/7566416/how-to-see-which-commits-in-one-branch-arent-in-the-other/60731900#60731900):
    git cherry $(git merge-base origin/master HEAD) HEAD
- And the *commit hashes PLUS commit message subject lines* for all commits that created the feature branch, add `-v`:
    git cherry -v $(git merge-base origin/master HEAD) HEAD
- Why do the `git merge-base` part of the above? Because if you don't, then the `origin/master` that they recently merged into their PR to fix merge conflicts may NOT be the same `origin/master` you just pulled (yours is *newer*). If your `origin/master` you just pulled contains a bunch of newly-landed PRs from other people working simultaneously, for instance, then doing `git difftool master` alone, or `git difftool origin/master`, will be IN THE FUTURE, and you'll be `git diff`ing against FUTURE CHANGES that the PR in question doesn't even know about! Therefore, instead of seeing the true 5 or 10 files changed or whatever, you could see hundreds or even thousands of files changed from these future commits which occurred AFTER the PR requester last merged origin/master into their feature branch.
-- To verify this and get more insight into it, you can manually `git merge origin/master` into their feature branch on your local machine, and then `git difftool origin/master` will work correctly, and so long as you did a `git merge-base origin/master branch_from_github_PR` BEFORE merging the latest origin/master into their feature branch (and copied and saved the output hash for your future reference), `git lg` will allow you to track back to that merge-base (manually search for it in `git lg` with the forward slash tool (/)), and you'll be able to see what's going on in all of the forks and splits and how far into the FUTURE `git difftool origin/master` was looking!
-- So, to just avoid all this hassle in the first place, just use the `git difftool $(git merge-base origin/master HEAD)` command every time instead!

B) You may also do the comparison withOUT checking out the branch from the PR as follows:
Note: this has the benefit of allowing you to do the comparison withOUT checking out the branch first! This means you can keep open whatever work you currently had open. The downside, of course, is that you can't `git grep`, `grep`, or otherwise search the code base in the modified state, nor use your IDE or editor to explore the changes. Therefore, I highly recommend just doing option A above instead!
    git fetch origin/branch_from_github_PR  # update your locally-stored remote-tracking branch to origin/branch_from_github_PR
    git difftool $(git merge-base origin/master origin/branch_from_github_PR)


== To move a chunk of commits to a new branch after a merge as though they were squashed & then cherry-picked instead: ==
See the section titled "How to use a patch file as a much easier replacement for squashing", here: https://stackoverflow.com/questions/7566416/how-to-see-which-commits-in-one-branch-arent-in-the-other/60731900#60731900

=== In short: how to use patch files: ===
[keywords: git patch files, git patch-files, using git patch files, patching commits, moving commits from branch to branch en-masse]
(Copy/pasted from my answer here: https://stackoverflow.com/questions/7566416/how-to-see-which-commits-in-one-branch-arent-in-the-other/60731900#60731900, and then edited)

    ## How to use a patch file as a much easier replacement for squashing:

    **A work-around is to simply [obtain a patch file](https://stackoverflow.com/questions/28192623/create-patch-or-diff-file-from-git-repository-and-apply-it-to-another-different/28193089#28193089) containing a "squash-equivalent" of all 30 of my commits, patch it onto a new fork of `master` (a new sub-feature-branch), and work from there, as follows:**

        git checkout feature_branch
        # ensure I have the latest changes from master merged into feature_branch
        git merge master
        # Obtain a patch file, which is the equivalent of a squash of my 30 commits into 1 commit:
        git diff master..feature_branch > mypatch.patch
        git checkout master
        # Create a new, sub-feature branch
        git checkout -b feature_branch2
        # Patch the 30 commit patch file onto it:
        git apply mypatch.patch

    If your patch won't apply, do some Googling. Ex: ["git patch failed"](https://www.google.com/search?q=git+patch+failed&oq=git+patch+failed&aqs=chrome..69i57.5337j0j7&sourceid=chrome&ie=UTF-8). You might try some of these suggestions to force the patch to apply: https://stackoverflow.com/questions/4770177/git-patch-does-not-apply.

    Now I have my 30-commit patch all applied locally, but unstaged and uncommitted.

    ## Now use `git gui` to add files, chunks, and/or lines and break up your big PR or "diff", as you see fit.

    Alternatively, just commit the whole patch/chunk as one commit and be done if your goal is simply to apply all of these changes to this new branch!

== To compare file changes after a major rebase or rebase + cherry-pick: ==
0. Back up your branch and do the rebase onto latest master (this is overly-simplified, but makes the general point):
    git branch mybranch_bak     # make a backup copy of mybranch called mybranch_bak *before* doing the rebase, just in case you mess up the rebase!
    git rebase -i master        # rebase mybranch onto latest master
1. Figure out which files mybranch_bak changed:
    MERGE_BASE=$(git merge-base master mybranch_bak) && git diff --name-only $MERGE_BASE..mybranch_bak > file_list.txt
2. Now look at any changes, ***in just these files**, between your rebased branch and your backed-up branch, to see how your rebase you just did affected these files you previously had worked in and changed:
    git checkout mybranch       # Ensure you are in your branch you just rebased
    git difftool branch_bak $(cat file_list.txt)    # Look at the files of interest to see how the rebase affected them; ensure no errors exist or were introduced in the rebase!
[THIS SINGLE-LINE CMD IS BROKEN! JUST USE THE 2-STEP CMD SEQUENCE ABOVE FOR NOW INTEAD.] OR, do it all in one single command!
    CHANGED_FILES="$(MERGE_BASE=$(git merge-base master mybranch_bak) && git diff --name-only $MERGE_BASE..mybranch_bak)" && git difftool branch_bak "$CHANGED_FILES"

== patch files / patches ==

Source: https://stackoverflow.com/questions/28192623/create-patch-or-diff-file-from-git-repository-and-apply-it-to-another-different/28193089#28193089
git diff tag1..tag2 > mypatch.patch = produce a patch file with the differences from tag1 to tag2
git apply mypatch.patch = apply all the changes detailed in mypatch.patch
git add -A && git commit = add and commit the changes just applied via the patch command above
SEE ALSO MY ANSWER HERE ABOUT OBTAINING A PATCH FILE WHICH IS THE EQUIVALENT OF A BIG SQUASH AFTER A MERGE!
  https://stackoverflow.com/questions/7566416/how-to-see-which-commits-in-one-branch-arent-in-the-other/60731900#60731900
BREAKING UP A BIG DIFF! ^^ See the link to my answer just above!

git branch --edit-description = edit a description of your branch stored in your project's local ".git/config" file; see: https://stackoverflow.com/questions/2108405/branch-descriptions-in-git/8858853#8858853
See also: https://github.com/bahmutov/git-branches
    git branch --edit-description
    git config branch.master.description "description text"  <=======
    git config branch.master.description
And: https://glebbahmutov.com/blog/git-branches-with-descriptions/#disqus_thread

git clean -fd
    WARNING WARNING WARNING THIS IS *DESTRUCTIVE*!!! REMOVE ALL UNTRACKED FILES AND DIRECTORIES; see: https://stackoverflow.com/questions/61212/how-to-remove-local-untracked-files-from-the-current-git-working-tree/64966#64966

git clean -Xdn
    <========== CLEAN FILES ignored by .gitignore files (dry run) ==========
    See which files and folders exist in a repo but are ignored by .gitignore files. 
    - ie: do a **dry run** of removing all files and directories in .gitignore files in the repo. Using `-X` causes this to NOT remove untracked files, but rather, only **explicitly ignored** files.
    - See here for *some* detail, but not this exact command: https://makandracards.com/makandra/17529-git-how-to-remove-ignored-files-from-your-repository-s-directory
    - NB: this would only remove `.gitignore`d files if they are NOT already tracked! If they are already tracked, you must **manually** remove them first with `rm path/to/file && git add path/to/file && git commit`. 
git clean -Xdf
    <========== CLEAN FILES ignored by .gitignore files ==========
    Delete all files and folders which are ignored by .gitignore files.
    - ie: Same as above, but force it to actually run!
    - NB: this would only remove `.gitignore`d files if they are NOT already tracked! If they are already tracked, you must **manually** remove them first with `rm path/to/file && git add path/to/file && git commit`.
    
== to delete a branch: ==

There are actually **3 different branches to delete!**. Read more here: https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely/23961231#23961231
1. Deleting a **local branch**:
    git branch --delete <branch>
    git branch -d <branch> # Shorter version
    git branch -D <branch> # Force-delete un-merged branches
2. Deleting a **remote branch**:
    git push --delete origin <branch>  # Git version 1.7.0 or newer
    git push -d origin <branch>        # Shorter version (Git 1.7.0 or newer)
    git push origin :<branch>          # Git versions older than 1.7.0
3. Deleting a **remote-tracking branch**:
    git branch --delete --remotes <remote>/<branch>
    git branch -dr <remote>/<branch> # Shorter <===
    -----
    git fetch --prune <remote> # Delete multiple obsolete remote-tracking branches; ie: "Before fetching, remove any remote-tracking references that no longer exist on the remote."--see `man git fetch` then search for "prune"
    git fetch -p <remote>      # Shorter version of the above

== other: ==

git rev-parse HEAD = obtain the git hash for HEAD; see: https://stackoverflow.com/questions/949314/how-to-retrieve-the-hash-for-the-current-commit-in-git/949391#949391
git rev-parse HEAD~4 = obtain the git hash 4 commits prior to HEAD; this is REALLY USEFUL, for instance, when trying to figure out which commit is N commits back when there have been multiple merges and it's confusing which commit was on which fork of those branches when looking at just `git log`. `git lg`, therefore, becomes much more important and useful as well, as it graphically shows these forks, branches, and merges in tree form!

git checkout -- my_file.txt = [WARNING: DESTRUCTIVE OF LOCAL COPY!] check out my_file.txt from HEAD and make it overwrite the current local copy I have! Good for "reverting" local, uncommitted changes on a file or two you're working on and messed up.

git diff --name-only <commit_hash1>..<commit_hash2> | wc -l = see how many files were changed between commit_hash1 and commit_hash2

== Changing commit history author info (name and email address): ==
See: https://help.github.com/en/github/using-git/changing-author-info

In case you made a mistake and had your name and/or email wrong while pushing commits, there's a way to go back and rewrite the history of your entire repo, fixing the author info.
CAUTION: this rewrites the whole history of your repo, meaning ALL (I believe) commit hashes IN ALL BRANCHES IN THE ENTIRE REPO will be changed when done, which means NO common merge-base will exist with any prior, unmerged branches or commits, and anyone who has forked your repo will no longer be able to merge into it without conflicts until they do a *hard reset* to reset their repo back on top of your changed repo, like this:

- Perform a hard reset of your local `master` branch onto the latest `upstream/master` branch:

    git fetch --all
    git checkout master
    # reset their local `master` branch onto your latest, rewritten, upstream master branch (as
    # stored locally on their PC as remote-tracking-branch `upstream/master`)
    git reset --hard upstream/master  # WARNING: this is destructive of any local changes or differences

So, here's how to rewrite the history. See GitHub's instructions here: https://help.github.com/en/github/using-git/changing-author-info

1. Open Terminal.
2. Create a fresh, bare clone of your repository:

    git clone --bare https://github.com/user/repo.git
    cd repo.git

3. Copy and paste the script, replacing the following variables based on the information you gathered:
    1. OLD_EMAIL
    2. CORRECT_NAME
    3. CORRECT_EMAIL

        #!/bin/sh

        git filter-branch --env-filter '

        OLD_EMAIL="old_email@gmail.com"
        CORRECT_NAME="Your_Correct_Full_Name"
        CORRECT_EMAIL="correct_email@gmail.com"

        if [ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL" ]
        then
        export GIT_COMMITTER_NAME="$CORRECT_NAME"
        export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL"
        fi
        if [ "$GIT_AUTHOR_EMAIL" = "$OLD_EMAIL" ]
        then
        export GIT_AUTHOR_NAME="$CORRECT_NAME"
        export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL"
        fi
        ' --tag-name-filter cat -- --branches --tags

4. Press Enter to run the script.
5. Review the new Git history for errors.
6. Push the corrected history to GitHub:

    git push --force --tags origin 'refs/heads/*'

7. Clean up the temporary clone:

    cd ..
    rm -rf repo.git

8. [GS-added] Now update your local ".git/config" file in this repo, OR your user-level "~/.gitconfig" file in your user home directory, ***to ensure your new name and email are correct SO THAT ALL FUTURE COMMITS YOU MAKE in this repo will have your new, correct name and email as well!***

    # assuming you're in your repo of interest, run this to open the editor and edit this repo's
    # git config file (alternatively, edit your user-level git config file with
    # `gedit ~/.gitconfig`)
    gedit .git/config

  Then, ensure the following is somewhere in the file. If it isn't, add it to the bottom!

    [user]
        name = Your_Correct_Full_Name
        email = correct_email@gmail.com

== == 

[Obtain git repo stats to see who has contributed how much (ex: how many commits or how many lines); git stats; count git lines; count git commits; git commit stats; git quick stats]

References:
1. Google search for "git count lines changed by certain author": 
   https://www.google.com/search?q=git+count+lines+changed+by+certain+author&oq=git+count+lines+changed+by+certain+author&aqs=chrome..69i57.11889j0j7&sourceid=chrome&ie=UTF-8
1. How to count total lines changed by a specific author in a Git repository? - https://stackoverflow.com/a/7010890/4561887
1. arzzen/git-quick-stats: https://github.com/arzzen/git-quick-stats

git quick-stats
    [then press `11`]
    Show git commits per author, sorted from most to least.
    See: 
    1. Installation instructions: https://github.com/arzzen/git-quick-stats#installation
    1. https://stackoverflow.com/a/7010890/4561887
git log --author="Gabriel Staples" --pretty=tformat: --numstat | gawk '{ add += $1; subs += $2; loc += $1 - $2 } END { printf "added lines: %s removed lines: %s total lines: %s\n", add, subs, loc }' -
    Count lines added, removed, and net total (added - removed) for author "Gabriel Staples" in the current repo and branch.
    See: https://stackoverflow.com/a/7010890/4561887

How to rename a branch both locally and remotely!
[renaming remote branches; how to rename remote branch]
See: 
1. https://stackoverflow.com/a/45561865/4561887
1. [my answer] https://stackoverflow.com/a/70302053/4561887
GS: my own instructions: ex: rename `master` --> `main` both locally *and* on the remote named `origin`:
```bash
git log master                  # make note of its latest commit hash
git branch -vv                  # view upstreams
git branch -m master main       # rename locally
git push -u origin main:main    # push the new branch name to the remote

git push origin :master         # delete the old remote `master` name
git fetch 
git branch -vv                  # view upstreams to make sure they are right for `main` 
                                # (the upstream should be `origin/main`)
git branch -r                   # view all remote branches (`origin/master` should not exist)
git log main                    # sanity check: ensure it's the same commit hash as `master` before
```


====================================================================================================
= cron jobs: =
====================================================================================================
[chrono/chronjobs <-- (misspelled), cronjobs, crono, chrono, crontab -l, crontab -e]

See: "eRCaGuy_dotfiles/useful_scripts/cronjobs/README.md" for commands, setup, format, examples, etc.
Online link: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/tree/master/useful_scripts/cronjobs


====================================================================================================
= git lfs: =
====================================================================================================

See my Q&A: How to use git lfs as a basic user: This covers the question: "What is the difference between git lfs fetch, git lfs fetch --all, git lfs pull, and git lfs checkout?": https://stackoverflow.com/a/72610495/4561887

Assuming you have a repo with a MASSIVE set of files managed by `git lfs` (ex: 20 GB), you should configure a cronjob [chron job] to run every night at 2am to pull the latest files, as described here: "eRCaGuy_dotfiles/useful_scripts/cronjobs/README.md".

References:
1. *****+Great article!: [my developer planet: Git LFS: Why and how to use](https://mydeveloperplanet.com/2018/10/31/git-lfs-why-and-how-to-use/)
1. https://git-lfs.github.com/
1. My repo and notes: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles#how-to-clone-this-repo-and-all-git-submodules
1. *****[my Q&A] [How to use `git lfs` as a basic user: What is the difference between `git lfs fetch`, `git lfs fetch --all`, `git lfs pull`, and `git lfs checkout`?](https://stackoverflow.com/a/72610495/4561887)
1. [my ans] How to shrink your .git folder in your git repo: https://stackoverflow.com/a/68554906/4561887
1. Google search for "how does git lfs store files more efficiently than git?": https://www.google.com/search?q=how+does+git+lfs+store+files+more+efficiently+than+git%3F&oq=how+does+git+lfs+store+files+more+efficiently+than+git%3F&aqs=chrome.0.69i59.265j0j9&sourceid=chrome&ie=UTF-8
1. ***** VERY USEFUL VIDEO!: What is Git LFS?: https://www.youtube.com/watch?v=9gaTargV5BY
    I discovered this video from here: https://stackoverflow.com/a/49173061/4561887

sudo apt update && sudo apt install git-lfs
    Install `git lfs` in Ubuntu
    See: https://mydeveloperplanet.com/2018/10/31/git-lfs-why-and-how-to-use/
git lfs install
    Install `git lfs` git hooks into your repo, and update your ~/.gitconfig file with "lsf" filter info.
    See: https://mydeveloperplanet.com/2018/10/31/git-lfs-why-and-how-to-use/
git lfs track "*.jpg" "*.JPG"
    Track all *.jpg and *.JPG files using `git lfs`.
    See: https://mydeveloperplanet.com/2018/10/31/git-lfs-why-and-how-to-use/
git lfs track "largefiles/*.jpg"
    Track all *.jpg files inside the "largefiles" dir; ie: all files at path "largefiles/*.jpg".
    See: https://mydeveloperplanet.com/2018/10/31/git-lfs-why-and-how-to-use/
git lfs untrack "*.jpg" "*.JPG"
    _Stop_ tracking these files.
    See `man git lfs`.
git lfs ls-files
    List all files being tracked by `git lfs`.
git add -A
    Add all files to the "index", or git staging area, including files now tracked by `git lfs`. 
git commit
    Commit all staged files to the git repo. Files tracked by `git lfs` will just have a pointer in the git repo history, and the actual binary content will be stored on a separate server from the git repo, so as to minimize the data the git repo must track and to keep the size of the git repo small.
    See: https://mydeveloperplanet.com/2018/10/31/git-lfs-why-and-how-to-use/
git lfs prune
    Clean up (remove) old git lfs cached files from .git/lfs which are no longer used.
    See: 
    1. https://mydeveloperplanet.com/2018/10/31/git-lfs-why-and-how-to-use/
    1. [my answer] How to shrink your .git folder in your git repo: https://stackoverflow.com/a/68554906/4561887
git lfs pull
    Fetch and check out all git lfs files for the git commit or branch you are currently on. 
    This one command is the equivalent of these 2 commands:
    ```bash
    git lfs fetch
    git lfs checkout
    ```
    See: [my Q&A] [How to use `git lfs` as a basic user: What is the difference between `git lfs fetch`, `git lfs fetch --all`, `git lfs pull`, and `git lfs checkout`?](https://stackoverflow.com/a/72610495/4561887)


====================================================================================================
= git submodules: =
====================================================================================================

REFERENCES:
1. READ THIS TUTORIAL!: https://www.vogella.com/tutorials/GitSubmodules/article.html 
1. *****+ Official documentation!: https://git-scm.com/book/en/v2/Git-Tools-Submodules <==== READ THIS! ====
1. `man git submodule`

# 1. HOW TO ADD A REPO AS A SUBMODULE TO ANOTHER GIT REPO:
SEE: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> "Starting with Submodules"
--------------------
git clone https://github.com/ElectricRCAircraftGuy/eRCaGuy_X9C_digital_pot.git
    Clone this project (repo).
cd eRCaGuy_X9C_digital_pot
    cd (change directories) into it.
git submodule add https://github.com/ElectricRCAircraftGuy/eRCaGuy_CodeFormatter.git
    <=======
    **Clone** AND add AND stage for commit this eRCaGuy_CodeFormatter repo as a repo (submodule) within the current repo. 
    IT IS PROBABLY BEST TO USE THE "https" URL, NOT the "ssh" URL, so that others who may not have ssh keys set up in github can still read from it and clone this repo too, even though they don't have their ssh keys set up--which I think throws an error during cloning if they attempt to use the "ssh" url otherwise. 
    See here: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> see also the "Note" at the bottom of the "Starting with Submodules" section which talks about configuring your own 'PRIVATE_URL' which you have push access to. See also the `git config` command I use just below to set a private push/pull url for just myself!
git submodule add https://github.com/ElectricRCAircraftGuy/ripgrep_replace.git useful_scripts/ripgrep_replace
    <=======
    Same as above, except add the submodule's file contents directly into the repo's sub-directory at "useful_scripts/ripgrep_replace" instead of into the default path at just "ripgrep_replace".
    See: https://stackoverflow.com/a/9035930/4561887
    See especially all of my comments underneath that answer too!:
        > I figured it out! Please update your answer to explain these subtleties. Let's say I want to add my [ripgrep_replace](https://github.com/ElectricRCAircraftGuy/ripgrep_replace) repo as a subrepo inside my [eRCaGuy_dotfiles](https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles) repo, at the path `eRCaGuy_dotfiles/useful_scripts/ripgrep_replace`. To do that using the command style shown in your answer, you must do `cd eRCaGuy_dotfiles`...
        > 
        > ...and then `git submodule add https://github.com/ElectricRCAircraftGuy/ripgrep_replace.git useful_scripts/ripgrep_replace`, NOT `git submodule add https://github.com/ElectricRCAircraftGuy/ripgrep_replace.git useful_scripts`! See the difference in the path I specified? I tried the latter command and it gives me the error `'useful_scripts' already exists in the index`. I mistakenly thought that I only had to specify the directory I want the `ripgrep_replace` dir inside, but rather, I must specify the full path I want that repo's _actual files_ inside!
cd "useful_scripts" && git submodule add https://github.com/ElectricRCAircraftGuy/ripgrep_replace.git
    <======= ADD SUBMODULE TO SPECIFIC SUB-DIR =======
    Same as above: add the 'ripgrep_replace' submodule's file contents directly into the currently-checked-out repo's sub-directory at path "useful_scripts/ripgrep_replace". Notice that the `ripgrep_replace` dir is added automatically even though it is *not* manually specified!
    This is even easier than the command above because you don't have to remember the command above and its folder name nuances! You just `cd` into wherever you want a submodule to go, then call the `git submodule add <path/to/submodule.git>` cmd and the folder "submodule" will automatically be created there, and the file contents of that submodule cloned to be within it!
    See: https://stackoverflow.com/a/17401451/4561887
git status
    See the submodule in your current repo, which IS now already staged from the `git submodule add` cmd above, but is NOT yet committed. 
    You will see two new files:
            new file:   .gitmodules
            new file:   eRCaGuy_CodeFormatter
git submodule status
    <================
    List all submodules (sub-repos) in your repo, and show which commit hash each submodule is currently set to point to.
    Where I first learned this: https://stackoverflow.com/a/1030263/4561887
git diff --cached eRCaGuy_CodeFormatter
    See the cached changes. You'll see eRCaGuy_CodeFormatter as a particular **commit hash** from that repository! Even though it's a folder and a submodule, git tracks it as a particular git commit hash from that repository. 
    See here: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> search for "Instead, Git sees it as a particular commit from that repository."
git diff --cached --submodule
    See a nicer `git diff` view with special submodule information for this submodule. 
    NB: If you don't want to type `git diff --submodule` all the time, add the "log" setting to your config like this: `git config --global diff.submodule log`. See: https://git-scm.com/book/en/v2/Git-Tools-Submodules.
git commit
    Commit the added submodule to your current repo. When you do, you'll see something like this:
            2 files changed, 4 insertions(+)
            create mode 100644 .gitmodules
            create mode 160000 eRCaGuy_CodeFormatter
    Notice the `160000` mode for the eRCaGuy_CodeFormatter entry. This means that entry is a git submodule directory, rather than a regular, tracked file or directory. 
git config submodule.eRCaGuy_CodeFormatter.url git@github.com:ElectricRCAircraftGuy/eRCaGuy_CodeFormatter.git
    Add my private GitHub "ssh" url which I can also **push** to! This way, public users of my repo can easily pull using my https url (or the ssh one if they have ssh keys set up in GitHub), but I can also **push** using my ssh url. 
    See here: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> see also the "Note" at the bottom of the "Starting with Submodules" section which talks about configuring your own 'PRIVATE_URL' which you have push access to.
git push origin master
    Push these changes to the remote repo on GitHub. 

# 2. HOW TO CLONE A REPO WITH SUBMODULES:
SEE: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> "Cloning a Project with Submodules"
--------------------
-----
OPTION 1 
(explicit--multiple commands):
-----
git clone https://github.com/ElectricRCAircraftGuy/eRCaGuy_X9C_digital_pot.git
    Clone this project (repo). NB: "When you clone such a project, by default you get the directories that contain submodules, but none of the files within them yet" (https://git-scm.com/book/en/v2/Git-Tools-Submodules). 
git submodule init
    Initialize your local git configuration file (inside ".git/config" maybe?)
git submodule update
    Clone all 1-level-deep submodules within this repo. OR:
git submodule update --recursive
    [BETTER than the cmd just above] Clone all n-level-deep submodules within this repo, recursively, to all levels of nesting. 
    See: `man git submodule`, then search for "--recursive", until you find this under the `update` section:
    > If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within.
-----
OPTION 2 [GREAT]: <==============
-----
git clone --recurse-submodules https://github.com/ElectricRCAircraftGuy/eRCaGuy_X9C_digital_pot.git
    Clone the main repo, as well as all submodules, recursively down to all levels of submodules. 
-----
OPTION 3 [the shorter version of Option 1]:
-----
git clone https://github.com/ElectricRCAircraftGuy/eRCaGuy_X9C_digital_pot.git
    Clone the repo, but not the submodules. 
git submodule update --init
    This is the equivalent of `git submodule init` followed by `git submodule update`.
-----
OPTION 4 [BEST I THINK!]: <======= BEST ========
-----
git clone https://github.com/ElectricRCAircraftGuy/eRCaGuy_X9C_digital_pot.git
    Clone the repo, but not the submodules. 
git submodule update --init --recursive
    <========== USE THIS! ==========
    BEST! Combines `git submodule init` followed by `git submodule update --recursive`, thereby fetching and checking out any and all nested submodules as well!
-----
OPTION 5 [ALSO A GREAT TECHNIQUE IT SEEMS! [NEED TO TEST IT STILL TO BE SURE]]
-----
git clone --recursive https://github.com/ElectricRCAircraftGuy/eRCaGuy_X9C_digital_pot.git
    Clone the repo, AND the submodules, all in one go!

# 3. PULLING UPSTREAM CHANGES INTO THE SUBMODULES [>> run BOTH commands below, in this order! <<]
SEE: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> "Pulling Upstream Changes from the Project Remote"
--------------------
git pull
    Pull all upstream changes in the repo as well as submodules. This apparently does NOT, I think, check out the submodule changes just pulled, however--maybe they are just fetched?
git submodule update --init --recursive
    <====================
    (See the more-preferred option order just below).
git submodule update --recursive --init
    <========== USE THIS! ==========
    Update (clone) all submodule changes too. 
    GS: as determined through experimental testing, this also **checks out the appropriate commit hash** for each submodule, in a "detached head" (`HEAD detached at commit_id`) state! You can `cd` into each submodule directory and run `git status` and `git log` to see what I mean!

- How to update all git submodules in a repo (two ways to do two _very different_ things!):
git submodule update --init --recursive
    <============================
    Option 1: as a **user** of the outer repo, pull the latest changes of the
    sub-repos as previously specified (pointed to as commit hashes) by developers
    of this outer repo.
    - This recursively updates all git submodules to their commit hash pointers as
      currently committed in the outer repo.
    See my answer: https://stackoverflow.com/a/74470585/4561887
git submodule update --init --recursive --remote
    <============================
    Option 2. As a **developer** of the outer repo, update all subrepos to force
    them each to pull the latest changes from their respective upstreams (ex: via
    `git pull origin main` or `git pull origin master`, or similar, for each
    sub-repo). 
    See my answer: https://stackoverflow.com/a/74470585/4561887

OTHER, GENERAL NOTES ABOUT GIT SUBMODULE CMDS:

git diff --submodule
    Show a nicer `git diff` view for submodules. 

git submodule status
    Show which commit hash each submodule is currently set to point to.
    Where I first learned this: https://stackoverflow.com/a/1030263/4561887
git submodule update --init
    Initialize and update (clone) all submodules in this repo to 1-level deep.
    See: https://git-scm.com/book/en/v2/Git-Tools-Submodules
git submodule update --init --recursive
    <========== USE THIS ONE, esp. after each `git pull`! ==========
    Initialize (ie: do for the first time) and update (clone) all submodules in a git repo, recursively, to all levels deep.
    See: https://stackoverflow.com/questions/1030169/easy-way-to-pull-latest-of-all-git-submodules/1032653#1032653
    and https://git-scm.com/book/en/v2/Git-Tools-Submodules --> see:
        > Note that to be on the safe side, you should run `git submodule update` with the `--init`
        > flag in case the MainProject commits you just pulled added new submodules, and with the
        > `--recursive` flag if any submodules have nested submodules.
git submodule update --recursive
    Call this every time thereafter? (ie: after the first time when you also initialized?)--NO! Use the command above instead!: `git submodule update --init --recursive`. See the quote from the official `git submodule` documentation in the description of the cmd just above. 
    Just update all submodules, recursively, assuming you've already initialized at least once.
    See: https://stackoverflow.com/questions/1030169/easy-way-to-pull-latest-of-all-git-submodules/1032653#1032653
    and https://git-scm.com/book/en/v2/Git-Tools-Submodules

git submodule update --remote
    In place of manually `cd`ing into each submodule and pulling/fetching the latest, then committing it in the parent repo, you can call this command to automatically go into each submodule and do that for you, thereby updating each submodule (ALL submodules) in the project to point to the latest version (commit hash) of those submodule repos!
    See: https://git-scm.com/book/en/v2/Git-Tools-Submodules
git submodule update eRCaGuy_CodeFormatter
    Just update the `eRCaGuy_CodeFormatter` submodule within the current git repo. 
    See: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> search for "If you have a lot of them, you may want to pass the name of just the submodule you want to try to update."
git config -f .gitmodules submodule.eRCaGuy_CodeFormatter.branch my_branch
    Write to your local .gitmodules file that you want the branch pulled into the eRCaGuy_CodeFormatter submodule to be `my_branch`, rather than the default `master`!
    See: https://git-scm.com/book/en/v2/Git-Tools-Submodules --> search for "git config -f .gitmodules".


====================================================================================================
= github: =
====================================================================================================

- This is mostly to describe things like doing searches on GitHub. 
- For `git` commands related to GitHub, see the "== GitHub: ==" subsection of the "= git: =" main section above instead.

== GitHub search: ==
1. See my longer answer and "GitHub search quick-reference cheat sheet" here: https://stackoverflow.com/questions/29136057/can-i-search-github-labels-with-logical-operator-or/61618255#61618255
1. See my shorter answer here. This is a summary of what to expect when using the GitHub global search bar versus the GitHub Pull Request search bar: https://webapps.stackexchange.com/questions/57933/how-to-search-with-logic-operators-on-github/142071#142071

The following content is my own content that I wrote, originally copy/pasted from [here](https://stackoverflow.com/questions/29136057/can-i-search-github-labels-with-logical-operator-or/61618255#61618255).

# GitHub search quick-reference cheat sheet:
Reminder: [read here](https://webapps.stackexchange.com/questions/57933/how-to-search-with-logic-operators-on-github/142071#142071) for a quick refresher/summary of what to expect when using the GitHub global search bar versus the GitHub Pull Request search bar.

## DEFAULT GITHUB PULL REQUEST (PR) SEARCHES:
1. All open PRs created by me:
    1. https://github.com --> click "Pull requests" at the *very top*.
    1. Direct link: https://github.com/pulls
1. All open PRs assigned to me:
    1. https://github.com --> "Pull requests" --> "Assigned".
    1. Direct link: https://github.com/pulls/assigned
1. All open PRs which mention me in a comment (via @my-username):
    1. https://github.com --> "Pull requests" --> "Mentioned".
    1. Direct link: https://github.com/pulls/mentioned
1. All open PRs for which my review is requested:
    1. https://github.com --> "Pull requests" --> "Review requests".
    1. Direct link: https://github.com/pulls/review-requested

## CUSTOM GITHUB PULL REQUEST (PR) SEARCHES:
-----------------------------------------
1. SEE ALL OPEN PRS--BY AUTHOR
Sample Chrome bookmark to create to one of these URLs: "PRS BY AUTHOR--Username 1"
-----------------------------------------
    1. Using the Pull request search bar:
        1. https://github.com --> click "Pull requests" at the *very top*.
        1. Direct link: https://github.com/pulls
        1. Now use the search bar at the top-center/top-right.
        1. _Note that this search bar is limited to only one author at a time:_

                is:open is:pr archived:false author:username-1
                is:open is:pr archived:false author:username-2
                is:open is:pr archived:false author:username-3
                is:open is:pr archived:false author:username-4

        1. Here is a sample URL for the first of the 4 searches just above: https://github.com/pulls?q=is%3Aopen+is%3Apr+archived%3Afalse+author%3Ausername-1
            1. Now create a Google Chrome shortcut named "PRS BY AUTHOR--Username 1", pointing to this URL!

    1. Using the GitHub global search bar (main search bar at top-left of any GitHub page):
        - This search bar allows multiple authors at once, but displays slightly differently than (doesn't look as good as) the Pull request search above:

                is:open is:pr archived:false author:username-1 author:username-2 author:username-3 author:username-4

        - Here is what the URL looks like after performing this search in the GitHub global search bar: https://github.com/search?q=is%3Aopen+is%3Apr+archived%3Afalse+author%3Ausername-1+author%3Ausername-2+author%3Ausername-3+author%3Ausername-4
            - Now create a Google Chrome shortcut named "PRS BY AUTHOR--ALL", pointing to this URL!

-----------------------------------------
2. SEE REVIEW REQUESTS of me from AUTHOR
Sample Chrome bookmark to create to one of these URLs: "REVIEW REQUESTED BY--Username 1"
-----------------------------------------
    1. Using the Pull request search bar:
        - Note that this search bar is limited to only one author at a time:

                is:open is:pr archived:false review-requested:my-username author:username-1
                is:open is:pr archived:false review-requested:my-username author:username-2
                is:open is:pr archived:false review-requested:my-username author:username-3
                is:open is:pr archived:false review-requested:my-username author:username-4

        - Here is a sample URL for the first search above: https://github.com/pulls?q=is%3Aopen+is%3Apr+archived%3Afalse+review-requested%3Amy-username+author%3Ausername-1
            - Now create a Google Chrome shortcut named "REVIEW REQUESTED BY--Username 1", pointing to this URL!

    1. Using the GitHub global search bar (main search bar at top-left of any GitHub page):
        - This search bar allows multiple authors at once, but displays slightly differently than (doesn't look as good as) the Pull request search above:

                is:open is:pr archived:false review-requested:my-username author:username-1 author:username-2 author:username-3 author:username-4

        - URL produced by the above global search: https://github.com/search?q=is%3Aopen+is%3Apr+archived%3Afalse+review-requested%3Amy-username+author%3Ausername-1+author%3Ausername-2+author%3Ausername-3+author%3Ausername-4
            - Now create a Google Chrome shortcut named "REVIEW REQUESTED BY--ALL", pointing to this URL!


====================================================================================================
= ssh: =
====================================================================================================
[incl: sshfs, ssh, putty, etc.]

== ssh keys: ==
- including for use with GitHub

Key setup: see:
1. https://help.github.com/en/enterprise/2.20/user/github/authenticating-to-github/connecting-to-github-with-ssh
1. Generating a key: https://help.github.com/en/enterprise/2.20/user/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent

GENERATE SSH KEYS:
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
    generate a 4096-bit RSA key (strong encryption--industry standard today)
OR
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -f ~/.ssh/id_rsa
    same as above, except **explicitly** tell it to save the private key into the output file "~/.ssh/id_rsa"!
ssh-keygen -t ed25519 -C "your_email@example.com"
    BEST and FASTEST and NEWEST encryption (better than the RSA one above, but not yet as widely supported; works fine on GitHub though!)

ADD YOUR SSH PRIVATE KEY TO THE SSH-AGENT:
ssh-add ~/.ssh/id_rsa
    Add this **private** ssh key to your ssh-agent on your PC so this key is easily usable for signing or verification wherever needed. See: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.

READ SSH KEYS AND CHECK THEIR FINGERPRINTS:
- See: https://stackoverflow.com/questions/9607295/calculate-rsa-key-fingerprint/32130465#32130465
ssh-keygen -lf ~/.ssh/id_rsa
    'l'ist the fingerprint of the 'f'ile ~/.ssh/id_rsa, which is the private key. The default fingerprint type is "sha256" (`-E sha256`)
ssh-keygen -E sha256 -lf ~/.ssh/id_rsa
    exact same thing as above, except explicitly setting the fing'E'rprint type to sha256
ssh-keygen -E sha256 -lf ~/.ssh/id_rsa.pub
    exact same thing as above, except using the public (.pub) key instead of the private one
ssh-keygen -E md5 -lf ~/.ssh/id_rsa.pub
    'l'ist the fing'E'rprint of this public key 'f'ile using the md5 hash, WHICH IS THE SAME FINGERPRINT HASH THAT GITHUB USES ONLINE IN CASE YOU ARE TRYING TO COMPARE YOUR HASH AGAINST WHAT GITHUB IS SHOWING TO SEE WHICH KEY IS BEING USED ON GITHUB! <===========
    - Note that using the *private* key in the above commands has the added benefit of telling you also *what the public key file is named and where it is located*, and *what type the key is!* The key type will be listed in parenthesis at the very end. Ex: '(ED25519)' or '(RSA)'.

COPY PUBLIC SSH KEY TO ANOTHER COMPUTER FOR KEY-BASED/PASSWORD-LESS LOGON:
ssh-copy-id -i ~/.ssh/id_rsa.pub user@hostname_or_ip_addr
    copy your public identity file (public SSH key) "~/.ssh/id_rsa.pub" to the computer user@hostname_or_ip_addr into its ~/.ssh/authorized_keys file.
    - See: https://askubuntu.com/questions/4830/easiest-way-to-copy-ssh-keys-to-another-machine/4833#4833
cat ~/.ssh/id_rsa.pub | ssh user@hostname_or_ip_addr 'cat >> ~/.ssh/authorized_keys && echo "Key copied"'
    alternative, more "manual" way to do the above, manually copying your .pub public key into the server/host's "~/.ssh/authorized_keys" file!
    - See: https://askubuntu.com/questions/4830/easiest-way-to-copy-ssh-keys-to-another-machine/6186#6186

== sshfs: ==
sshfs -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3 username@server_hostname:/path/on/server/to/mount ~/mnt/my_server
    do an ssh 'F'ile 'S'ystem mount of a remote PC's disks to your local PC, over ssh. More specifically: mount path "path/on/server/to/mount", on the server "username@server_hostname", to your local disk at location "~/mnt/my_server", doing some fancy keep-alive stuff to keep the connection from going stale and disconnecting you!
    - See: [my own ans] https://askubuntu.com/questions/791002/how-to-prevent-sshfs-mount-freeze-after-changing-connection-after-suspend/942820#942820


====================================================================================================
= grep: =
====================================================================================================

*****See my own answer here, for instance, for `grep` & `git grep` examples: https://stackoverflow.com/questions/60843047/locating-a-function-in-a-git-repository/60843055#60843055

time git grep -E -n "\bmyFuncName\b" = do a *whole word search* (hence the \b surrounding the search string) for "myFuncName", displaying li'n'e 'n'umbers (`-n`) too

== Exlude a word: ==
Use the `-v`, or `--invert-match` option! See:
1. https://stackoverflow.com/questions/4538253/how-can-i-exclude-one-word-with-grep/4538335#4538335
1. https://stackoverflow.com/questions/10411616/grep-regex-not-containing-string/10411661#10411661
    grep "pattern_to_find" file | grep -v "pattern_to_exclude" = search for "pattern_to_find" while EXCLUDING (in'v'erting the match on) "pattern_to_exclude"  <==== EXCLUDE WORD(S) WHEN GREP-SEARCHING! =====
OR
    grep -v "unwanted_word" file | grep "wanted_word" = same as above, just in the opposite order is all.

Here's some examples. This outputs "redhat" and "yellowtail":
    $ echo "redhat redwood redbox redding yellowtail" | grep -E -o "(redhat|yellowtail)"
    redhat
    yellowtail
So this outputs just "yellowtail", by then excluding anything with "red" in it!:
    $ echo "redhat redwood redbox redding yellowtail" | grep -E -o "(redhat|yellowtail)" | grep -v red
    yellowtail

find -type f | grep -v \.xml | xargs grep --color=always my_regex_search
    <====== VERY USEFUL! =======
    find only 'f'iles (no directories) which do NOT end in .xml, then search each of those files to see if they contain "my_regex_search" 

find some/path/ -maxdepth 1 -type d | grep "_messages$"
    find only 'd'irectories (`-type d`) in some/path/, only 1 layer deep (`-maxdepth 1`), which have names that end in (`$` indicates a line end) "_messages"


====================================================================================================
= ripgrep: =
====================================================================================================
(better/faster than `grep`, `git grep`, etc.)

References:
1. *****+[EXCELLENT USAGE INFO AND EXAMPLES!] [ripgrep is faster than {grep, ag, git grep, ucg, pt, sift}](https://blog.burntsushi.net/ripgrep/)
    1. See also the usage example titled "Search and replace"!
1. *****https://github.com/BurntSushi/ripgrep
    1. Installation (see the section for "Debian"/"Ubuntu"): https://github.com/BurntSushi/ripgrep#installation
1. https://mariusschulz.com/blog/fast-searching-with-ripgrep

rg 'regex_search'
    ripgrep search for pattern 'regex_search'
rg -L 'regex_search'
    <=========== VERY USEFUL! ==========
    ripgrep search for pattern 'regex_search', FOLLOWING SYMBOLIC 'L'INKS [symbolic links] while traversing directories! 
rg 'regex_search' -g '*.h'
    <========== ALSO VERY USEFUL ==========
    search for pattern 'regex_search' while searching ONLY in files/paths which match Linux/Unix file glob pattern '*.h'. Source: from the creater of ripgrep himself! https://unix.stackexchange.com/questions/503161/ripgrep-path-pattern/503170#503170 
rg -L --no-ignore 'some regular expression' -g "*.c" 2>/dev/null
    <=============== VERY GOOD! ===============
    Search paths ignored in your .gitignore file. ie: Search for all .c files in your git repo, searching down symbolic linkes (`-L`) and down paths which are in your .gitignore files (hence `--no-ignore`!), sending all stderr error output to /dev/null to ignore it (hence `2>/dev/null`). 
    [keywords: regex ripgrep rg search git repo and output build directories dirs too!; search git output; search git build dir; search build dir; search output dir; rg ignore]
rg -L --no-ignore --hidden 'some regular expression' -g "*.c" 2>/dev/null
    <=================== BEST! ===================
    Same as above, but also search hidden directories--ie: dirs which begin with a dot (.)!
    [keywords: rg --hidden; rg --no-ignore; rg hidden; hidden rg]
`
== Comparison of `grep` to `rg` (ripgrep): ==
[grep to ripgrep, grep to rg command comparison]
grep -Rn regex_search some/path/to/search/ = search for `regex_search`, 'R'ecursively (following symlinks), only in path "some/path/to/search/", while showing line 'n'umbers where a match is found
rg -L regex_search some/path/to/search/ = exact same as above, except using ripgrep, which is much faster!


====================================================================================================
= Jinja2: =
====================================================================================================

- a template-based automatic code/file generator (think string formatter/replacer for an entire text file).

Main Jinja2 References:
1. [Main Jinja2 website](https://jinja.palletsprojects.com/en/2.11.x/)
2. [Entire Jinja2 documentation in PDF form](https://jinja.palletsprojects.com/_/downloads/en/2.11.x/pdf/)
3. [Jinja2 Python API](https://jinja.palletsprojects.com/en/2.11.x/api/)
4. [Jinja2 Template Designer (used for writing template files, which some people like to end in .j2)](https://jinja.palletsprojects.com/en/2.11.x/templates/)


====================================================================================================
= Binutils & other developer tools: =
====================================================================================================

objdump, ld, nm, size, strings, etc.

References:
1. https://www.gnu.org/software/binutils/
2. [my own Q!] [How do I find out at compile time how much of an STM32's Flash memory and dynamic memory (SRAM) is used up?](https://electronics.stackexchange.com/questions/363931/how-do-i-find-out-at-compile-time-how-much-of-an-stm32s-flash-memory-and-dynami)
3. ***** [EXCELLENT INFO! An "object file" IS an "executable"! This also has definitions for "VMA" and "LMA"] https://sourceware.org/binutils/docs/ld/Basic-Script-Concepts.html#Basic-Script-Concepts
1. MY DETAILED ANSWERS HERE!:
    1. [on Stack Overflow](https://stackoverflow.com/questions/64073080/convert-binutils-size-output-from-sysv-format-size-format-sysv-my-execut/64080798#64080798) and here:
    1. [on Electronics Stack Exchange](https://electronics.stackexchange.com/questions/363931/how-do-i-find-out-at-compile-time-how-much-of-an-stm32s-flash-memory-and-dynami/523439#523439).

nm <objfiles>
    "List symbols from object files" (see `man nm`). GS note: "object files" simply means executables, such as `a.out`! See here: https://sourceware.org/binutils/docs/ld/Basic-Script-Concepts.html#Basic-Script-Concepts.
objdump -t <objfiles>
    Show symbols in an object file (very similar to the `nm` command just above!). See reference 3 above!
objdump -h <objfiles>
    Show output sections in an object file (executable). See reference 3 above! See also the `size --format=sysv /bin/ls` command below.
size -h
    See help menu for `size` cmd. See also: `man size`.
size <objfiles>
    "Lists the section sizes of an object or archive file [ie: an executable output file from building with gcc]." (See link 1 above, and also my Q and the Ans. at link 2 above). See also `man size`. If no object files are specified, "the file a.out will be used".
size a.out
    List size info. for the "a.out" executable object file. (Note: this [a.out] is the default executable output file name which gcc produces if no other name is specified to gcc via the `-o executable_name` option).
size /bin/ls
    Show (berkeley-formatted [short info]) size info. on the `ls` command.
    Sample output:
            $ size /bin/ls
               text    data     bss     dec     hex filename
             124042    4728    4832  133602   209e2 /bin/ls
    **Note:** `text` is program space, `data` is non-zero-initialized (ie: initialized with something OTHER than zero) static or global variables, `bss` is zero-initialized (or uninitialized) static or global variables, and `dec` and `hex` are both the sums of `text + data + bss`, in decimal and hex format, respectively.
    See here for where I got a lot of my information below: https://electronics.stackexchange.com/questions/363931/how-do-i-find-out-at-compile-time-how-much-of-an-stm32s-flash-memory-and-dynami/363932#363932.
      FOR A MICROCONTROLLER:
        1. Here's the breakdown for what takes up Flash memory vs RAM:
            1. text takes up flash memory.
            2. data takes up both flash memory AND RAM, since the values must be stored in flash to be copied into RAM during startup.
            3. bss takes up RAM only, since the instructions in flash for bss memory just needs to store how many variables and what sizes need to be allocated in RAM, and whether to zero-initialize them or not, but the instructions for bss memory do NOT need to store any actual values for these variables.
            (4.) GS note: there's also a linker script `.rodata` section, which is for "read-only data". This is **constant static or global variables**, and on STM32 mcus, is automatically placed into flash memory and therefore takes up flash only, since these variables are constant and do not need to be in RAM to be written to.
        1. "RAM used by static or global variables" (as reported by the Arduino IDE, for instance) = data + bss.
            1. So, this means that "RAM remaining for local variables" (ie: the **stack**) and for dynamic memory allocation (the **heap**) = RAM_total - "RAM used by static or global variables" = RAM_total - (data + bss).
        1. Program space (flash memory) used (as reported by the Arduino IDE, for instance) = text + data.
        1. I have to assume that since ".rodata" is NOT shown by this default `size` command, but IS shown by the `size --format=berkeley` version of the command below, then ".rodata" must already be included in the "text" section shown above, but I need to do some research to be sure, and to see how to go from the "sysv" format to the default "berkely" format!
            1. UPDATE: THIS IS CORRECT! `.rodata` is marked as `READONLY` in the `objdump -h <objfile>` output section output, meaning it goes into the `text` section. You can also tell this from the LMA and VMA memory addresses in that output.
            1. ===> SEE MY DETAILED ANSWERS HERE!: <===
                1. [on Stack Overflow](https://stackoverflow.com/questions/64073080/convert-binutils-size-output-from-sysv-format-size-format-sysv-my-execut/64080798#64080798) and here:
                1. [on Electronics Stack Exchange](https://electronics.stackexchange.com/questions/363931/how-do-i-find-out-at-compile-time-how-much-of-an-stm32s-flash-memory-and-dynami/523439#523439).
size --format=berkeley /bin/ls
    Same as above, because "berkeley" is the default format.
size -B /bin/ls
    Same as above (berkeley format). See `size -h`.
size --format=sysv /bin/ls
    Show sysv (much longer and more-detailed) size info. on the `ls` command.
size -A /bin/ls
    Same as above (sysv format). See `size -h`.
size -A --radix=16 /bin/ls
    Show `size` info in sysv format (`-A`) and in hex (`--radix=16`) number format!
size -A -x /bin/ls
    Same as above! Display in hex (`-x`) format. Options include octal (`-o`), decimal (`-d`), or hex (`-x`). See `size -h`.
objdump -h /bin/ls
    Show output sections in an object file (executable). Very similar to the above (`size --format=sysv /bin/ls`), except even more-detailed! See: https://sourceware.org/binutils/docs/ld/Basic-Script-Concepts.html#Basic-Script-Concepts.


====================================================================================================
= Binary and ELF file analyzer: =
====================================================================================================

[.map files, .elf files, .bin files, etc.]

UPDATE: SEE MY NOTES HERE INSTEAD: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/blob/master/useful_apps/analyzing_binary_files_README.md

Research:
1. Google search for "elf file memory analyzer": https://www.google.com/search?q=elf+file+memory+analyzer&oq=elf+file+memory+analyzer&gs_lcrp=EgZjaHJvbWUyBggAEEUYOdIBCTI0Mzg5ajBqNKgCALACAA&sourceid=chrome&ie=UTF-8

1. https://github.com/jedrzejboczar/elf-size-analyze
    ```bash
    # Install 
    pip3 install elf-size-analyze

    # Example usage for Microchip PIC32 mcu to analyze RAM (`-R`) usage
    elf-size-analyze -t xc32- -HaR path/to/Autopilot.X.production.elf
    ```
1. https://github.com/google/bloaty - Google's Bloaty McBloatface.


====================================================================================================
= Cellular & Networking: =
====================================================================================================
- incl. VPN

Tools to be aware of:
1. ConnMan - network manager
    1. `sudo apt install connman`
    1. https://wiki.archlinux.org/title/ConnMan
    1. https://wiki.gentoo.org/wiki/Connman
1. `connmanctl` - cli interface to connman
    1. https://manpages.debian.org/testing/connman/connmanctl.1.en.html
    1. https://manpages.ubuntu.com/manpages/xenial/man1/connmanctl.1.html
1. oFono and `ofonod` - GSM cellular dbus-centric tool developed by Intel & Nokia
    1. https://en.wikipedia.org/wiki/OFono
    1. https://manpages.ubuntu.com/manpages/bionic/man8/ofonod.8.html
    1. https://www.linux.org/threads/what-do-ofono-and-connman-do.39201/
    1. Linux kernel official source code repo: https://git.kernel.org/pub/scm/network/ofono/ofono.git/about/
1. wpa_supplicant - wifi management
    1. https://wiki.archlinux.org/title/wpa_supplicant
1. BlueZ - the "official Linux Bluetooth protocol stack" (http://www.bluez.org/)
    1. http://www.bluez.org/
    1. Official source code: https://github.com/bluez/bluez
1. strongSwan - IPsec (IP security) embedded Linux VPN
    1. `sudo apt install strongswan`
    1. Official website: https://www.strongswan.org/
    1. https://en.wikipedia.org/wiki/StrongSwan
    1. Official source code: https://github.com/strongswan/strongswan
1. `swanctl` - cli interface to the strongSwan VPN solution tool
    1. `sudo apt install strongswan-swanctl`
    1. `cat /etc/swanctl/swanctl.conf` - view the config file for the strongSwan VPN
    1. Official source code & introductory documentation: https://github.com/strongswan/strongswan
1. `ipsec` strongSwan cli tool
    1. `sudo apt install strongswan` - this installs the `ipsec` cli tool too
    1. https://wiki.strongswan.org/projects/strongswan/wiki/ipseccommand
1. `traceroute` cli tool
    1. `sudo apt install traceroute`

connmanctl services
    "Shows a list of all available services. This includes the nearby wifi networks, the wired ethernet connections, bluetooth devices, etc."
    See: https://manpages.debian.org/testing/connman/connmanctl.1.en.html
man swanctl
swanctl -h
sudo ipsec status
    See: 
    1. `man ipsec`
    1. `ipsec --help`
ip route
sudo apt install traceroute
traceroute
traceroute google.com
traceroute 192.168.0.1
cat /etc/swanctl/swanctl.conf
    View the config file for the strongSwan VPN.


====================================================================================================
= IP & Networking: =
====================================================================================================
Also: Ethernet UDP and TCP command-line commands and tx/rx.
Keywords: ethernet: =

ifconfig
    show the internet & network configuration/connection information for your system and all of its network cards (both wireless (ex: WIFI) and wired (ex: Ethernet ports))
-----
TURN NETWORK INTERFACES ON AND OFF (up or down, respectively)
See: https://askubuntu.com/questions/168032/how-to-disable-built-in-wifi-and-use-only-usb-wifi-card/204536#204536
-----
ifconfig
    list ALL network interfaces; note: see more on "virtual interfaces" and how to create them farther below
iwconfig
    <===== REALLY USEFUL =======
    list all wireless network interfaces (see more on this cmd below)
nmcli
    <=====
    Show a network summary, kind of like `ifconfig`. 
    Network manager command-line interface?
    See this comment to me where I found out about it: https://unix.stackexchange.com/questions/344974/how-can-i-make-changes-to-the-network-routing-metric-permanently/349356?noredirect=1#comment1495324_349356
nmcli device show 
    Show all network **devices**. 
    This command is shown at the bottom of the output from just `nmcli`. 
nmcli connection show 
    Show all network **connections**. 
    This command is shown at the bottom of the output from just `nmcli`.
nmcli device wifi list
    <===== REALLY USEFUL =======
    List all available wifi networks, including their SSIDs and scanned signal strengths / "bars". 
ls /etc/NetworkManager/system-connections/
    See all network connections stored on your system! Note: each of these files is readable by root only, and contains passwords/pre-shared keys too! 
    Editing these files directly **is** allowed. Run `sudo systemctl restart NetworkManager` after editing them to apply changes. 
    See my full answer here on how to edit these files to force a connection over 2.4GHz or 5GHz, for example: https://askubuntu.com/a/1524752/327339.
sudo ifconfig INTERFACE_NAME up
    turn network interface INTERFACE_NAME on; ex:
sudo ifconfig wlan0 up
    <===== REALLY USEFUL =======
    turn network interface wlan0 ON
sudo ifconfig INTERFACE_NAME down
    turn network interface INTERFACE_NAME off; ex:
sudo ifconfig wlan0 down
    <===== REALLY USEFUL =======
    turn network interface wlan0 OFF
sudo ifconfig INTERFACE_NAME down && sudo ifconfig INTERFACE_NAME up
    <==========
    Reset an interface by bringing it down then back up again; this can help fix routing tables I believe? (use `route -n` to show routing tables).
    It seems to me this is kind of like "power cycling" a network interface, and is useful to reset one which isn't working properly! 
    ***You might want to do this after changing an interface's IP address, for instance.***
sudo ifconfig INTERFACE_NAME NEW_IP netmask NEW_NETMASK
    Set a new IP address and netmask to interface "INTERFACE_NAME". 
    See: https://www.howtogeek.com/118337/stupid-geek-tricks-change-your-ip-address-from-the-command-line-in-linux/
    Ex:
sudo ifconfig eth0 192.168.0.1 netmask 255.255.255.0
    Set interface "eth0"'s IP address to a new value of 192.168.0.1, with a new netmask of 255.255.255.0. 
    **NB: run `sudo ifconfig eth0 down && sudo ifconfig eth0 up` when done** to "reset" this interface and (apparently?) re-calculate its routing tables shown by `route` or `route -n`! 
    <===========
route
    Show the IP routing table. [I think this tries to find a name server to look up symbolic host names]
route -n
    Show the IP routing table with numerical addresses instead of trying to determine symbolic host names. [I'm not sure exactly what this means, but I think it skips the name server symbolic name lookup step; in either case, it runs **way** faster than just the `route` command!]

sudo ip link set wlan0 up
    <===== REALLY USEFUL (NEWER CMD!) =======
    Turn ON the `wlan0` networking device--the same as (or very similar to) `sudo ifconfig wlan0 up` above. Apparently this `ip link set` command is intended to replace the older and apparently now-deprecated `ifconfig` cmd above! 
    See: https://www.redhat.com/sysadmin/ifconfig-vs-ip --> sections "What's trending?" and "Enable and disable an interface". 
    See also my answer here: https://askubuntu.com/a/1320155/327339.
    [GS: See more `ip` cmds below!]
sudo ip link set wlan0 down
    <===== REALLY USEFUL (NEWER CMD!) =======
    Turn OFF the `wlan0` networking device--the same as (or very similar to) `sudo ifconfig wlan0 down` above. Apparently this `ip link set` command is intended to replace the older and apparently now-deprecated `ifconfig` cmd above! 
    See: https://www.redhat.com/sysadmin/ifconfig-vs-ip --> sections "What's trending?" and "Enable and disable an interface". 
    See also my answer here: https://askubuntu.com/a/1320155/327339.
    [GS: See more `ip` cmds below!]

iwconfig
    'w'ireless network 'i'nterface configuration tool of some sort (stands for 'i'nterface 'w'ireless perhaps?); see `man iwconfig` and also here for a little more info: https://unix.stackexchange.com/questions/137894/how-do-i-find-out-if-my-wireless-card-supports-5ghz/137895#137895
iwconfig
    list wireless network interfaces
iwlist INTERFACE_NAME freq
    list the available wireless frequencies of interface INTERFACE_NAME; see: https://unix.stackexchange.com/questions/137894/how-do-i-find-out-if-my-wireless-card-supports-5ghz/137895#137895; ex:
iwlist wlan0 freq
    list the available wireless frequencies of wireless network interface `wlan0`
iwlist wlan0 scanning | grep -C5 -i '\"my_network_name\"'
    See all channels and frequencies "my_network_name" is broadcasting on, on both 2.4GHz *and* 5GHz frequencies!
    - See my comment under this answer here: https://askubuntu.com/questions/202288/how-do-i-require-use-of-the-5-ghz-band-when-connecting-to-a-wireless-n-access-po/261410#261410.
    - Note that **2.4GHz channels** include `01`, `02`, `03`, etc. through `11`, and **5GHz channels** are just `36`, `40`, `44`, and `48` (this is based on looking at my Orbi mesh router settings).
    - Also, I first learned this `iwlist` command from here: https://askubuntu.com/questions/183525/how-to-set-wifi-driver-settings-to-prefer-5-ghz-channel-above-2-4-ghz/631329#631329.

nm-connection-editor
    <=================
    Open the "Advanced Network Configuration" GUI! Taught to me by BrosTrend Trend-tech in an email to me on 7 Mar. 2021. One thing you can do is set a "Device", by MAC address, in order to limit one WiFi connection to a specific WiFi adapter. Or, you can leave this "Device" field blank to let that connection work with ANY connected network/WiFi adapter! Be sure to **look at the command-line output in the terminal** when running this program, to take note of any feedback or errors the GUI program may be seeing. This is helpful to indicate to you why you may not be able to save new settings, for instance. 
    See my notes on this cmd here: https://github.com/ElectricRCAircraftGuy/BrosTrendWifiAdapterSoftware

A few esoteric networking commands to be aware of:
See: 
  - https://www.techrepublic.com/blog/data-center/breaking-down-an-ipv6-address-what-it-all-means/
  - https://www.techrepublic.com/blog/data-center/ipv6-in-action-how-mythic-beasts-does-it/
- - - - - 
host www.raspberrypi.org
whois raspberrypi.org
ip addr          
ifconfig
iwconfig
netstat -an

ip help
    show the options and `OBJECT`s available for the `ip [OPTIONS] <OBJECT>` commands!
    - See also MY ANS HERE! https://unix.stackexchange.com/questions/152331/how-can-i-create-a-virtual-ethernet-interface-on-a-machine-without-a-physical-ad/593142#593142
        - https://unix.stackexchange.com/a/593142/114401
man ip
    See the "man" (manual) pages for the higher-level `ip` cmd.
ip link help
    Help menu for the `ip link` cmd.
man ip link
    See the "man" (manual) pages for the `ip link` cmd.
sudo ip link set wlan0 [up|down]
    [GS: See these "ip link set" cmds farther above where I documented them before.]
ip address help
    Show help menu for the `ip address` cmd.
man ip address
    See the "man" (manual) pages for the `ip address` cmd.
ip address
    show all configured network interfaces and their IP addresses & network interface info; NB: I don't really understand this command yet, but it looks useful, and seems to show a bunch of the same information as `ifconfig`.
    - UPDATE Aug. 2023: this command is better than `ifconfig`, because it shows **multiple IP addresses** per interface, if you have manually assigned multiple IP addresses and Subnet masks to a given hardware (or software) interface adapter!
ip addres = same as above
ip addre = same as above
ip addr = same as above
ip add = same as above
ip ad = same as above
ip a = same as above
^^ Note the trend! So long as the command can be figured out and determined to be distinct from all other command possibilities, it is accepted! Therefore, you only need as many characters in the OBJECT as are required to make it distinct from all other OBJECT possibilities for this command!
---------
[virtual interfaces, virtual network interfaces, virtual network devices, virtual devices]
Learn how to make **virtual network interfaces** here!
- Sometimes, you must create a virtual interface to simulate a connected hardware network card with a certain IP address so that software you have which is trying to open up a network socket to that specific device at that specific IP is able to do so, _even if the hardware isn't actually physically present on the PC you are running the software!_ Very useful, for instance, on hardware test platforms or HIL test systems.
  - [MY OWN ANS!] https://unix.stackexchange.com/questions/152331/how-can-i-create-a-virtual-ethernet-interface-on-a-machine-without-a-physical-ad/593142#593142
    - https://unix.stackexchange.com/a/593142/114401
  - https://unix.stackexchange.com/questions/152331/how-can-i-create-a-virtual-ethernet-interface-on-a-machine-without-a-physical-ad/152334#152334
- - - - - 
`modprobe`, `lsmod`, `ip link add`, `ip address change`, `ip address`, `ip link delete`, etc.
See my answer here!: https://unix.stackexchange.com/a/593142/114401
*****ALSO: see this other answer here!: https://unix.stackexchange.com/a/152334/114401
- - - - - 
lsmod
    List and show the status of modules in the Linux Kernel. Creating a dummy interface requires the "dummy" kernel module. 
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
lsmod | grep dummy
    Search for the "dummy" kernel module to see if you have it!
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
sudo modprobe dummy
    1. Install the "dummy" Linux kernel module.
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
    *****ALSO: see this other answer here!: https://unix.stackexchange.com/a/152334/114401
sudo lsmod | grep dummy
    2. Ensure the "dummy" Linux kernel module is installed.
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
    *****ALSO: see this other answer here!: https://unix.stackexchange.com/a/152334/114401
sudo ip link add eth10 type dummy
    3. Create a virtual (dummy) interface named `eth10`.
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
sudo ip address change dev eth10 10.0.0.1
    4. Change this new interface's IP address to whatever you like (10.0.0.1 in this case).
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
ip address
    5. See the newly-created device and the IP address you just assigned to it.
    See what IP addresses and interfaces you have.
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
ip a
    Same as above. See the list of these commands a bit above where I show they are all same!: `ip a`, `ip addr`, `ip address`, etc.
sudo ip link delete eth10 type dummy
    6. Delete this 'eth10' dummy device, if you ever need to.
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
ip address
    7. Ensure 'eth10' is deleted and doesn't show up here now.
ifconfig
    See what IP addresses and interfaces you have (this may not be as complete as the `ip address` cmd above, and it may not show your virtual dummy 'eth10' device you just created above!).
    See my answer here!: https://unix.stackexchange.com/a/593142/114401
ip route get 10.0.0.1
    Show which interface is being used to route this IP address.
    See this comment by @Hauke Laging under my question: https://unix.stackexchange.com/questions/678162/how-to-create-ethernet-interface-at-a-specific-ip-address-that-i-can-ping-and-fo?noredirect=1#comment1280923_678162

ssh -X -o "ServerAliveInterval 60" my_username@my_hostname_or_IP
    ssh into hostname or IP address my_hostname_or_IP with username my_username, enabling X-window forwarding, and with the additional 'o'ption set to send a heartbeat signal (server "keep alive" message) every 60 seconds, so your session never disconnects automatically!

hostname
    show my hostname; ex: mypcname23-aa
nslookup some_ip_address
    use 'n'ame 's'erver lookup to try to find the hostname of a given IP address
nslookup some_hostname
    the exact reverse of the above: try to find the IP address from a given hostname

wget https://path.to.some.file.to.download
    download a file at this URL; shows a nice progress bar and download stats (speed, total size to download, total size downloaded so far, etc.) the entire time!
curl
    cURL stands for "client URL". It "is a command line tool that developers use to transfer data to and from a [web] server."
    See [NEED TO STUDY & READ!]: https://developer.ibm.com/devpractices/api/articles/what-is-curl-command/
    Some web utility for interaction with websites and HTML "REST" APIs; need to learn how to use a lot more still.
curl -X POST --data '{"some key 1":"some value 1","some key 2":"some value 2", "some key 3":"some value 3"}' http://some.web.address
    [NEED TO STUDY & LEARN MORE] Send this JSON object as a `POST` HTML REST command to a web server at this address.
curl -X GET http://some.web.address/some_id
    Assuming the server responded to the previous POST cmd with some ID `some_id`, request some response JSON data object for this `some_id` from the serer. It will come back as a JSON object.
curl -X GET http://some.web.address/some_id | jq .
    Same as above, except pipe all the output to the `jq` (JQuery?) "Command-line JSON processor" so it can pretty-format it all for us. Now, we can look at the (probably JSON) JSON object returned to us from the server in a nice-to-look-at format!
curl http://some.web.address/some_id | jq .
    Same as above (the `-X GET` behavior is the _default_ if not specified!).
curl -X GET http://some.web.address/some_id | jq .key1
    Same as above, except filter on only the outer-most dict key named `key1`, so that that's all we see in the output of the JSON object!
curl -X GET http://some.web.address/some_id | jq .key1.key2
    Same as above, except filter on only the outer-most dict key named `key1`, followed by the sub-level key named `key2`!
curl -X GET http://some.web.address/some_id | jq .key1.key2.key3
    Same as above, except filter in on outer key `key1`, sub-key `key2`, and sub-sub-key `key3`, etc. This pattern can continue indefinitely down to as many sub-levels as you want!
curl -X POST -F "file=@path/to/some_binary_firmware_image.bin" http://192.168.0.2/api/update_firmware
    <========= POTENTIAL WAY TO UPDATE A LINUX BOARD'S ROOTFS IMAGE VIA AN HTTP REST API `POST -F` CMD ===========
    Upload a file via a post to this URL address! The `-F` means "form", but when you have `-F file=@<file>`, it indicates that the "form" is actually a local file you are uploading to some HTTP REST API web server! In this case, the purpose of the web server could be to update a Linux rootfs image on the embedded Linux board running the web server, for instance!
    For details on the `curl` command and `-F` option, see: `man curl` and search for "-F".
    Regarding the meaning of `-F` and `@`, `man curl` states:
    > This [`-F`] enables uploading of binary files etc. **To force the 'content' part to be a file,
      prefix the file name with an `@` sign.** To just get the content part from a file, prefix the
      file name with the symbol `<`. The difference between `@` and `<` is then that `@` makes a 
      file get attached in the post as a file upload, while the `<` makes a text field and just get
      the contents for that text field from a file.
curl --connect-timeout 10 --max-time 30 --data '{"some key 1":"some value 1","some key 2":"some value 2", "some key 3":"some value 3"}' -X POST http://some.web.address
    <=========
    Set curl connect and total timeouts as well!

telnet
    (Note: install with `sudo apt install telnet`).

nmap
    A "network map" tool; network explorer/tester/penetration tester, etc. Tool for network mapping and port scanning.
    - See: https://nmap.org/. 
    - Runs on Windows, Mac, and Linux. Use in conjunction with netcat (`nc`), pcap, Wireshark, etc. 
    - Note: they have their own re-implementation of netcat called `ncat`: https://nmap.org/ncat/. When you install `nmap` on Windows, the Windows installer comes with nmap, so just install nmap and check the extra boxes to install this too and you'll get it.
sudo snap install nmap
    Install the latest "snap" store version of `nmap` on Linux Ubuntu.
sudo apt install ncat
    Install `nmap`'s version of netcat, called `ncat`. 
nmap bitbucket.org
    <===========
    Scan bitbucket.org to see which ports are open. If port 22 does *not* show up, it means that either your local computer firewall (ex: Windows firewall on Windows), *or* your network firewall, is blocking external traffic on this port! 
    - See my Q&A here: [Cannot `git clone` Bitbucket repo on Windows: `ssh: connect to host bitbucket.org port 22: Network is unreachable`](https://stackoverflow.com/q/76918674/4561887)
    - Example run and output:
        ```bash
        $ nmap bitbucket.org
        Starting Nmap 7.93 ( https://nmap.org ) at 2023-08-17 13:55 MST
        Nmap scan report for bitbucket.org (104.192.141.1)
        Host is up (0.017s latency).
        Other addresses for bitbucket.org (not scanned): 2406:da00:ff00::22cd:e0db
        Not shown: 997 filtered tcp ports (no-response)
        PORT    STATE SERVICE
        22/tcp  open  ssh
        80/tcp  open  http
        443/tcp open  https

        Nmap done: 1 IP address (1 host up) scanned in 5.14 seconds
        ```
    - Note that port 22 above is for SSH-based git operations with BitBucket. Port 443 is HTTPS (and they allow ssh on this port too, to help people whose network administrators block port 22). Port 80 is HTTP.

Use `netcat` (`nc`) for sending and receiving Ethernet packets (either UDP OR TCP) in Linux from the command-line! 
NB: if using Python, you can use the `socket` library instead!: https://docs.python.org/3/library/socket.html
Examples: 
    1. Official examples: https://docs.python.org/3/library/socket.html#example
    1. [my own example code] https://github.com/ElectricRCAircraftGuy/eRCaGuy_hello_world/blob/master/python/socket_talk_to_ethernet_device.py
*****+ See my full tutorial here too for general netcat commands!: "General netcat (`nc`) usage instructions, including setting the IP address to bind to when receiving, or to send to when sending" - https://serverfault.com/a/1140509/357116 <=============
- - - - - 
Python `socket` example (see my link just above):
    ```python
    import socket

    # NB: SOCK_STREAM is used for TCP, and SOCK_DGRAM is used for UDP!
    # See: 
    # 1. What is SOCK_DGRAM and SOCK_STREAM?: 
    #   1. The most-upvoted answer: https://stackoverflow.com/a/10810040/4561887
    #   1. *****++[MY VERY-DETAILED ANSWER!] https://stackoverflow.com/a/71417876/4561887
    # 2. *****+ https://www.ibm.com/docs/en/aix/7.1?topic=protocols-socket-types
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    HOST = '192.168.0.1'
    PORT = 9999
    s.connect((HOST, PORT))
    s.settimeout(1)
    s.sendall("my command to send".encode())
    data = s.recv(4096)
    print('Received', repr(data))
    s.close()
    ```
- - - - - 
Equivalent netcat command to send and receive data as above:
    ```bash
    printf '%s' "my command to send" | timeout 0.2 nc 192.168.0.1 9999
    ```
    NB: do NOT use `echo` in place of `printf` above. See my Q&A here for detailed reasons: https://stackoverflow.com/questions/70001189/piping-echo-to-netcat-fails-while-piping-printf-passes

Netcat and socat
- `socat` is an alternative to netcat (`nc`). See:
    1. https://unix.stackexchange.com/a/457685/114401
    1. https://packages.debian.org/stretch/socat
- *****+ General netcat commands, how-to, examples, usage, tutorial: see my answer here: https://serverfault.com/a/1140509/357116 <=============

nc
    (From `man nc` or `man netcat`): "The nc (or netcat) utility is used for just about anything under the sun involving TCP, UDP, or UNIX-domain sockets."
netcat
    Same as above! `nc` is an alias to `netcat` apparently. `man nc` and `man netcat` are identical. 
nc -h
    netcat help menu
netcat -h
    netcat help menu
nc -u -l 127.0.0.1 30000
nc -lu 127.0.0.1 30000
nc -lu -s 127.0.0.1 -p 30000
    <======= VERY USEFUL NETCAT UDP SERVER LISTENING FOR DATA FROM CLIENT =========
    Set up a UDP (`-u`) listener (`-l`) to the loopback interface (IP `127.0.0.1`, AKA: LOCALHOST) on port (`-p`) 30000. 
    Note: I arbitrarily chose port 30000. 
    For a list of common TCP and UDP ports, see Wikipedia here: https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers.
    - See these commands above in my tutorial here: "General netcat (`nc`) usage instructions, including setting the IP address to bind to when receiving, or to send to when sending" - https://serverfault.com/a/1140509/357116
nc -u 127.0.0.1 30000
    <======= VERY USEFUL NETCAT UDP CLIENT SENDING TO SERVER =========
    Set up a UDP (`-u`) sender (the default, apparently) to the loopback interface (IP `127.0.0.1`, AKA: LOCALHOST) on port (`-p`) 30000. 
    Now, to send char data, just start typing, then press Enter! So long as you have a listener already open in another terminal (see just above), you'll see the output you send magically show up in the listener's terminal!
exit
    Type this to exit any open netcat session you are in!
nc -u 127.0.0.1 30000 < filename.bin
    <======= SEND A BINARY FILE OVER UDP VIA NETCAT! ========
    Send binary file `filename.bin` over UDP to IP address 127.0.0.1 on port 30000. 
    Source: `man netcat` and search for `nc -N host.example.com 1234 < filename.in`, which is where I first learned this format to send a file over netcat!
    NB: apparently this can also be done over UDP via raw bash commands too, withOUT netcat! See: https://linux-tips.com/t/sending-binary-data-to-a-tcp-or-udp-connection-in-bash/250
        Ex: `dd if=binary.dat bs=160 count=1 > /dev/udp/192.168.2.5/9000`
        > Please note that, there is no `/dev/tcp` or `/dev/udp` folder exists in the system, this redirection mechanism is a feature of the bash shell itself.
nc -w 1 -u 127.0.0.1 30000 < filename.bin
    <======= SEND A BINARY FILE OVER UDP VIA NETCAT! ========
    Same as above, except also with a timeout ('w'ait period) of 1 second, to return from netcat that amount of time after sending.

nc -lu 127.0.0.1 30000
    Listen for UDP packets being sent to virtual interface host IP address "localhost" (127.0.0.1), on port 30000. 
    See my full answer and tutorial here: https://serverfault.com/a/1140509/357116
nc -l 0 30000
    Listen for UDP packets being sent to IP address 0, or `INADDR_ANY`, which means "any interface host IP address". 
    See my full answer and tutorial here: https://serverfault.com/a/1140509/357116

---
WIP: ncat continual forwarding relay
---
while true; do ncat -l -u 5053 --sh-exec "ncat -u someserver.server.com 5053"; done
    UDP relay: listen on port 5053, and forward all incoming UDP packets to someserver.server.com on port 5053
while true; do ncat -l 5053 --sh-exec "ncat someserver.server.com 5053"; done
    TCP relay: listen on port 5053, and forward all incoming TCP packets to someserver.server.com on port 5053

socat udp:127.0.0.1:30000 - < filename.bin
    <========= SEND A BINARY FILE OVER UDP VIA SOCAT! ==========
    VERY SIMILAR TO NETCAT ABOVE, except perhaps more-reliable and consistent since apparently there are many netcat implementations but only one socat implementation maybe?
    See @A.B's comment & links here: https://unix.stackexchange.com/questions/706598/connection-refused-when-i-try-to-send-a-udp-packet-with-netcat-on-an-embedded#comment1337439_706598
socat -t 0.005 udp:127.0.0.1:30000 - < filename.bin
    Same as above, except with a **very short timeout** of only 0.005 sec to wait for any incoming message, so as to quickly close the connection so you can then send again.
socat -t 0 udp:127.0.0.1:30000 - < filename.bin
    <============ SEND A BINARY FILE OVER UDP VIA SOCAT! =============
    Same as above, except return **immediately** after sending! Do NOT wait for any response at all! (timeout of zero: `-t 0`)

printf '%s' 'my command msg' | timeout 0.2 nc 192.168.0.1 9999 
    Send the "my command msg" string via netcat to IP 192.168.0.1 on PORT 9999 via TCP over Ethernet with a timeout of 0.2 sec. 

---------
EXERCISES:
FOR MORE, SEE THE "Interactive examples" section of my answer here: https://serverfault.com/a/1140509/357116  <=============
 - Basic TCP/IP single listener (server), single sender (client) 
 - UDP single listener (server), multiple senders (clients)
---------

1. In one terminal, open up a UDP listener:

        nc -lu 127.0.0.1 30000      # UDP listener/server

1. In another terminal, open up a UDP sender:

        nc -u 127.0.0.1 30000       # UDP sender/client

1. In the sender's terminal, type "hello" and press Enter. You'll see it show up in the listener's terminal! 
1. In the receiver's terminal, type "world" and press Enter. You'll see it show up in the sender's terminal! Notice the communication is **2-way!** Either side can send now!
1. Type more data to send from either side, as desired. 
1. When done, type `exit` into each netcat terminal to exit `netcat`, OR press Ctrl + C to interrupt and kill each open `netcat`. 
The above works!
- - - - - 

GOING FURTHER:
(goal is to get multiple senders to be able to send to multiple listeners...is this even possible?)
    WORK-IN-PROGRESS/Need to research this more!:
    1. In a 3rd terminal, open up another **listener**, as shown above, and in a 4th terminal, open up another **sender**, as shown above.
    ...

Example of power supply control via string commands over Ethernet TCP using netcat:
[netcat power supply; power cycle; power cycling; power on; power off; power supply commands]
- This is similar to Serial UART-controlled devices, except the command and response strings are simply over Ethernet (either UDP or TCP) instead of over serial.
- Example Device: Teledyne LeCroy T3PS3000: https://www.digikey.com/en/products/detail/teledyne-lecroy/T3PS3000/9598577
    - For help, contact:
        Teledyne LeCroy Support
        support@teledynelecroy.com
        700 Chestnut Ridge Road
        Chestnut Ridge, NY 10977
        (800) 553-2769 Option 3
    - It's not in the manual, so I emailed them and they told me:
        > The T3PS3000 uses socket communication and the default port is 5025.
- Manual (Quick Start Guide): http://cdn.teledynelecroy.com/files/manuals/t3ps3000-quick-start-guide.pdf
    - p24, "Chapter 3 Remote Control" is where the command interface begins.
- NB: in all of the commands below, use `printf` as shown below. Do NOT use `echo`! `echo` appends a newline (`\n`) which can interfere with a device's ability to parse the data. It may work with `echo -n`, which suppresses the newline, but `echo` isn't the best way. `printf` is the best way. See my detailed Q&A on this here: https://stackoverflow.com/questions/70001189/piping-echo-to-netcat-fails-while-piping-printf-passes
- - - - - 
printf '%s' '*idn?' | timeout 0.2 nc 192.168.0.1 5025
    Query the identification, make, model, etc, of the device.
printf '%s' 'measure:voltage? ch1' | timeout 0.2 nc 192.168.0.1 5025
    Read the voltage (V) on channel 1
printf '%s' 'measure:current? ch1' | timeout 0.2 nc 192.168.0.1 5025  
    Read the current (A) on channel 1
printf '%s' 'measure:power? ch1' | timeout 0.2 nc 192.168.0.1 5025  
    Read the power (W) on channel 1
printf '%s' 'ch1:voltage 12' | timeout 0.2 nc 192.168.0.1 5025  
    Set the Ch1 voltage to 12V
printf '%s' 'ch1:current 0.5' | timeout 0.2 nc 192.168.0.1 5025  
    Set the Ch1 current to 0.5A
printf '%s' 'output ch1,off' | timeout 0.2 nc 192.168.0.1 5025  
    Turn channel 1 OFF
printf '%s' 'output ch1,on' | timeout 0.2 nc 192.168.0.1 5025  
    Turn channel 1 ON
printf '%s' 'system:error?' | timeout 0.2 nc 192.168.0.1 5025  
    Query/read the last error message
printf '%s' 'system:status?' | timeout 0.2 nc 192.168.0.1 5025  
    Query/read the current system status. See the manual description of this cmd and response on p31. The response will be in hex, where each bit means something special.
etc. etc. See the manual (Quick Start Guide) linked-to above for the full command sequence, which has about 2x as many commands as described above.
watch -n 0.5 'printf "%s" "measure:current? ch1" | timeout 0.2 nc 192.168.0.1 5025'
    Take a current reading of Ch1 every 0.5 sec.
trap 'printf "%s\n" "Ctr + C"; run="false";' SIGINT SIGTERM; \
run="true"; while [ "$run" = "true" ] ; do \
printf "%s" "measure:current? ch1" | timeout 0.2 nc 192.168.0.1 5025; \
sleep 0.5; done
    Similar to the above: take a reading every 0.5 sec! But, instead of showing the value in-place like `watch` does, overwriting the old value with each new value, **print them all to the screen**, scrolling down, instead, so you can manually average some values when done taking a bunch of readings!
    See also this answer about `trap` in Bash: https://serverfault.com/a/160961/357116
    <======= EXCELLENT! =======

Note: for other power supplies, such as the PowerUSB devices here (https://pwrusb.com/collections/all), do this instead. 
See: eRCaGuy_dotfiles/useful_scripts/power_supply_PowerUSB_Windows_cycle_power.sh
---
PwrUsbCmd="/c/Program Files (x86)/PowerUSB/PwrUsbCmd.exe"
"$PwrUsbCmd" 0 0 0  # outlet1 outlet2 outlet3  OFF
"$PwrUsbCmd" 1 1 1  # outlet1 outlet2 outlet3  ON

tcpdump resources:
1. Google search for "how to use tcpdump": https://www.google.com/search?q=how+to+use+tcpdump&oq=how+to+use+tcpdump&aqs=chrome..69i57j69i65.3038j0j7&sourceid=chrome&ie=UTF-8
1. *****+++ [MOST EXCELLENT TCPDUMP GETTING-STARTED TUTORIAL!] tcpdump tutorial and examples: https://opensource.com/article/18/10/introduction-tcpdump
    1. tcpdump man manual pages to describe packet format: https://www.tcpdump.org/manpages/tcpdump.1.html#lbAG
1. https://dzone.com/articles/tcpdump-learning-how-read-udp
1. *****https://danielmiessler.com/study/tcpdump/ - good source for a range of examples, but only AFTER you've thoroughly gone through the tutorial above first to learn the basics!
1. *****+ TCPDUMP & LIBPCAP [the main, official `tcpdump` and Libpcap website!]: https://www.tcpdump.org/
   "This is the home web site of tcpdump, a powerful command-line packet analyzer; and libpcap, a **portable C/C++ library for network traffic capture**."
   1. See some of the helpful community links and references right at the top of this file too! ex:
        1. *****+Tcpdump advanced filters: https://blog.wains.be/2007/2007-10-01-tcpdump-advanced-filters/
        1. *****++Tcpdump cheat sheet: https://packetlife.net/media/library/12/tcpdump.pdf

sudo tcpdump
    Appears to listen to *any* ethernet socket traffic.
    Use this command to read and print UDP and TCP Ethernet packets! This can be very useful to help you see if certain packets or messages are even coming in to your system!
    TODO: read also about "pcap" and "Wireshark" and how some sort of .pcap ("packet capture") definition files or something can help you interpret (I think) and parse incoming packets (in Wireshark, I think)! In other words, I'd like to be able to see binary values in Ethernet packets properly interpreted, automatically, as I look at incoming and outgoing packets in tcpdump or Wireshark.
sudo tcpdump --list-interfaces
sudo tcpdump -D
    <=========== LIST ALL INTERFACES AND THEIR STATUS! ==========
    List all interfaces which you can view traffic on. Very useful! Similar to `ifconfig`. 
    An "interface" is the main name you see when you run "ifconfig", `sudo tcpdump --list-interfaces`, or `sudo tcpdump -D`. It represents a physical OR virtual Ethernet card/plug in the side of your computer. 

    See section "2. Capturing packets with tcpdump" of this tutorial: *****+https://opensource.com/article/18/10/introduction-tcpdump
sudo tcpdump --interface any -c20 -nn
sudo tcpdump -i any -c20 -nn
    <=========== USEFUL TO GET STARTED SEEING SOME TRAFFIC ========
    Filter by **interface**. An "interface" is the main name you see when you run "ifconfig", `sudo tcpdump --list-interfaces`, or `sudo tcpdump -D`. It represents a physical OR virtual Ethernet card/plug in the side of your computer. 
    Capture ANYTHING in this case.
    On any interface (`--interface any`, or `-i any`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`), nor ports (`-nn`).
    See section "2. Capturing packets with tcpdump" of this tutorial: *****+https://opensource.com/article/18/10/introduction-tcpdump
    `man tcpdump` says this too:
            -n      Don't convert addresses (i.e., host addresses, port numbers, etc.) to names.
sudo tcpdump -i any -c20 -nn udp
    Filter by **protocol** (`icmp`, `udp`, `tcp`, etc).
    Same as above, but capture ONLY UDP packets! (`udp`).
    See "4. Filtering packets" --> "Protocol", here: https://opensource.com/article/18/10/introduction-tcpdump
    For more protocols, see this blog post under "Protocol filtering": https://blog.wains.be/2007/2007-10-01-tcpdump-advanced-filters/
        `arp`, `ip`, `tcp`, `udp`, `icmp`
    This cheat sheet shows more protocols still!: https://packetlife.net/media/library/12/tcpdump.pdf
sudo tcpdump -i any -c20 -nn host 127.0.0.1
    <========= FILTER BY `host`, WHICH IS THE IP OF THE SOURCE (`src`) OR DESTINATION (`dst`)! =========
    Filter by **host** (IP address). "Host" specifies an IP address which can be a "source (`src`) OR destination (`dst`)!
    On any interface (`-i any`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), and ONLY filtering on packets _to and from_ **host** (IP address) 127.0.0.1 (`host 127.0.0.1`), which is the local loopback interface for interprocess communication within the same computer.
    See "4. Filtering packets" --> "Host", here: https://opensource.com/article/18/10/introduction-tcpdump
    See also: tcpdump cheat sheet: https://packetlife.net/media/library/12/tcpdump.pdf
time sudo tcpdump host 192.168.1.1
    <========== HOST MATCHES AN IP AS DESINATION _OR_ SOURCE! ===========
    Match any traffic involving 192.168.1.1 as destination OR source!
    From: https://blog.wains.be/2007/2007-10-01-tcpdump-advanced-filters/
sudo tcpdump -i any -c20 -nn port 80
    Filter by **port** (ex: 22 for SSH; port numbers are 16-bits and hence range from 0 to 65535). See a list of common port numbers here: https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers
    On any interface (`-i any`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), and ONLY filtering on packets _to and from_ **port** 80 (`port 80`).
    See "4. Filtering packets" --> "Port", here: https://opensource.com/article/18/10/introduction-tcpdump
sudo tcpdump -i any -c20 -nn src 192.168.122.98
    Filter by **source IP address/hostname**.
    On any interface (`-i any`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), and ONLY filtering on packets _from_ source IP address 192.168.122.98 (`src 192.168.122.98`).
    See "4. Filtering packets" --> "Source IP/hostname", here: https://opensource.com/article/18/10/introduction-tcpdump
sudo tcpdump -i any -c20 -nn dst 192.168.122.98
    Filter by **destination IP address/hostname**.
    Same as above, except filter only on packets _to_ destination IP 192.168.122.98 (`dst 192.168.122.98`).
    See "4. Filtering packets" --> "Source IP/hostname", here: https://opensource.com/article/18/10/introduction-tcpdump
---
Complex expressions allow `and` and `or`. Use parenthesis, with the entire argument in quotation marks, for more-complex examples. Ex: 
sudo tcpdump -i any -c20 -nn "port 80 and (src 192.168.122.98 or src 54.204.39.132)"
    On any interface (`-i any`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), and ONLY filtering on packets _to and from_ port 80 (`port 80`) and from source IP 192.168.122.98 OR from source 54.205.39.132 ("and (src 192.168.122.98 or src 54.204.39.132)").
    See "4. Filtering packets" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
    See also this cheat sheet: https://packetlife.net/media/library/12/tcpdump.pdf
        It shows you can use: `! && ||` or `not and or`:
            `!` or `not`, `&&` or `and`, and `||` or `or`
---
sudo tcpdump -i any -c20 -nn src 192.168.122.98 and port 80
    Filter by **source IP address/hostname** AND **port**.
    On any interface (`-i any`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), and ONLY filtering on packets _from_ source IP address 192.168.122.98 (`src 192.168.122.98`) _and_ on port 80 (`and port 80`).
    See "4. Filtering packets" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
sudo tcpdump -i lo -c20 -nn "src 127.0.0.1 and port 50000"
    <========== GREAT DEMO! ==========
    Filter by **interface** AND **source IP address/hostname** AND **port**.
    On the local loopback interface (`-i lo`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), and ONLY filtering on packets _from_ source IP address 127.0.0.1 (the loopback address) AND on port 50000 (`and port 50000`).
    See "4. Filtering packets" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
sudo tcpdump -i lo -c20 -nn "src 127.0.0.1 and (port 50000 or port 50001)"
    <========== EVEN BETTER DEMO! =========
    Same as above, but on port 50000 OR port 50001.
    See "4. Filtering packets" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
time sudo tcpdump -i lo -c20 -nn "(src 127.0.0.1 and port 50000) and (dst 127.0.0.1 and port 50001)"
    <========== BEST DEMO SO FAR =============
    Filter by **interface**, **source IP and port**, and **destination IP and port**.
    On the local loopback interface (`-i lo`), capture 20 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), and ONLY filtering on packets _from_ source IP address and port 127.0.0.1:50000 which are _to_ destination IP address and port 127.0.0.1:50001. The `time` part times the process, to give you a feel for the packet **rate**, since you know the count is 20 packets. So, rate = 20/time = packets/sec.
    See "4. Filtering packets" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
time sudo tcpdump -i lo -c20 -nn -A "(src 127.0.0.1 and port 50000) and (dst 127.0.0.1 and port 50001)"
    <=========== ASCII OUTPUT ==========
    Same as above, but add `-A` to view the packet content ("minus its link level header") in ASCII output.
    See "5. Checking packet content" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
time sudo tcpdump -i lo -c20 -nn -X "(src 127.0.0.1 and port 50000) and (dst 127.0.0.1 and port 50001)"
    <=========== HEX + ASCII OUTPUT ==========
    Same as above, but add `-X` to **view the packet content** ("minus its link level header") in hex + ASCII output.
    See "5. Checking packet content" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
time sudo tcpdump -i lo -c20 -nn -X -w output.pcap "(src 127.0.0.1 and port 50000) and (dst 127.0.0.1 and port 50001)"
    <=========== SAVE TO A .PCAP BINARY FILE ========
    Same as above, but add `-w output.pcap` to write the captured packet info. to a "packet capture" .pcap file named "output.pcap".
    See "6. Saving captures to a file" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
-v
    Add `-v` or `-vv` for verbose or extra verbose, respectively, output.
    See "6. Saving captures to a file" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
time tcpdump -i lo -c20 -nn -X -r output.pcap "(src 127.0.0.1 and port 50000) and (dst 127.0.0.1 and port 50001)"
    <=========== READ FROM A .PCAP BINARY FILE ========
    Use `-r output.pcap` to read from the "output.pcap" binary "packet capture" file we just saved above, using these specified filters. 
    Note that `sudo` is NOT required in this case because we are reading from a user file rather than from the system network interfaces.
    NB: You can use filtering when reading from saved files the same as when reading directly from your network interfaces. 
    See "6. Saving captures to a file" --> "Complex expressions", here: https://opensource.com/article/18/10/introduction-tcpdump
time sudo tcpdump -i lo -c10 -nn -X "udp and (src 127.0.0.1 and port 50000) and (dst 127.0.0.1 and port 50001)"
    <================== MY FINAL ANSWER ===================
    On the local loopback interface (`-i lo`), capture 10 packets (`-c20`), NOT looking up their IP addresses (`-n`) nor ports (`-nn`), also printing the packet content in hex + ASCII (`-X`) (note: use lowercase `-x` for hex only), and ONLY filtering on udp packets (`udp`) which are _from_ source IP address and port 127.0.0.1:50000 and _to_ destination IP address and port 127.0.0.1:50001.
    See this **excellent** introductory tutorial to tcpdump to get started yourself: https://opensource.com/article/18/10/introduction-tcpdump
time sudo tcpdump -i lo -c10 -nn -X "udp and host 127.0.0.1 and (port 50000 or port 50001)"
    <============ EVEN SHORTER AND EASIER THAN ABOVE--SPECIFY HOST IP (SENDER OR RECEIVER) IN ONE =========
    Monitor traffic on the `lo` loopback interface (`-i lo`), capturing 10 packets (`-c10`), NOT looking up the packet IP addresses (`-n`) nor ports (`-nn`), displaying packet content in hex + ASCII (`-X`), for udp protocol packets (`udp`) with IP address 127.0.0.1 as sender _or_ receiver (`host 127.0.0.1`) and only for packets on port 50000 _or_ port 50001 (`and (port 50000 or port 50001)`).
    See this cheatsheet for help: *****+https://packetlife.net/media/library/12/tcpdump.pdf
    And: https://opensource.com/article/18/10/introduction-tcpdump


ethtool
    (From `man ethtool`): "query or control network driver and hardware settings". An alternative of some sort to `tcpdump`. 
    See `man ethtool`, and `ethtool --help` or `ethtool -h` for more info. I should also google about it and see what else it can offer!

ping 192.168.0.1
    Ping this IP address to see if it responds!
ping -c 1 -W 1 192.168.0.1
    <======== QUICK 1-SECOND PING AND EXIT =======
    Ping this IP address only 1 time, waiting and timing out after only 1 second.
```
trap 'printf "%s\n" "Ctr + C";' SIGINT; \
num=1; \
while ! ping -c 1 -W 1 "192.168.0.$num"; do \
    ((num++)); \
    if [ "$num" -ge 256 ]; then \
        echo "IP address is too large past this point. Exiting."; \
        break; \
    fi \
done
```
    <============ AUTOMATIC PING SCANNER ============
    Ping all IP addresses from 192.168.0.1 to 192.168.0.255, inclusive, trying 1 time and taking 1 second per ping, and stopping and exiting if either ANY IP address responds to the ping, OR if we hit address 192.168.0.256, which is not a valid IP Address.
    [ping loop; automatic ping; ping scanner; scan ping; scan for valid IP addresses; scan for IP addresses; search ping]


====================================================================================================
= D-Bus, sd-bus, gd-bus, ZeroMQ: =
====================================================================================================
[dbus, sdbus, gdbus, zmq, IPC (Inter-Process Communication) mechanisms, systemd]

References:
1. dbus
    1. https://en.wikipedia.org/wiki/D-Bus
    1. *****+ https://www.freedesktop.org/software/systemd/man/index.html - official reference index of all the functions!
        1. ***** dbus signature types: https://dbus.freedesktop.org/doc/dbus-specification.html#id-1.3.8
    1. https://0pointer.de/blog/projects/the-biggest-myths.html
    1. ***** blog by the author, incl. basic source code examples: http://0pointer.net/blog/the-new-sd-bus-api-of-systemd.html
1. gdbus
    1. `gdbus` CLI tool: https://www.freedesktop.org/software/gstreamer-sdk/data/docs/2012.5/gio/gdbus.html
1. systemd and sdbus
    1. ***** `busctl` CLI tool: https://www.freedesktop.org/software/systemd/man/busctl.html
1. zmq
    1. https://zeromq.org/


man gdbus
    view the manual pages
gdbus --help
    Oddly enough, this is **not a valid command**! So, it shows the `gdbus help` menu instead, which is exactly what we want :).
    View the `gdbus` help menu and list of commands.
gdbus help
    The **right** way to view the `gdbus` help menu and list of commands. Full output:
    ```
    Usage:
      gdbus COMMAND

    Commands:
      help         Shows this information
      introspect   Introspect a remote object
      monitor      Monitor a remote object
      call         Invoke a method on a remote object
      emit         Emit a signal
      wait         Wait for a bus name to appear

    Use “gdbus COMMAND --help” to get help on each command.
    ```
gdbus call --help
    See the help menu and options for the `gdbus call` command! Output:
    ```
    Usage:
      gdbus call [OPTION…]

    Invoke a method on a remote object.

    Connection Endpoint Options:
      -y, --system          Connect to the system bus
      -e, --session         Connect to the session bus
      -a, --address         Connect to given D-Bus address

    Application Options:
      -d, --dest            Destination name to invoke method on
      -o, --object-path     Object path to invoke method on
      -m, --method          Method and interface name
      -t, --timeout         Timeout in seconds
    ```

Example usages:

gdbus call --system --dest org.freedesktop.DBus --object-path /org/freedesktop/DBus --method org.freedesktop.DBus.ListNames | tr ',' '\n'
    ??? todo: add description
    - Note that piping the output to `tr ',' '\n'` replaces all commas (`,`) with newlines (`\n`) to make the output easier to look at.
    See: `gdbus call --help`
    See also: https://www.freedesktop.org/software/gstreamer-sdk/data/docs/2012.5/gio/gdbus.html
gdbus call -y -d com.whatever.something -o / -m com.whatever.something.MyFunction 1
    ??? todo: add better description
    Send a `1` to the `MyFunction` function at service?? com.whatever.something
    See: `gdbus call --help`
gdbus call --system --dest com.whatever.something --object-path / --method com.whatever.something.MyFunction 1
    <======
    Same as just above.
    See: `gdbus call --help`
busctl call com.whatever.something / com.whatever.something MyFunction b 1
    <============
    The systemd (`busctl`) version, meaning: exact same thing, as the `gdbus` call just above, assuming that the data being passed to the called method/function is a `b`oolean `1`. 
    Note: the `busctl` is nicer than `gdbus` because it allows you to specify the data signature (`b` in this case). 
    See: 
    1. `busctl --help`
    1. D-Bus summary of types (ex: `b` is bool): https://dbus.freedesktop.org/doc/dbus-specification.html#id-1.3.8
    1. https://www.freedesktop.org/software/systemd/man/busctl.html
busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
    <============
    An official example from FreeDesktop.org. They describe it as:
    """
    The [above] command invokes the "StartUnit" method on the "org.freedesktop.systemd1.Manager" interface of the "/org/freedesktop/systemd1" object of the "org.freedesktop.systemd1" service, and passes it two strings "cups.service" and "replace". As a result of the method call, a single object path parameter is received and shown:
    """
        ```
        # response:
        o "/org/freedesktop/systemd1/job/42684"
        ```
    Note that the `ss` signature specifies that two strings will follow as arguments to the `StartUnit` method. The two strings in this case are "cups.service", and "replace". 
    See: 
    1. *****https://www.freedesktop.org/software/systemd/man/busctl.html
    1. D-Bus summary of types (ex: `b` is bool, `s` is string): https://dbus.freedesktop.org/doc/dbus-specification.html#id-1.3.8


====================================================================================================
= Symlink Utilities: =
====================================================================================================
[keywords: fixing broken symlinks; fix broken symlinks; = symlinks: =; = symlink: =]

References:
1. Google search for "bash script to fix broken symlinks":
   https://www.google.com/search?q=bash+script+to+fix+broken+symlinks&oq=bash+script+to+fix+broken+symlinks&aqs=chrome..69i57.5764j0j9&sourceid=chrome&ie=UTF-8
1. https://www.makeuseof.com/basic-commands-linux/
1. https://techbit.ca/2021/01/fixing-broken-symlinks-with-find-and-replace/
1. Repair broken symlinks to new location - https://unix.stackexchange.com/q/578671/114401
1. *****How can I "relink" a lot of broken symlinks? - https://unix.stackexchange.com/a/18365/114401
    1. *****+ [my answer, presenting my `fix_broken_symlinks` tool] https://unix.stackexchange.com/a/732315/114401


ln -sir path/to/some/file/or/dir .
    <==========
    Create a symlink to that location in the current directory.
ln -i path/to/some/file/or/dir .
    <==========
    Create a **hard** link to that location in the current directory.
    Read about hard links here: https://www.cbtnuggets.com/blog/certifications/open-source/linux-hard-links-versus-soft-links-explained

[keywords: check verify hard links; hard link inodes; how to tell if files are hard links to the same underlying inode file storage]

ls -li path/to/file/or/dir
    See the inode ('i'node) of the file. Hard links have the same inode as each other. The inode is what points to the underlying memory storage (on the disk) for the file.
    Source: Bing Chat: prompt: "In linux, how do I tell at the command line if a link is a symlink or hard link?"
ll -i path/to/file/or/dir
    <==========
    Similar to above.
    Source: Bing Chat: prompt: "In linux, how do I tell at the command line if a link is a symlink or hard link?"
stat path/to/file/or/dir
    <==========
    Stat the file (ask for its 'stat'us). This will also show the inode number and the number of hard "Links" to this inode number. A "Links" value > 1 indicates it is a shared hard link, and more hard link files point to this same inode number too.
    Source: Bing Chat: prompt: "In linux, how do I tell at the command line if a link is a symlink or hard link?"

- - -
NB: 
1. Use `-v` for verbose output, to show the new symlinks and where they point. VERY USEFUL FOR DEBUGGING!
1. Also, when fixing up symlinks to **directories**, you *must* either `rm` the symlink first, _or_ use the `-n` option to (from `man ln`): "treat LINK_NAME as a normal file if it is a symbolic link to a directory", in order to edit or replace the actual symlink to the dir rather than creating a _new_ symlink _inside_ that dir! So, use `-n` too! See my comments and our discussion here: https://unix.stackexchange.com/questions/18360/how-can-i-relink-a-lot-of-broken-symlinks/732315#comment1389743_18365
- - -
ln -svn target_path symlink_path
    Make a symlink at "symlink_path" which links to (points to) "target_path". 
ln -svni target_path symlink_path
    Interactively do the above: in case the "symlink_path" already exists, it will prompt you to ask if you'd like to overwrite it.
ln -svnf target_path symlink_path
    CAUTION: force-create the symlink, overwriting "symlink_path" with this new symlink even if it already exists. 
ln -svnr target_path symlink_path
    <=========
    Make a **relative** symlink (forcing it to be relative even if you use an absolute "target_path") at "symlink_path" which links to (points to) "target_path".
ln -svnri target_path symlink_path
    <======== BEST WAY TO CREATE A NEW SYMLINK! ========
    Same as above, but do it interactively to ask if you'd like to overwrite.
    NB: **All** of these options are important, and what I want. See 'man ln' for what each does. See also my notes about some of them, above.
ln -svnrf target_path symlink_path
    CAUTION: same as above, but force-overwrite "symlink_path" without prompting you if it already exists.
    Good for scripting.
- - -
Putting it all together, from below: if creating your own utility to manipulate symlinks, use `find . -type l` to find all symlinks, or `find . -xtype l` to find all *broken* symlinks. Use `readlink path/to/symlink` to read the path a symlink points to. Use `sed` to search and replace within that if desired. And use `ln -svnrf target_path symlink_path` if scripting the automatic replacement of an absolute symlink with a relative symlink (where, of course, "target_path" could be read via `readlink`). 
- - -
TARGET_PATH="$(readlink symlink_path)"; ln -svnrf "$TARGET_PATH" symlink_path
    Convert the symlink at "symlink_path" from an absolute to a relative symlink!
    When done, confirm it worked with `ll symlink_path`.
SYMLINK_PATH="path/to/symlink"; TARGET_PATH="$(readlink "$SYMLINK_PATH")"; ln -svnrf "$TARGET_PATH" "$SYMLINK_PATH"
    <=========== VERY USEFUL! ============
    Slightly cleaner way to do the above: convert an existing, non-broken, symlink at "symlink_path" from an absolute to a relative symlink!
    When done, confirm it worked with `ll "$SYMLINK_PATH"`.
    - Note: the above is akin to `symlinks -rsvc` (SEE BELOW; CAUTION: modifies disk), except more granular, since `symlinks` changes ALL symlinks, recursively, whereas the one-liner above can be made to just change just **one** single symlink at once!
    - [keywords: convert absolute to relative symlink; convert absolute symlink to relative symlink; convert an absolute symlink to a relative symlink; symlinks absolute to relative; symlink absolute to relative; absolute to relative symlink; symlink absolute relative symlink; symlink relative absolute symlink]

unlink path/to/symlink
    Delete the symlink; same as `rm path/to/symlink`.
    See also: What is the difference between 'rm' and 'unlink'? - https://unix.stackexchange.com/q/151951/114401
rm path/to/symlink
    Pretty much the same as above, except more obvious to the world what it's really doing.
    See also: What is the difference between 'rm' and 'unlink'? - https://unix.stackexchange.com/q/151951/114401

---
See also my answer here!: Unix & Linux: All about symlinks: creating, listing, converting from absolute to relative, etc. - https://unix.stackexchange.com/a/774298/114401 <====
---
sudo add-apt-repository universe && sudo apt update && sudo apt install symlinks
    Install the `symlinks` utility in Ubuntu. 
    See: https://www.makeuseof.com/how-to-find-and-fix-broken-symlinks-in-linux/
man symlinks
    <=========
    See the manual pages for this really useful utility!
symlinks -h
    See the short help menu for this really useful utility.
symlinks .
    Show all **non**-relative symlinks in the current directory only, **not** recursing down into sub-dirs. 
symlinks -v .
    Show all symlinks, including relative symlinks (via `-v` for verbose) in the current directory only, **not** recursing down into sub-dirs. 
symlinks -rv .
    Show all symlinks, including relative symlinks (via `-v` for verbose) in the current directory, recursing down into sub-dirs too! (via `-r`). 
symlinks -rsv .
    <=========== BEST CMD TO VIEW ALL SYMLINKS & THEIR STATUS ============
    Show all symlinks, including relative ones (`-v`), recursively (`-r`), and finding "lengthy" links too (`-s`; see `man symlinks`).
symlinks -rsv . | grep '^dangling'
    <====== FIND BROKEN SYMLINKS ========
    Find only "dangling", or broken, symlinks. 
    Note: `find . -xtype l` can also do this. Prove it like this and you will see the same number of broken symlinks:
    ```bash
    symlinks -rsv . | grep '^dangling' | wc -l
    find . -xtype l | wc -l
    ```
    [find all broken symlinks; find all dangling symlinks]
symlinks -rsvt . 
    <==============
    Same as `symlinks -rsv`, but also `t`est which symlinks would be converted from absolute to relative, or otherwise fixed if they are "lengthy" or "messy". It is a "dry run" of running with `-c`, but without actually making any changes. 
symlinks -rsvt . | grep '^changed'
    <==============
    See just which links would be "changed" if you ran with `-c`. 
symlinks -rsvc .
    <==============
    CAUTION!: THIS ACTUALLY CHANGES SYMLINKS ON YOUR SYSTEM! 
    Convert all "absolute" symlinks to "relative", and reduce/clean up any "messy" or "lengthy" symlinks as well. 
    Note: this can NOT fix broken or "dangling" symlinks. That requires manual intervention from a human.

fix_broken_symlinks path/to/dir
    find all broken symlinks in this dir
    See: 
    1. My answer: https://unix.stackexchange.com/a/732315/114401
    1. My source code for this tool: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/blob/master/useful_scripts/fix_broken_symlinks.sh
fix_broken_symlinks path/to/dir find_regex replacement_str
    dry-run fix all broken symlinks in this dir
    See: 
    1. My answer: https://unix.stackexchange.com/a/732315/114401
    1. My source code for this tool: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/blob/master/useful_scripts/fix_broken_symlinks.sh
fix_broken_symlinks path/to/dir find_regex replacement_str -f
    actually fix all broken symlinks in this dir (passing `-f` to force it)
    See: 
    1. My answer: https://unix.stackexchange.com/a/732315/114401
    1. My source code for this tool: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/blob/master/useful_scripts/fix_broken_symlinks.sh

ll
    Alias for `ls -alF`: show all files, including symlinks and where they point.
ls -alF
    Same as above. 
ll -R
    Also recurse into all subdirs. 
ll -R | grep -- '->'
    A bit of a cheesy way to just show symlinks, recursively.
    A better way would be `find . -type l` or `symlinks -rsv .`
ll path/to/symlink
    <==========
    See where the symlink points. 
    NB: use `readlink path/to/symlink` to **only** get the path where the symlink points!
ls -alF path/to/symlink
    Same as above, in case the `ll` alias doesn't exist on your system.
alias ll='ls -alF'
    Create the `ll` alias for your system, in case it doesn't exist. 
    Place this in your `~/.bashrc` file to make this alias "permanent"/persistent across reboots. 

find . -type l
    Find all symlinks. 
symlinks -rsv .
    Find all symlinks. See above for more details. 
find . -xtype l
    <==========
    Find all **broken** ("dangling") symlinks only (like `symlinks -rsv .`, but less verbose/detailed in the output since `find` does *not* show where the symlink points).
    [find all broken symlinks; find all dangling symlinks]
symlinks -rsv .
    Find all symlinks, including **broken** ("dangling") symlinks.

readlink path/to/symlink
    <======= VERY USEFUL FOR SCRIPTING =======
    Read the target path that the symlink points to. No output if the path passed to it is not to a symlink. 
    Related utility: `realpath`. 
realpath some_file_or_symlink
    <======= VERY USEFUL! ========
    Obtain the full, resolved path (absolute path) of some_file_or_symlink. If it is a symlink, this walks the path all the way down to the actual path. 
    Search this doc for other usages of this too.


====================================================================================================
= Docker: =
====================================================================================================

Docker is some kind of light-weight virtual machine/containerization environment. 

From ChatGPT on 17 Jan. 2023:

Me:
What is docker?

ChatGPT:
Docker is a platform that allows developers to easily deploy, run, and manage applications in a containerized environment. Containers are a lightweight form of virtualization that enable applications to be packaged with their dependencies and run consistently across different environments. Docker provides a command-line interface and API for interacting with containers, as well as a centralized hub for sharing and discovering container images. This makes it easier for developers to build, test, and deploy applications quickly and consistently.

References:
1. `man docker`
1. [NEED TO GO THROUGH THIS TUTORIAL!] ***** Official getting started documentation: https://docs.docker.com/get-started/
    What is a container?

    > Simply put, a container is a sandboxed process on your machine that is isolated from all other processes on the host machine.

    > To summarize, a container:
    > 
    > - is a runnable instance of an image. You can create, start, stop, move, or delete a container using the DockerAPI or CLI.
    > - can be run on local machines, virtual machines or deployed to the cloud.
    > - is portable (can be run on any OS).
    > - is isolated from other containers and runs its own software, binaries, and configurations.


    > What is a container image?
    > 
    > When running a container, it uses an isolated filesystem. This custom filesystem is provided by a container image. Since the image contains the container’s filesystem, it must contain everything needed to run an application - all dependencies, configurations, scripts, binaries, etc. The image also contains other configuration for the container, such as environment variables, a default command to run, and other metadata.

    Note: Docker is more than just `chroot`.
1. 


docker container ls
    List running docker containers. 
    Sample run and output--notice the container name as the end!: `my-container-name`
    ```bash
    $ docker container ls
    CONTAINER ID   IMAGE                                                           COMMAND                  CREATED      STATUS      PORTS     NAMES
    0183871ab108   whatever.com/something/whatever/my-container-name:latest        "fixuid -q watch -n …"   6 days ago   Up 6 days             my-container-name
    ```
    See: 
    1. `docker container --help`
    1. `docker container ls --help`
    1. `man docker container`
docker ps
    Same exact thing as `docker container ls`. 
    See `docker --help`
docker container --help
    See help menu.
man docker container
    See manual pages.
docker exec --help
    See help menu.
docker exec -it <container_name_or_id> /bin/bash
    Open a shell in the given docker container. The docker container's name can be found in the far right-hand column of the output from `docker container ls` or `docker ps` (see above).
    From `docker exec --help`: `-i` is `--interactive`, to "keep STDIN open even if not attached", and `-t` is `--tty`, to "allocate a pseudo-TTY", making it an interactive terminal you can type in. Running `/bin/bash` gives you access to the docker container's bash shell environment for live interaction! 
    See: 
    1. `docker exec --help`
    1. https://docs.docker.com/engine/reference/commandline/exec/
docker exec -it my-container-name /bin/bash
    <=========
    Open the docker container named "my-container-name" in interactive mode in a bash shell terminal.
    See just above for details. 
    Find the name in the far **right** column of the output of `docker container ls` or `docker ps`. 
docker exec -it 0183871ab108 /bin/bash
    <=========
    Exact same thing as above, except using the container's ID instead of its name.
    Find the Container ID in the far **left** column of the output of `docker container ls` or `docker ps`. 
exit
    Leave the docker container shell--just like exiting any shell or terminal.
dexec [--help]
    Some sort of tool to run stuff in a docker container or something. 
    See: https://github.com/docker-exec/dexec


====================================================================================================
= Partitions and File Systems: =
====================================================================================================
[keywords: = partitions: =; = file systems: =]

References:
1. Shrinking encrypted partitions: [my answer] How to install & use `blivet-gui` on an Ubuntu live USB so we can use `blivet-gui`, Gnome Disks, and GParted (all 3 are required together) to shrink an encrypted LUKS partition: https://unix.stackexchange.com/a/728750/114401
1. Expanding encrypted partitions: [my answer] How to clone your hard drive (SSD or HDD) and expand your LUKS-encrypted partition to fill the new full disk space: https://unix.stackexchange.com/a/674828/114401
1. [my article] https://www.electricrcaircraftguy.com/2018/01/how-to-clone-your-hard-drive.html
1. Ask Ubuntu: How do I find out what filesystem my partitions are using?: https://askubuntu.com/q/309047/327339
1. ***** [my Q&A] How do I find out which partitions my filesystems (and mount points) are on, and how full the partitions are?: https://unix.stackexchange.com/a/733887/114401


gparted
    Open the GUI parted partition editor
blivet-gui
    Open this GUI
gnome-disks
    Open this GUI

parted -l
    List partitions

df -h
    <=====
    List disk usage and filesystem mount points (but not partitions :()
    See my Q&A: https://unix.stackexchange.com/a/733887/114401
sudo fdisk -l
    <=====
    List all partitions and their sizes, but *not* their filesystem mount points/paths.
    See my Q&A: https://unix.stackexchange.com/a/733887/114401
sudo fdisk -l /dev/mmcblk0p3
    List the info. for just this one partition at `/dev/mmcblk0p3`.
cat /etc/fstab
    See your filesystem (fs) table (tab), which is the config file to define how and where to mount all of your filesystems and partitions.
lsblk  
    <== VERY USEFUL ===
    See which partition your filesystems are on, and how big they are.
    See my Q&A: https://unix.stackexchange.com/a/733887/114401
mountpoint -n /  
    <=====
    (Works on BusyBox only) See the **name** of the partition which contains the root mountpoint (`/`). 
    See my Q&A: https://unix.stackexchange.com/a/733887/114401
---
Note that the %usage of a given partition can be calculated by: (filesystem usage as shown by `df -h` + 
other partition usage as shown by `lsblk`) / (total partition size as shown by `lsblk`).
See my Q&A: https://unix.stackexchange.com/a/733887/114401
---
blkid
    See more "block device attributes", including the UUID of each partition!
    See `man blkid`. 
    See my Q&A: https://unix.stackexchange.com/a/733887/114401


====================================================================================================
= Linux (General): =
====================================================================================================
[general linux cmds; general linux commands; linux general, linux =, linux: =]

Linux Terminal shortcuts: https://www.howtogeek.com/howto/ubuntu/keyboard-shortcuts-for-bash-command-shell-for-ubuntu-debian-suse-redhat-linux-etc/
Ex:
    Ctrl + A = go to beginning
    Home = same as above
    Ctrl + E = go to end
    End = same as above
    Ctrl + L = clear screen (same as typing `clear` command)
    reset = reset the terminal back to its default state (useful in case it's corrupted and you can't even see what you're typing, for instance)
    . ~/.bashrc = re-source your bash startup file (~/.bashrc), which also automatically re-sources your bash aliases file (~/.bash_aliases), if it exists. Doing this resets all environment variables, terminal prompt string, terminal text colors, custom aliases or bash functions included in either of those two files, etc.

== Linux terminal options: ==
gnome-terminal = Ubuntu's default terminal
tmux = [see "= tmux: = " section in this doc] terminal session manager
screen = [GNU screen] terminal session manager
terminator = *****a terminal program to EASILY allow 4 terminals (2x2) or even 16 terminals (4x4) all in one single window! Great for running ROS, for instance, since it requires so many stinking terminals open!
 - See here, **including my comments under the answer!**
   https://askubuntu.com/questions/612131/how-to-display-more-than-1-terminal-simultaneously/612139#612139
 - See also: [eRCaGuy_dotfiles/useful_apps/README.md](useful_apps/README.md)


== ==

stty cols 80
    Set the terminal width to 80 columns. 
    From my prompt to GitHub Copilot: 
        > set the width of my terminal to 80 chars
env
    Display the current "environment", including all shell environment variables and what they are currently set to!
    Note: this is the same executable called for running script when you do a hashbang of `#!/usr/bin/env bash` at the top of your bash sript!
    See: https://www.ibm.com/docs/en/aix/7.2?topic=e-env-command

bash -x some command
    <====== VERY USEFUL FOR DEBUGGING BASH SCRIPTS! =======
    From `man bash`: "-x  Print commands and their arguments as they are executed."
    Also works with `sh`. Ex: `sh -x some command`. 

ls -d -1 ../some-random-name-*
    Find and list (`ls`) all directories (`-d`) in one single new-line-delimited column (`-1`) which are one directory up (`../`) and named `some-random-name-*`, where the asterisk (`*`) is a bash shell "glob" character. 
    This is REALLY USEFUL to integrate into a meson.build file, for instance, when working with Buildroot or some other build system and you need to do a wildcard search or match to find a certain directory, file, files, headers, etc. of interest to bring in to the build system or include somehow!
    See also Meson's Q&A titled "But I really want to use wildcards!" here: 
    https://github.com/mesonbuild/meson/blob/master/docs/markdown/FAQ.md#but-i-really-want-to-use-wildcards

lsof
    List all open files and see which command and process PID has them open!
    See: https://www.tecmint.com/find-out-who-is-using-a-file-in-linux/
lsof /dev/null
    See only this one open file (`/dev/null` in this case) and see which processes and PIDs have it open.
    See: https://www.tecmint.com/find-out-who-is-using-a-file-in-linux/

uptime
    show how long the computer has been on (since last reboot), how many users are currently logged-in, etc.
who
    show who is currently logged-in 
    [keywords: who is logged in, linux who is logged in, linux open ssh sessions, linux ssh users logged in, linux open login sessions, linux open sessions of users logged-in, linux users logged in, linux sessions, linux users currently logged in]
w
    "Show who is logged on and what they are doing"; great command to ensure you're the only one remotely logged on to a PC, for instance!
whoami
    print your username (helps verify you are logged in under the correct user)
sudo whoami
    print your sudo username; it should say "root" since you ran it as `sudo`! This helps verify you have `sudo` access!--ie: that you are a member of the "sudo" group (run `groups` to check), and in the sudoers file (run `sudo visudo`--you should have an entry for your username at the bottom).

df -h
    show 'd'isk 'f'ile usage to see how much hard drive/SSD space you have total, used, and remaining
free -h
    look at RAM and swap file/swap partition usage [memory free, ram free, swap free] in "ibytes" (base 1024) form--ex: GiB = Gibibytes
free -h --si
    Show free RAM and swap in human-readable base 1024 form--ex: GB = Gigabytes
    See: https://askubuntu.com/a/898942/327339
    - esp. see the comments under this answer--including my own comment!
swapon --show
    show which swap files or partitions are in use; see my own answer here!: https://askubuntu.com/questions/927854/how-do-i-increase-the-size-of-swapfile-without-removing-it-in-the-terminal/1177620#1177620; you can also do:
cat /proc/meminfo | grep -B 1000 -A 1000 -i swap
    examine the "/proc/meminfo" file for entries named "swap", such as the "SwapTotal" line; see my own answer linked-to just above!
du -h
    see file space usage of every item (file? and folder) in your current directory; NB: just look at the very last line to see the total usage of your current directory!
du -h | tail -n 1
    same as above, except retain ONLY the *last line* so that you can immediately see the total usage of this directory! Sample output:
        100G .
du -sh
    same as above! The `-s` says to 's'ummarize, which means to just output the last line! The output is **exactly identical** to what you get with `du -h | tail -n 1`.
du -h | tail -n 1 | awk '{print $1}'
    same as the line just above, except also retain ONLY the *first column* so that you get rid of the extra dot (.) at the end which indicates "current directory". Sample output:
        100G
    See here for `awk` usage help which enabled me to retain only the 1st column above: https://stackoverflow.com/questions/7315587/bash-shortest-way-to-get-n-th-column-of-output/43284174#43284174

---
[keywords: find and sort files greater than a certain size; find and sort files by name]
Main references: 
1. My answer: [Unix & Linux: All about finding, filtering, and sorting with `find`, based on file size](https://unix.stackexchange.com/a/731663/114401) - see the example near the end, titled **"(Figure out which file extensions to add to `git lfs` next)"**.
- NB: in the examples below, instead of using `find` with `-printf '%s\t%p\n'` to output size information, you could use `du` instead. I haven't gone down that path to get the right options and formatting I'd want, however, like I have done with `find`, so the `find` commands are good enough for now. 
---
find . -type f -size +100k -printf '%s\t%p\n' | awk '{printf("%13.6f kiB ", $1/(1024)); for (i=2; i<NF; i++) printf("%s ", $i); printf("%s\n", $NF)}' | sort -rn -k 1
    <==== SORT BY SIZE ======
    List all files > 100 kiB (`+100k`), and sorted in reverse order (largest first) by their size (`sort -rn -k 1`). 
    Source: ChatGPT helped me figure a lot of this out, especially getting me started on the `awk` stuff!
    See also my answer: https://unix.stackexchange.com/a/731663/114401
find . -type f -size +100k -printf '%s\t%p\n' | awk '{printf("%13.6f kiB ", $1/(1024)); for (i=2; i<NF; i++) printf("%s ", $i); printf("%s\n", $NF)}' | sort -k 3 --ignore-case
    <==== SORT BY NAME ======
    List all files > 100 kiB (`+100k`), and sorted alphabetically by the 3rd column (`-k 3`), which is the name, ignoring case in order to sort case-insensitive (`sort -k 3 --ignore-case`).
    Limitation: as it is currently written, this is only sorting by the first portion of the name up until the first space within the name, if there is one. 
    Source: ChatGPT helped me figure a lot of this out, especially getting me started on the `awk` stuff!
    See also my answer: https://unix.stackexchange.com/a/731663/114401
find . -type f -size +100k -printf '%s\t%p\n' | awk '{printf("%13.6f kiB ", $1/(1024)); printf("\""); for (i=2; i<NF; i++) printf("%s ", $i); printf("%s\"\n", $NF)}' | sort -k 3 --ignore-case
    Same as just above, except putting double quotes around the entire path, which may be helpful if there are spaces in the path and you need to use the output in a script?
    Limitation: as it is currently written, this is only sorting by the first portion of the name up until the first space within the name, if there is one. 
    See also my answer: https://unix.stackexchange.com/a/731663/114401
find . -type f -size +100k -printf '%s\t%p\n' | awk '{printf("%13.6f kiB ", $1/(1024)); for (i=2; i<NF; i++) printf("%s ", $i); printf("%s\n", $NF)}' | sort -rn -k 1 | grep -v '.*\.pdf$'
    <==== SORT BY SIZE, showing only NON-PDF files ======
    Same as the "SORT BY NAME" one a couple examples above, except then pipe to `grep -v '.*\.pdf$'` to exclude all files ending in .pdf, so that I can figure out which *NON*-PDF files are > 100 kiB in size!
    See also my answer: https://unix.stackexchange.com/a/731663/114401

find . -type f | awk 'length($0) > 200'
    Find long paths > 200 chars. Ex: to find paths too long for Windows's 256 char or so file path limit!
    Source: Microsoft Copilot (was Bing Chat): https://sl.bing.net/hzNxvgWMluS

chown
    Change the owner of files and directories. 

chmod
    'Ch'ange the file permissions "mode" ('mod'e) for files and directories. Examples:
chmod -R 700 ~/.ssh
    'R'ecursively set mode 700 (`u+rwx,g-rwx,o-rwx`--see: https://en.wikipedia.org/wiki/Chmod#Command_line_examples) for the directory ~/.ssh and all files and folders recursively within it.
chmod 600 ~/.ssh/*
    Set mode 600 (`u+rw,g-rwx,o-rwx`) for all files and directories (`/*`) directly within (but NOT recursively in sub-directories within) in the dir "~/.ssh/".
chmod -R a-x+X my_dir
    For 'a'll users (user, group, other), recursively (`-R`) remove e'x'ecutable privileges on EVERYTHING (all files and directories), then put it back (`+X`) for all **directories** only, so that these dirs can be opened and browsed!
    - See: https://superuser.com/questions/454795/how-can-i-do-a-recursive-chmod-only-on-directories/454807#454807
    <====== VERY USEFUL TO KNOW ABOUT +/-X! ==========
chmod -R 700 ~/.ssh && chmod -R u-x+X ~/.ssh
    Recusively (`-R`) set mode 700 (`u+rwx,g-rwx,o-rwx`) for all files and folders in ~/.ssh, then recursively remove e'x'ecutable privileges on all files and folders (`-R u-x`), recursively adding back executable privileges only on dirs (`-R u+X`), so they can be opened/navigated.
chmod -R u+rw,g-rwx,o-rwx ~/.ssh
    A much cleaner way to do the above! Recursively (`-R`) turn off ALL privileges for 'g'roup and 'o'ther users, while ensuring the owner ('u'ser) recursively has 'r'ead and 'w'rite privileges on all files and folders within ~/.ssh.
    <====== BEST! =======
chmod -R u-x+rwX,g-rwx,o-rwx ~/.ssh
    A slightly-altered version of the above to remove e'x'ecutable privileges on all files and directories (`-x`) within ~/.ssh, while then adding them back for all directories (`+X`), to fix things in the event you accidentally previously added `+x` to all files, but didn't mean to.
    <====== GOOD! MAY BE NEEDED TO FIX THINGS! ======
chmod 700 ~/.ssh
    Ensure only the 'u'ser (owner) can read, write, or execute (open/navigate to) the ~/.ssh dir. 
    <====== THIS IS A GOOD IDEA FOR SECURITY! ======
chmod 777 some_file_or_dir
    Set the mode on some_file_or_dir to 777 (`u+rwx,g+rwx,o+rwx`), which means FULL PRIVILEGES for all! Note: watch out! This is _very rarely desired_, for security reasons, as it gives all privileges to all users to this file or dir. 

[Linux bash shell debugging; bash debugging; bash debug prints]
set -x
    Turn on a type of "shell debugging" to "print commands and their arguments as they are executed." See `help set | less`. 
    See also the `set -x` examples used by @eaglemc here in this issue on my repo here: https://github.com/ElectricRCAircraftGuy/PDF2SearchablePDF/issues/9. 
set +x
    Turn OFF the `set -x` "print everything executed in the shell" type debugging!

[bash script path, bash full path, bash full dir path, bash full directory path, bash directory path, bash filename, bash basename, bash dirname]
[FOR A FULL EXAMPLE OF THE BELOW 3 CMDS, SEE MY ANSWER HERE: <=========
https://stackoverflow.com/questions/59895/how-to-get-the-source-directory-of-a-bash-script-from-within-the-script-itself/60157372#60157372]

realpath some_file_or_symlink
    <========= VERY USEFUL! vvv^^^ ========
    Obtain the full, resolved path (absolute path) of some_file_or_symlink. If it is a symlink, this walks the path all the way down to the actual path. 
dirname $(realpath some_file_or_symlink)
    Obtain the full **directory** path of the path above.
basename $(realpath some_file_or_symlink)
    Obtain the base **filename** of the path above.

lscpu
    <===========
    List information about your CPU and cores, whether your CPU is 32 or 64-bit, how many CPUs you have, how many threads per core you have, your system's **endianness**, which processor (Pentium i3, i5, i7, i9, etc.), CPU processor speed, etc. 
    From `man lscpu`: "display information about the CPU architecture"
    [how many cores you have: see the "CPU(s):" line near the top! Or, just run `nproc`! (see below); number of threads; how many threads you have; hyperthreads]
lscpu | grep "Byte Order"
    View your system's byte order or endianness! Ex: "Big Endian" [most-significant byte first] or "Little Endian" [least-significant byte first].
nproc
    <===========
    See the number of cores/hyperthreads you have! Ex: on a 16-core laptop, you'll see `16`. 
    I first learned about this tool from the `ydotool` build instructions here: https://github.com/ReimuNotMoe/ydotool#build

uname
    Print system information
uname -r
    Print the kernel release version
uname --kernel-release
    Same as above

shred
    Better than `rm`! It's more secure. See `man shred`: "overwrite a file to hide its contents, and optionally delete it."
shred -v --iterations=1 path/to/some_file
    <====== BEST USAGE ======
    Overwrite "some_file" with random data to "shred" it one time, showing verbose output. 
    NB: I read somewhere that on modern SSD's, shredding only **1 time** is recommended, NOT more than that (hene the `--iterations=1` option!), as more than that unnecessarily wears down your flash memory with NO extra security benefit since data gets scrambled all the time on SSD's anyway as a result of wear-leveling. 
    See where I first saw this cmd: https://www.cyberciti.biz/hardware/cryptsetup-add-enable-luks-disk-encryption-keyfile-linux/

fzf:
cat "path/to/eRCaGuy_dotfiles/git & Linux cmds, help, tips & tricks - Gabriel.txt" | fzf -m --reverse
    [GOOD] Fuzzy search this file withOUT showing line numbers.
    See my comment: https://github.com/junegunn/fzf/issues/1034#issuecomment-1054558594
grep -n '' "path/to/eRCaGuy_dotfiles/git & Linux cmds, help, tips & tricks - Gabriel.txt" | fzf -m --reverse
    [BETTER] Fuzzy search this file WITH showing line numbers!
    See my comment: https://github.com/junegunn/fzf/issues/1034#issuecomment-1054558594

date
    Print the current date and time. 
    Ex. output: `Sun Mar  6 08:17:15 MST 2022`
date --help
    Help menu for `date` cmd
man date
    man pages for `date` cmd
date +"%a %b %-d %H:%M:%S %Y %z"
    <======= `git log` output format =======
    Produce the current date, time, and timezone in the **exact same format** as what you see in the timestamps in `git log` output!
    Ex. output: `Sun Mar 6 13:04:39 2022 -0700`
    Keywords: git date; git log date; date git log
---
[DATE MATH: use `date -d "[math expressions]"`! Examples:]
---
date -d "+10 minutes"
    Print the `date` output as it would be **10 minutes from now** (in the future)!
date +"%a %b %-d %H:%M:%S %Y %z" -d "Sun Mar 6 13:04:39 2022 + 10 minutes"
    <======= Do date-and-time or timestamp math to create a new date and time! =======
    Print this timestamp **plus 10 minutes**, in this specified `git log`-like format. 
    Output: `Sun Mar 6 13:14:39 2022 -0700`
date +"%a %b %-d %H:%M:%S %Y %z" -d "Sun Mar 6 13:04:39 2022 + 70 seconds"
    Same as above, but **add 70 seconds** instead of 10 minutes.
    Output: `Sun Mar 6 13:05:49 2022 -0700`
date +"%Y%m%d-%H%Mhrs_%Ssec"
    <===============
    A good date format for use as a folder name when running automatic backup scripts. Ex. output:
            20220331-1908hrs_42sec

---
time zones / timezones:
- initially learned from ChatGPT; manually tested myself
---
timedatectl status
    <=========
    List your current time and timezone
timedatectl
    Same as just above.
timedatectl list-timezones
    List all possible timezones
sudo timedatectl set-timezone America/New_York
    Set your timezone to America/New_York (Eastern Time)
sudo timedatectl set-timezone America/Phoenix
    <=========
    Set your timezone to America/Phoenix (MST always--no Daylight Savings Time)
sudo timedatectl set-timezone America/Los_Angeles
    Set your timezone to America/Los_Angeles (Pacific Time)
find /usr/share/zoneinfo
    A very crude way to list all possible timezones, since they are stored as files inside the /usr/share/zoneinfo dir.
ls /usr/share/zoneinfo/*
    Another very crude way to do the above (list all possible timezones)
sudo ln -svnrf /usr/share/zoneinfo/America/New_York /etc/localtime
    Create a symlink pointing to the "/usr/share/zoneinfo/America/New_York" file at "/etc/localtime". 
    This is a way to manually set the timezone to America/New_York, since the binary file either copied to or symlinked to the /etc/localtime file is what sets the timezone. 
    Same as `sudo timedatectl set-timezone America/New_York`.
sudo cp /usr/share/zoneinfo/America/New_York /etc/localtime
    Same as just above, except copy the binary timezone file rather than symlinking it.


== diff: ==
[plain diff; NOT git diff; regular diff; diff only; only diff; diff alone; alone diff]

See also the Linux `cmp` command:
cmp file1 file2
    Compare two files **byte-by-byte**.

diff file1.txt file2.txt
    Compare file1.txt and file2.txt **line-by-line** for differences! (similar to `git diff`).
diff -u file1.txt file2.txt
    same as above, except showing 'u'nified context output, meaning: show 3 lines (by default) of "unified", or intermingled line-by-line, output to show the context around the differences between the left and right files!
diff --unified file1.txt file2.txt
    same as above
diff -c file1.txt file2.txt
    similar to the above, except show 3 lines for each file of **'c'opied** 'c'ontext instead of line-by-line unified context
diff --context file1.txt file2.txt
    same as above
diff -u=10 file1.txt file2.txt
    show 10 lines of 'u'nified context instead of the default 3 lines
diff --color=always file1.txt file2.txt
    show color output!
diff -u --color=always file1.txt file2.txt
    <============== BEST ANSWER! [identical output to `git diff`] ===============
    JUST LIKE `git diff`! SHOW COLOR, WITH UNIFIED LINE-BY-LINE CONTEXT, JUST LIKE git diff! 
diff -y --color=always file1.txt file2.txt
    Same as above, except use a prettier side-b'y'-side view instead.
    <================== EVEN PRETTIER SIDE-BY-SIDE VIEW WITH '-y' ===================
diff -u --color=always left_file.txt right_file.txt
    same as above, except with me accentuating the position of the "left" and "right" files in the command <=============
git diff --no-index -- file.a file.b
    same as `diff -u --color=always file1.txt file2.txt`! ie: this (`--no-index`) allows you to use `git diff` on files NOT tracked in/tracked by any git repo!
    See: https://stackoverflow.com/a/15110387/4561887
diff -r path/to/dir1 path/to/dir2
    <======= COMPARE 2 DIRS =========
    Compare (diff) two directories to see if their contents are equal.
diff -rq path/to/dir1 path/to/dir2
    Similar to above, but include the `-q` `--brief` option, whatever that means.
diff -r --brief path/to/dir1 path/to/dir2
    <======= COMPARE 2 DIRS =========
    Same as above. 

- Note that `man diff` shows that you can use `-` as one of the two files to read from stdinput for that file instead! It says, "FILES  are  'FILE1  FILE2' or 'DIR1 DIR2' or 'DIR FILE' or 'FILE DIR'.  If --from-file or --to-file is given, there are no restrictions on FILE(s).  If a FILE is '-', read standard input.  Exit status is 0 if inputs are the same, 1 if different, 2 if trouble." So, you can do this!:
---
cat left_file.txt | diff -u --color=always - right_file.txt = pipe content in from stdinput as the **left** file (marked by `-` in the `diff` command)!
cat right_file.txt | diff -u --color=always left_file.txt - = pipe content in from stdinput as the **right** file (marked by `-` in the `diff` command)!

- This allows you to do interesting things, such as show how clang-format changes a file, like this:
clang-format myfile.cpp | diff -u --color=always myfile.cpp - = run clang-format on myfile.cpp, sending its clang-formatted output to stdout; pipe this formatted output to `diff`, however, showing 3 lines of 'u'nified output, with color on, comparing the original myfile.cpp on the left to the stdinput piped in as the file on the right. Therefore, the left is the original file and the right is the formatted file. Now, you can see the output of what changes WOULD be made withOUT actually making those formatting changes! It's a sort of clang-format "preview" to see what **would** be done without actually doing it! See the == clang-format: == section above for further details.


== ==

HASH SUM COMMANDS [hash sums, checksums, cryptography, cryptographic checksums, data integrity checksums]:
sha256sum somefile.txt
    Calculate a SHA-256 hash over somefile.txt.
sha512sum somefile.txt
    Calculate a SHA-512 hash over somefile.txt.
md5sum somefile.txt
    do an MD5 checksum of somefile.txt; note: according to my online research, MD5 checksums are NOT cryptographically sound, but are still ok for use as general-purpose data integrity checksums.
shasum --algorithm 256 somefile.txt
    same as `sha256sum somefile.txt`
shasum -a 256 somefile.txt
    same as above = same as `sha256sum somefile.txt`
shasum -a 512 somefile.txt
    same as `sha512sum somefile.txt`

strings <binary_file>
strings my_binary_file > temp_strings.txt
    extract all ASCII strings from the binary file my_binary_file and store them into the text file temp_strings.txt.

strip <object_file>
strip <executable_file>
strip my_executable_file
    Strip and remove (discard) symbol data from C and C++ executables/object files. This can be used to reduce the size of a Linux executable, for instance, when you want to move it to a very memory-constrained small embedded Linux device or Linux distribution.
    See:
    1. `man strip`
    1. Where I first learned about this: https://github.com/npat-efault/picocom#compilation--installation
        > [Stripping] the binary is not required, it just reduces its size by a few kilobytes

hexdump -C my_file
    print all chars of the binary or ASCII file, my_file, in hex+ASCII mode (`-C` means "'C'anonical hex+ASCII display"). 
    Ex. 1:
        $ hexdump -C temp_strings.txt
        00000000  6f 22 6c 69 6e 6b 22 64  68 74 74 70 73 3a 2f 2f  |o"link"dhttps://|
        00000010  77 77 77 2e 72 65 64 64  69 74 2e 63 6f 6d 2f 72  |www.reddit.com/r|
        00000020  2f 41 73 6b 52 65 64 64  69 74 2f 63 6f 6d 6d 65  |/AskReddit/comme|
        00000030  6e 74 73 2f 65 73 74 32  62 34 2f 77 68 61 74 5f  |nts/est2b4/what_|
        00000040  77 6f 75 6c 64 5f 62 65  5f 74 68 65 5f 77 6f 72  |would_be_the_wor|
        00000050  73 74 5f 74 68 69 6e 67  5f 74 6f 5f 70 75 74 5f  |st_thing_to_put_|
        00000060  69 6e 5f 61 5f 70 69 0a  61 74 61 2f 22 63 6f 72  |in_a_pi.ata/"cor|
        ...
    Ex. 2:
        $ hexdump -C d\:\\lineter.csv 
        00000000  66 72 75 69 74 7c 71 75  61 6e 74 69 74 79 0d 61  |fruit|quantity.a|
        00000010  70 70 6c 65 7c 35 0d 62  61 6e 61 6e 61 7c 37 0d  |pple|5.banana|7.|
        00000020  6d 61 6e 67 6f 7c 38 0d                           |mango|8.|
        00000028
hexdump -c my_file
    Also super useful! Prints the "One-byte character display", which means that a `\r` char gets printed as `\r` literally instead of as a hex `0d`! Sample output:
    Correlary to Ex. 2 from above:
        $ hexdump -c d\:\\lineter.csv 
        0000000   f   r   u   i   t   |   q   u   a   n   t   i   t   y  \r   a
        0000010   p   p   l   e   |   5  \r   b   a   n   a   n   a   |   7  \r
        0000020   m   a   n   g   o   |   8  \r                                
        0000028

xxd file_in.bin file_out.hex
    <=======
    Convert binary to ASCII hex. 
    A hexdump tool. ie: binary (or ASCII, if the binary is ASCII chars) to ASCII hex chars. 
    ==> `xxd` does binary to ASCII hex, and `xxd -r` does the reverse: ASCII hex to binary. <===
    Some sort of hexdump-like tool similar to `hexdump`. From `man xxd`: "xxd - make a hexdump or do the reverse."
xxd -r file_in.hex file_out.bin
    <=======
    Do the 'r'everse: convert ASCII hex to binary.
hex2xxdhex path/to/myfile1.hex path/to/myfile2.hex && meld path/to/myfile1.xxd.hex path/to/myfile2.xxd.hex
    <======== BEST BINARY FIRMWARE COMPARE COMMAND =======
    My custom function to convert .hex firmware files to .bin and then to a human-compare-friendly .xxd.hex, so you can easily compare two files with `diff` or `meld`. 
    See:
    1. My answer here: https://stackoverflow.com/a/76584597/4561887
    1. eRCaGuy_dotfiles/home/.bash_useful_functions

objcopy --input-target=ihex --output-target=binary my_firmware.hex my_firmware.bin
    Convert an Intex hex firmware file to binary.
    See: https://stackoverflow.com/a/37226481/4561887
hex2bin path/to/myfile1.hex path/to/myfile2.hex path/to/myfile3.hex
    <========
    My custom function to convert .hex firmware files to .bin. 
    This command converts all 3 of this .hex files to .bin files in the same dir as the corresponding .hex files.
    See:
    1. My answer here: https://stackoverflow.com/a/76584597/4561887
    1. eRCaGuy_dotfiles/home/.bash_useful_functions

echo "54657374696e67203120322033" | xxd -r -p
    Convert this ASCII hex string to binary, which happens to be printable ASCII chars. 
    Run and output:
        ```bash
        $ echo "54657374696e67203120322033" | xxd -r -p
        Testing 1 2 3
        ```
    Note: 
    - `-r` means 'r'everse, as in: convert ASCII hex to binary, not binary to ASCII hex. 
    - '-p' means 'p'lain output, or "continuous hexdump style". This makes it print properly by not separating bytes, I think.
    - You can NOT combine `-r -p` into `-rp`. That fails to parse and doesn't work! The program has a lousy argument parser.
    See: https://stackoverflow.com/a/30084257/4561887
echo "Testing 1 2 3" | xxd -p
    Convert this binary (these ASCII chars) to ASCII hex. 
    Example run and output:
        ```bash
        $ echo "Testing 1 2 3" | xxd -p
        54657374696e672031203220330a
        ```
    Note that the hex `0a` at the end is decimal 10, or the `\n` newline char. That newline char is added by `echo` automatically. 
    See also: 
    1. https://stackoverflow.com/a/30084257/4561887
    1. And the example just above.
printf "%s" "54657374696e67203120322033" | xxd -r -p
    <==============
    Convert this ASCII hex string to binary (regular ASCII). 
    - Note: "ASCII hex string" means data like in an Intel ".hex" microcontroller firmware hex file. But, if you were truly trying to convert an entire Intel .hex file to binary, use the proper tool instead: 
        `objcopy --input-target=ihex --output-target=binary my_firmware.hex my_firmware.bin`. 
    - Better than the example above, since it doesn't add a stray newline char (hex 0A, or `\n`) at the end, like `echo` does. 
    - See my comments below this answer here: https://stackoverflow.com/a/30084257/4561887
    - Example run and output:
        ```bash
        $ printf "%s" "54657374696e67203120322033" | xxd -r -p
        Testing 1 2 3
        ```
printf "%s" "Testing 1 2 3" | xxd -p
    <==============
    Convert this binary (ASCII string) to ASCII hex. 
    Better than the example above, since it doesn't add a stray newline char (hex 0A, or `\n`) at the end, like `echo` does. 
    See my comments below this answer here: https://stackoverflow.com/a/30084257/4561887
    Example run and output:
        ```bash
        $ printf "%s" "Testing 1 2 3" | xxd -p
        54657374696e67203120322033
        ```
xxd -ia file > file.c
    Create a C file which can be included in a C program to encode binary data into a C program! From `man xxd`:
    >     -i | -include
    >            output in C include file style. A complete static array definition is written (named after the input file), unless xxd reads from stdin.
    Full example:
    Notice that `xxd -ia file > file.c` places the entire contents of `file` into `file.c` as a C array of bytes, with all bytes written in hex! You can then use this "file.c" directly in any C or C++ program!
    ---
    ```bash
    $ printf "%s" "hello world" > file
    $ xxd -ia file > file.c
    $ cat file.c
    unsigned char file[] = {
      0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64
    };
    unsigned int file_len = 11;
    ```
    ---
    NB: for a C source file that contains:
    file.c:
    ```c
    unsigned char file[] = {
      0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64
    };
    unsigned int file_len = 11;
    ```
    an appropriate includable header file, file.h, would look like this:
    file.h:
    ```c
    // Now when you include this header file, you get access to these variables because 
    // the compiler is made aware that **they exist** via the `extern` keyword, but including
    // the header will NOT include this huge object each time. Rather, the linker will find its
    // corresponding object file at link time.
    extern unsigned char* file;
    extern unsigned int file_len;
    ```

dos2unix -n in.win.hex out.unix.hex
    Convert DOS/Windows `\r\n` line endings in `in.win.hex` to `\n` Linux/Unix line endings in `out.unix.hex`. 
    Note: this runs inside Git Bash in Git for Windows, too!
unix2dos -n in.unix.hex out.win.hex
    Convert `\n` Linux/Unix line endings in `in.unix.hex` to `\r\n` DOS/Windows line endings in `out.win.hex`. 
    Note: this runs inside Git Bash in Git for Windows, too!

vbindiff file1.bin file2.bin
    <============ VERY ADVANCED BINARY COMPARISON TOOL! ==============
    Compare two binary files in an ncurses-like interactive GUI-like environment way. 
    See the bottom of this article here: https://www.howtogeek.com/817201/compare-binary-files-linux/
    [meld for binary files meld for .bin files meld diff cmp browse through binary files]
    See my answer here: https://superuser.com/a/1790518/425838
vbindiff file1.bin
    Browse through a single binary file!
    See: https://www.howtogeek.com/817201/compare-binary-files-linux/ - he said "And in fact, using VBinDiff with a single binary file is an easy and convenient way to browse through binary files, which is a nice bonus."
vbindiff --help
    Show help menu.
man vbindiff
    Show the man pages (manual pages).
[See also: Super User: How do I compare binary files in Linux?: https://superuser.com/q/125376/425838]

meld <(xxd file1.bin) <(xxd file2.bin)
    <========== THIS IS AMAZING! =========
    Compare two **binary** files side-by-side. 
    The `xxd` command is to convert binary to ASCII hex with ASCII next to it!
    I got the idea from this absolutely ingenious answer here!: https://superuser.com/a/968863/425838
    I may be the first to combine that technique with `meld`. 
    To compare two **Intel hex** files side-by-side, you must first convert them to binary, as shown below. `objcopy` can NOT write to stdout, as this question and answer learned: https://stackoverflow.com/q/24433784/4561887. 
    See my answer here: https://superuser.com/a/1790518/425838
objcopy --input-target=ihex --output-target=binary my_firmware1.hex 1.bin \
 && objcopy --input-target=ihex --output-target=binary my_firmware2.hex 2.bin \
 && meld <(xxd 1.bin) <(xxd 2.bin)
    <========== THIS IS AMAZING! =========
    (Same as above, except converting Intel hex files to binary first!)
    Compare two **Intel hex** firmware files side-by-side. See also the notes in the prior example just above. 
    The `xxd` command is to convert binary to ASCII hex with ASCII next to it!
    I got the idea from this absolutely ingenious answer here!: https://superuser.com/a/968863/425838
    I may be the first to combine that technique with `meld`. 
    For alternate compilers, you'll have to call your compiler directly. Ex: for the Microchip MPLAB X XC32 compiler toolchain, it would look like this instead:
    See my answer here: https://superuser.com/a/1790518/425838
xc32-objcopy --input-target=ihex --output-target=binary my_firmware1.hex 1.bin \
 && xc32-objcopy --input-target=ihex --output-target=binary my_firmware2.hex 2.bin \
 && meld <(xxd 1.bin) <(xxd 2.bin)
    <========== THIS IS AMAZING! =========
    Same as above, except for the Microchip MPLAB X XC32 compiler toolchain. See my notes just above.
    See my answer here: https://superuser.com/a/1790518/425838


gnome-system-monitor = CPU/RAM/network usage monitor GUI
top = basic CLI competitor to gnome-system-monitor
htop = much better (ncurses-based?) CLI competitor to gnome-system-monitor!

LIST RUNNING PROCESSES AND THEIR PROCESS IDS (PIDs):
(See `man ps` for details)
ps aux
    <====== MOST COMMON USAGE =====
    list all running processes on the system (using the BSD syntax) 
ps -A
    list all running processes on the system (using the standard syntax)
ps -eLf
    get info about *threads*
ps -ejH
    print a process tree = very helpful to see **what process called what process(es)**!
ps aux | grep "some_name"
    <==========
    Find only processes named "some_name", or at least with "some_name" in their output line displayed by `ps aux`
ps auxf
    <===== EVEN BETTER! =====
    Even better, also graphically show the process parent/child hierarchy and relationships to see which process spawned which process!
    See: https://unix.stackexchange.com/a/453654/114401 - where I first learned about the `-f` in `ps auxf`.
ps auxf | grep "some_name"
    <========== BEST! ==========
    Find processes with `some_name` in them, while also graphically viewing their process parent-child relationships/hierarchy.
    See: https://unix.stackexchange.com/a/453654/114401 - where I first learned about the `-f` in `ps auxf`.
pgrep "some_name"
    Similar to the cmd just above. Find the process ID (PID) of the process named "some_name"! This is easier and cleaner than using `ps aux | grep "some_name"`, as shown above!
    See this YouTube video at this time for where I learned this: https://youtu.be/qgG5Jhi_Els?t=314
    Keywords: pgrep kill; kill pgrep; kill process; process kill; find process; process finder

top
    List all processes in order of which one is using the most CPU % _first_.
    Tip: once you find a process you'd like to investigate, such as "Isolated w+", or something, run the `pstree` command below on it, such as 'pstree | less -i, then type "/isolated w"', to see which process it falls under. Ex: perhaps "Isolated w+" is part of Firefox. Running `pstree` and piping to `less` to search for that process will help you identify this.
top -b -n 1
    <==========
    Run `top` once (`-n 1`) in batch (`-b`) mode, rather than interactively. 
    This is great if you want to pipe the output to a file or to another tool to parse or grep it, for example. I use this in my "eRCaGuy_dotfiles/useful_scripts/cpu_logger.py" script.
    See: http://help.collab.net/index.jsp?topic=/teamforge178/faq/topcommand.html
top -b -n 1 | head -n 50
    <==============
    Same as above, but only keep the first 50 lines. This is fine because most of the time you only care the most about the first few dozen high-CPU-usage processes anyway.
top -o %MEM
    <==========
    Sort by the % memory (RAM) usage order (`-o %MEM`) instead of by the default % CPU usage (`-o %CPU`) order.
    See: https://unix.stackexchange.com/a/128957/114401

pstree
    <==========
    List the dependency/parent-child tree of all running processes. 
    See: https://forums.linuxmint.com/viewtopic.php?t=362756
pstree | grep -i "isolated w"
    See if the tree contains this word/process named "isolated w" (case 'i'nsensitive).
pstree | grep -C 99999 -i isolated
    <==========
    Same as above, but even better! Show all context ('-C') lines too. 
pstree | less -i
    ...then type "/isolated w"
    <==============
    Same as above, but even better still! Pipe it to `less` to view and search/scan the output live.

KILL RUNNING PROCESSES:
(see `man kill` for details)
kill -l = list all kill signal options; ex:
    $ kill -l
     1) SIGHUP      2) SIGINT       3) SIGQUIT      4) SIGILL       5) SIGTRAP
     6) SIGABRT     7) SIGBUS       8) SIGFPE       9) SIGKILL      10) SIGUSR1
    11) SIGSEGV     12) SIGUSR2     13) SIGPIPE     14) SIGALRM     15) SIGTERM
    16) SIGSTKFLT   17) SIGCHLD     18) SIGCONT     19) SIGSTOP     20) SIGTSTP
    21) SIGTTIN     22) SIGTTOU     23) SIGURG      24) SIGXCPU     25) SIGXFSZ
    26) SIGVTALRM   27) SIGPROF     28) SIGWINCH    29) SIGIO       30) SIGPWR
    31) SIGSYS      34) SIGRTMIN    35) SIGRTMIN+1  36) SIGRTMIN+2  37) SIGRTMIN+3
    38) SIGRTMIN+4  39) SIGRTMIN+5  40) SIGRTMIN+6  41) SIGRTMIN+7  42) SIGRTMIN+8
    43) SIGRTMIN+9  44) SIGRTMIN+10 45) SIGRTMIN+11 46) SIGRTMIN+12 47) SIGRTMIN+13
    48) SIGRTMIN+14 49) SIGRTMIN+15 50) SIGRTMAX-14 51) SIGRTMAX-13 52) SIGRTMAX-12
    53) SIGRTMAX-11 54) SIGRTMAX-10 55) SIGRTMAX-9  56) SIGRTMAX-8  57) SIGRTMAX-7
    58) SIGRTMAX-6  59) SIGRTMAX-5  60) SIGRTMAX-4  61) SIGRTMAX-3  62) SIGRTMAX-2
kill -L = same as above
kill -9 9999 = send KILL signal (#9 in the list above) to Process ID (PID) 9999  <======= VERY COMMON USAGE ========
kill -KILL 9999 = same as above (KILL is #9 in the list above)
kill -SIGKILL 9999 = exact same as above  <======= VERY COMMON USAGE ========
kill -l KILL = look up the "KILL" signal in the list above to retrieve that it is signal "9"
kill -l 9 = look up the number "9" signal in the list above to retrieve that it is signal "KILL"
kill 9999 8888 = kill both PIDs 9999 and 8888 (can list any number of pids to kill!); the general format is:
kill pid1 pid2 pid3 ... pidn = send the default signal, SIGTERM (or TERM) to all these processes
kill 123 543 2341 3453 = "send the default signal, SIGTERM, to all those processes" (see `man kill`); note that SIGTERM can also be written as TERM or 15.
kill -TERM 123 543 2341 3453    = same as above
kill -SIGTERM 123 543 2341 3453 = same as above  <======= VERY COMMON USAGE ========
kill -15 123 543 2341 3453      = same as above

kill "$(cat /var/run/process_name.pid)"
    Kill the process whose name is `process_name` and whose PID (process ID) is stored inside the file "/var/run/process_name.pid".
pid="$(cat /var/run/syslog-ng.pid)" kill -SIGUSR1 $pid
    Reopen the log files being written-to by `syslog-ng`. This is good to call after logrotate. 
    This sends the `SIGUSR1` kill signal to the `syslog-ng` process via its PID stored in that file. 
    In this particular case, it is equivalent to `syslog-ng-ctl reopen`. 
    See my notes here: https://github.com/syslog-ng/syslog-ng/issues/1774#issuecomment-1270517815

killall chrome
    <=========== WORKS GREAT! ============
    Kill all Chrome processes (useful whenever Chrome freezes!)
    [chrome freezes chrome freezing frozen chrome is frozen]
    See: https://askubuntu.com/a/746948/327339
pkill -9 -f chrome
    Kill all Chrome processes. 
    See: https://askubuntu.com/a/746948/327339
pkill <process_name>
    Kill this process. To **list** all processes which match a given name, use `pkill` instead!
pgrep chrome
    <===============
    List all processes which match the name "chrome"! ie: list all running Chrome processes. 
    See: `man pgrep` and `man pkill` (apparently from the same executable or module/project).
pgrep <process_name>
    Search for a running process by name! (perhaps better than `ps aux | grep -i process_name`, especially when you just want the PID (process ID)!)
    To **kill** all processes which match a given name, use `pkill` instead!
    
pgrep -f foxit
    Find all Foxit PDF reader processes. 
    NB: `-f` is **required** to match the foxit processes. Without it, they won't be found!
pkill -f foxit
    <======= VERY USEFUL SINCE FOXIT FREEZES ALL THE TIME IN MY LINUX UBUNTU 20.04 PC! ========
    Kill all Foxit PDF reader processes
    NB: `-f` is **required** to match the foxit processes. Without it, they won't be found!
sudo pkill --signal SIGINT openconnect
    cleanly kill openconnect or openconnect-sso
    See my answer: https://unix.stackexchange.com/a/725171/114401
sudo pkill -SIGINT openconnect
    <===============
    (same thing as above): cleanly kill openconnect or openconnect-sso
    See my answer: https://unix.stackexchange.com/a/725171/114401

[disk usage; disk free space; disk space usage]
- See: https://www.ubuntupit.com/best-disk-analyzer-tools-for-linux-system/
sudo baobab = disk usage analyzer GUI (now called simply "Disk Usage Analyzer" in Ubuntu, and it comes with Ubuntu!)
baobab = same as above, except it can't analyze root directories
qdirstat = a direct competitor GUI tool to analyze disk usage--comparable to baobab/Disk Usage Analyzer
ncdu [options] <dir> = an ncurses-based tool to analyze disk usage in directory "dir"; CLI-based; works ***really well*** and it is ***really fast***, and it also works over ssh!
free -h = show memory and swap total, used, and free space!
(sudo) swapon --show = show swap partition and swapfile status and sizes
df -h = show disk usage
du -h my_folder = show folder usage
How to make a Linux swapfile; see my own answer here!
https://stackoverflow.com/questions/55190272/java-lang-outofmemoryerror-when-running-bazel-build/60572662#60572662

less -RFX myfile.txt = open up myfile.txt in the "less" stream viewer/pager, with the following options, which make it act **identically** to how the output from `git diff` acts! Note: I borrowed my explanations here from the bottom of my own "eRCaGuy_dotfiles/useful_scripts/git-diffn.sh" (`git diffn`) script I wrote herein.
-R = interpret ANSI color codes
-F = quit immediately if the output takes up less than one screen
-X = do NOT clear the screen when less exits
See also:
  1. https://stackoverflow.com/questions/2183900/how-do-i-prevent-git-diff-from-using-a-pager/14118014#14118014
  2. https://unix.stackexchange.com/questions/38634/is-there-any-way-to-exit-less-without-clearing-the-screen/38638#38638

grep '' *
    Read and print out ALL contents (`''`) of ALL files (`*`) within this dir!
    [keywords: list all files (that would actually be with the `find` cmd); list contents of all files; read and print contents of all files in a dir; list all file contents; print all file contents]
    <======== VERY USEFUL! =========
grep '' /path/to/dir/*
    Read and print out ALL contents (`''`) of ALL files within the "/path/to/dir/" dir (`/path/to/dir/*`)! [print all; read all; print all files; cat all files]
    <======== VERY USEFUL! =========
watch -n 0.5 'grep '"''"' *'
    Watch the contents of a bunch of files change by printing out their values by running `grep '' *` every 0.5 sec!
    - See here for help with these quotes: https://stackoverflow.com/a/1250279/4561887
        - In the `'"''"'` part, the first single quote ends the previous quote. Then you have two single quotes in double quotes (`"''"`), then you have a single quote to begin the next quoted string.
    <======== VERY USEFUL! =========
watch -n 0.5 "grep '' *"
    Same as above--but simpler since it turns out this command can be done with double quotes around the outside instead of single quotes since we don't need to block any variable expansion that would otherwise happen 1-level too soon when within double quotes!
    <======== VERY USEFUL! =========
watch -n 0.5 "grep '' path/to/some/dir/*"
    Same as above, but showing that you can grep what's in some other dir explicitly instead of just whatever files are in your current dir.

watch -n INTERVAL_IN_SECONDS COMMAND = run COMMAND and display its output every INTERVAL_IN_SECONDS seconds! See: https://linuxize.com/post/linux-watch-command/; ex:
watch -n 30 'du -h ~/.cache | tail -n 1' = display the disk usage in your ~/.cache dir every 30 sec! Very useful when you are watching a large bazel build cache grow, for instance! Ex:
watch -n 30 'du -h ~/.cache/bazel | tail -n 1' = watch your bazel build cache (in ~/.cache/bazel) grow every 30 seconds--ex: during a large build; it can be useful to watch the directory grow as evidence that the build is progressing properly; note: you may need to use sudo in the command `watch` is running for it to check the size of *all* objects:
watch -n 30 'sudo du -h ~/.cache/bazel | tail -n 1' = same as above, except with the subcommand, `du`, as root, so it can read *all* items, even those in your cache which may be owned by root


[Keywords: continually watch a file grow; ex: a growing log file, by "following" it. This means you load the new contents at the end as it grows; watch growing log file; cat growing log file; continually watch log file; continually watch growing log file; watch growing file; watch file grow; less follow file; tail follow file; follow log file; track log file (`tail -f my_file.log`); tail watch less; tail, watch, and less; tail, watch, & less; tail watch and less; tail watch & less]

less -N +F path/to/some/growing/log_file.log
    View a file, showing line numbers (`-N`), and follow it to continually watch it grow live ('+F'). 
    See my answer here: https://unix.stackexchange.com/a/687072/114401
less -N --follow-name +F path/to/some/growing/log_file.log
    <=============== EXCELLENT--MY FAVORITE OPTION OVERALL! ================
    Same as above, but also do `--follow-name` to follow the **name** of the file "log_file.log" instead of the file descriptor originally opened when this file was opened. This ensures you keep tracking the latest rotating log file instead of watching a stale backed-up log file renamed from `log_file.log` to `log_file.log.1` or something. 
    Note that `tail`'s equivalent of `--follow-name` is `follow=name`.
    See my answer here: https://unix.stackexchange.com/a/687072/114401
    See also here: https://unix.stackexchange.com/a/196349/114401
less -N +G path/to/some/growing/log_file.log
    Similar to above, but just jump to the end of the file once. To begin following it live from this point, press `F` OR Ctrl + End while `less` is open and running.
    See my answer here: https://unix.stackexchange.com/a/687072/114401
tail -f path/to/some/growing/log_file.log
    <=============== EXCELLENT--MY FAVORITE ON EMBEDDED LINUX SYSTEMS RUNNING BUSYBOX since `less +F` doesn't work on those ================
    Watch a file grow live, showing only new contents as they come in. 
    See my answer here: https://unix.stackexchange.com/a/687072/114401
tail -f --follow=name path/to/some/growing/log_file.log
    <===== EXCELLENT OPTION for `tail` if NOT using BusyBox =====
tail -f -s 2 path/to/some/growing/log_file.log
    Same as above, but only check and load new contents at the end of the file every 2 seconds.
tail +1 -f path/to/some/growing/log_file.log
    Similar to above, but also print the entire file first, starting at the first line (`+1`), before following and loading new contents continually
    See my answer here: https://unix.stackexchange.com/a/687072/114401
watch -n 1 'tail -n 20 path/to/some/growing/log_file.log'
    <======== VERY GOOD =======
    Continually view the last 20 messages of the log file every 1 second.
    See my answer here: https://unix.stackexchange.com/a/687072/114401
watch -n 1 'head -n 2 log_file.log; tail -n 10 log_file.log'
    <======== BEST WHEN YOU NEED A HEADER TO VIEW AT THE TOP OF AN UPDATING LOG FILE ========
    Every 1 second, print the first 2 lines of `log_file.log` (which contain log **header** information, for instance), followed by the last 10 lines of the log file. This way you'll see a frozen header at the top of the output, with a constantly-updating stream of new data underneath that as the log file grows!


== CAN Bus and CAN Networking: ==

TODO: need to add this information in here so I don't forget it.
[CANbus; can: ==; can devices: ==]


== USB, serial, devices, etc.: ==
[usb serial devices]

Serial terminal tools:
1. picocom [my favorite]
    1. See my installation instructions & notes: https://github.com/ElectricRCAircraftGuy/eRCaGuy_dotfiles/tree/master/useful_apps/serial_terminals_README.md
    1. Source code: https://github.com/npat-efault/picocom
1. minicom
1. Arduino Serial Monitor and Serial Plotter
1. eRCaGuy_PyTerm
    1. My repo: https://github.com/ElectricRCAircraftGuy/eRCaGuy_PyTerm

[FOR MY NOTES ON PICOCOM, SEE: "eRCaGuy_dotfiles/useful_apps/serial_terminals_README.md"]

picocom --help
    Show the version (1st line) and help menu.
picocom --baud 115200 /dev/ttyUSB0
    Connect to device /dev/ttyUSB0 at 115200 baud
man picocom
    See the manual pages for `picocom`.
Ctrl+A, Ctrl+H
    Show the Help menu while in picocom.
    See:
    1. `man picocom` and search for "C-a" in the "COMMANDS" section.
    1. "eRCaGuy_dotfiles/useful_apps/serial_terminals_README.md"
Ctrl+A, Ctrl+X
    Exit picocom.
    See:
    1. `man picocom` and search for "C-a" in the "COMMANDS" section.
    1. "eRCaGuy_dotfiles/useful_apps/serial_terminals_README.md"

stty 115200
    Change the serial baud rate **of the active terminal** to 115200.
[SEE MORE `stty` COMMANDS BELOW!]

setserial -g /dev/ttyS* | sort -V
    Display (and sort) serial information for all /dev/ttyS* devices.
    See my answer: https://unix.stackexchange.com/a/688772/114401
setserial -g /dev/ttyUSB* | sort -V
    Display (and sort) serial information for all /dev/ttyUSB* devices
    See my answer: https://unix.stackexchange.com/a/688772/114401
setserial -g -G /dev/ttyS* | sort -V
    <===========
    Same as 1st cmd above, but also show extra info., such as the baud rate too.
    See my answer: https://unix.stackexchange.com/a/688772/114401
setserial -g -G /dev/ttyUSB* | sort -V
    <===========
    Same as 2nd cmd above, but also show extra info., such as the baud rate too.
    See my answer: https://unix.stackexchange.com/a/688772/114401

dmesg | grep ttyS
    <===========
    Show UART information, incl. baudrate, for /dev/ttyS* devices.
    See my answer: https://unix.stackexchange.com/a/688772/114401
dmesg | grep ttyUSB
    <===========
    Show UART information, incl. baudrate, for /dev/USB* devices.
    See my answer: https://unix.stackexchange.com/a/688772/114401
dmesg
    print all messages from the Linux kernel ring buffer, which includes all entries for USB enumeration and stuff, including entries for each time you plug in or unplug any USB device, USB HID keyboard or mouse or gamepad or similar, USB to serial UARTs/converters (on nearly all Arduino boards), etc.
dmesg | tail
    just show the last 10 entries from the Linux kernel dmesg ring buffer
dmesg | tail -n 10
    same as above! (10 is the default `-n` setting for `tail`)
dmesg | tail -n 30
    show just the last 30 entries from the Linux kernel dmesg ring buffer [very useful to see what USB device you just plugged in or unplugged! It will show the device's USB ID, vendor ID, vendor name, manufacturer, serial number, etc. etc.] <===== EXCELLENT! =====
sudo dmesg --clear
    clear the entire Linux kernel dmesg ring buffer (not recommended necessarily, but it allows you to easily isolate and see just the lines generated by unplugging or plugging in a certain USB device); better, I think, would be to simply look at the timestamps in the `dmesg` output to see what device or event is likely to have generated which lines. See `man dmesg` for details on this command.
sudo dmesg -wH
    <======== VERY USEFUL!--shows LIVE output! ==========
    See the `dmesg` output **live** **as it changes!** `-H` means 'H'uman-readable output, and `-w` means `--follow`, or "'w'ait for new messages" (as they come in!). 
    See: https://unix.stackexchange.com/a/95852/114401

lsusb = list ('l'i's't) all USB devices which are plugged in

ls /dev = list ('l'i's't) all devices in the Linux "/dev" folder (device tree)

Note: an excellent way to get as much info. as possible about a device you just plugged in, and to see how it enumerates and what kind of device it is, is as follows:
    # 1. Start with the device NOT plugged in, then run:
    ls /dev > ~/temp/dev1.txt
    lsusb > ~/temp/lsusb1.txt

    # 2. plug it in now, then run:
    ls /dev > ~/temp/dev2.txt
    lsusb > ~/temp/lsusb2.txt
    # A. Compare the before and after files with `meld`:
    meld ~/temp/dev1.txt ~/temp/dev2.txt      # compare the before and after of what's in "/dev"
    meld ~/temp/lsusb1.txt ~/temp/lsusb2.txt  # compare the before and after of the `lsusb` output
    # OR B. compare the files above using `diff`, but with the same look (incl. coloring,
    #   surrounding line context, and line number info.) as `git diff`, as shown below.
    #   Note: for more context still, use `--unified=10` instead of just `-u` below. See `man diff`
    #   for details.
    diff -u --color=always ~/temp/dev1.txt ~/temp/dev2.txt
    diff -u --color=always ~/temp/lsusb1.txt ~/temp/lsusb2.txt
    # look at the recent Linux kernel ring buffer messages to see what was just plugged in
    dmesg | tail -n 30

    # 3. Unplug it again then run `dmesg` one more time to see the messages of what was
    #    just UNplugged!
    dmesg | tail -n 30

stty -echo
    Disable echo (printing chars you type, as received by stdin) in your current standard Linux TTY (TeleTYpe) terminal.
    NB: this is a universal concept, and really has nothing to do with *serial* terminals in particular.
    See: https://stackoverflow.com/a/62642654/4561887
stty echo
    Re-enable echo (printing chars you type, as received by stdin) in your current standard Linux TTY (TeleTYpe) terminal.
    NB: this is a universal concept, and really has nothing to do with *serial* terminals in particular.
    See: https://stackoverflow.com/a/62642654/4561887
stty 
    Prints all current terminal line settings **of the active terminal**. 
    Ex: in a standard Linux Ubuntu terminal its output might look like this:
    ```bash
    $ stty
    speed 38400 baud; line = 0;
    -brkint -imaxbel iutf8
    ``` 
    And on a remote embedded Linux system to which you are connected over an actual serial cable, it will show the actual serial baud rate, and might look like this. Notice that the real baud rate in this case is 115200, and a lot more information about this terminal is printed out, probably because **it's an actual serial port**, _not_ just an _emulated_ serial terminal like most terminals!:
    ```bash
    $ stty
    speed 115200 baud; line = 0;
    intr = ^C; quit = ^\; erase = ^?; kill = ^U; eof = ^D; eol = 
    ; eol2 = <undef>;
    swtch = <undef>; start = ^Q; stop = ^S; susp = ^Z; rprnt = ^R; werase = ^W;
    lnext = ^V; flush = ^O; min = 1; time = 0;
    -brkint ixoff -imaxbel
    -iexten
    ```
stty 115200
    Change the serial baud rate **of the active terminal** to 115200.
stty <parameters>
    See:
    1. `man stty`
    2. https://unix.stackexchange.com/a/242814/114401
stty -F </dev/device>
    Read serial configuration for the device at "/dev/device" instead of from `stdin` (the active terminal device you are typing into).
    From `man stty`:
    ```bash
    -F, --file=DEVICE
       open and use the specified DEVICE instead of stdin
    ```
stty -F /dev/ttyUSB0
    Print all current terminal line settings **of serial device "/dev/ttyUSB0"**.
    See: https://superuser.com/a/580088/425838
stty -F /dev/ttyUSB0 115200
    Change the serial baud rate of serial device "/dev/ttyUSB0" to 115200.
    See: https://superuser.com/a/1482079/425838
stty -F /dev/ttyUSB0 <parameters>
    See:
    1. `man stty`
    2. https://unix.stackexchange.com/a/242814/114401
---
NB: to list all possible serial baud rates of a particular serial device, OR to list all possible serial baud rates of ALL serial devices on your system, see these brilliant scripts here!: Is there any way to check which baud rates are supported on a serial device?: 
https://superuser.com/a/1482079/425838
---

---
Serial devices can be listed in both "/dev" **and** "/sys/class/tty"!
See "/sys/class/tty" here--search this page for that phrase: https://superuser.com/a/1482079/425838
---

ls /dev/tty*
    List all serial devices on your computer!
    See "/dev/tty" here--search this page for that phrase: https://superuser.com/a/1482079/425838
    NB: the device files in "/dev" are **files**. Pass them to `stty` to read the currrent terminal settings. 
    Ex: `stty -F /dev/ttyUSB0` will show its current baud rate and stuff.
ls /sys/class/tty
    List all serial devices on your computer! (similar to above)
    See "/sys/class/tty" here--search this page for that phrase: https://superuser.com/a/1482079/425838
    NB: the devices in "/sys/class/tty" are sysfs **directories**! Ex: "/sys/class/tty/ttyUSB0" contains a ton of other files, folders, and info! 
    I don't understand all of these "/sys/class/tty" files and folders, but to read all of these files at once, do this!: 
    `grep -rn '' /sys/class/tty/ttyUSB0/*`
grep -rn '' /sys/class/tty/ttyUSB0/*
    Grep all files herein at once!
    Read the contents of all readable files in the "/sys/class/tty/ttyUSB0/" sysfs dir at once!
    I don't really know what all this stuff means, but the above grep command is **super useful** to read all contents at once!
    Keywords: grep read all files and folders at once; grep all dir contents; grep all file contents; grep all files in a dir; dir grep everything; folder grep all files at once


== GPS devices: ==

sudo apt install gpsd-tools
    Install `gpsmon`. 
gpsmon
    Monitor a GPS device connected to your Linux system--ex: via serial, such as via serial maybe??--not sure).
sudo apt install gpsd
    Install `gpsd` daemon, `ppscheck`, etc.
ppscheck /dev/ttyS0
    See if a PPS (pulse per second) time-sync signal is coming in from a GPS over the serial device connected to Linux pseudo-file `/dev/ttyS0`. 
cpgs
    <===== LOOKS VERY USEFUL =======
    A terminal version of `xgps` (see below). 
    [Another GPS monitoring tool; useful to **see the GPS altitude**, for instance, which is either in MSL or HAE (Height Above Ellipsoid)--not sure which]
    See `man cgps`. 
    Simple clients for `gpsd` include:
    - `cgps`
    - `gegps`
    - `gps`
    - `lcdgps`
    From `man cgps`:
    > cgps is a client resembling xgps, but without the pictorial satellite display and able to run on a serial terminal or terminal emulator.
sudo apt install gpsd-clients
    Install gpsd clients, such as `xgps`, `gegps`, etc.
xgps
    <===== LOOKS VERY USEFUL =======
    A GUI version (X-window-based maybe?) of `cgps`. 
gegps
    <===== LOOKS VERY USEFUL =======
    GS: a "Google Earth GPS" tool, I believe. [I'm not sure how it works or how to set it up yet]
    From `man gegps`: 
    > By default, clients collect data from all compatible devices on localhost, using the default GPSD port 2947.
lcdgps
    From `man lcdgps`, `man gegps`, `man cgps`, etc.:
    > A client that passes gpsd data to lcdproc, turning your car computer into a very expensive and nearly feature-free GPS receiver. Currently assumes a 4x40 LCD and writes data formatted to fit that size screen. Also displays 4- or 6-character Maidenhead grid square output.


== `head` and `tail`: ==
- Use `head` to output the first part of files
- Use `tail` to output the last part of files
- This works great for piping `grep` output to one of these too!

echo -e "1 \n2 \n3 \n4 \n5 \n6 \n7 \n8 \n9 \n10" | head -n 3 = output just the FIRST 3 lines:
    $ echo -e "1 \n2 \n3 \n4 \n5 \n6 \n7 \n8 \n9 \n10" | head -n 3
    1
    2
    3
echo -e "1 \n2 \n3 \n4 \n5 \n6 \n7 \n8 \n9 \n10" | tail -n 3 = output just the LAST 3 lines:
    $ echo -e "1 \n2 \n3 \n4 \n5 \n6 \n7 \n8 \n9 \n10" | tail -n 3
    8
    9
    10

grep -rni --color=always "some search expression" | head -n 50 = output just the FIRST 50 occurrences I find!
grep -rni --color=always "some search expression" | tail -n 50 = output just the LAST 50 occurrences I find!

== awk: ==
Use `awk` to select only certain columns of textual output--see:
1. https://stackoverflow.com/questions/7315587/bash-shortest-way-to-get-n-th-column-of-output/43284174#43284174
1. and https://stackoverflow.com/questions/7315587/bash-shortest-way-to-get-n-th-column-of-output/7315716#7315716

Ex:
    echo "column1 column2 column3 column4" | awk '{print $1}' = select & keep only the 1st column of the text
    echo "column1 column2 column3 column4" | awk '{print $2}' = select & keep only the 2nd column of the text
    echo "column1 column2 column3 column4" | awk '{print $3}' = select & keep only the 3rd column of the text
    echo "column1 column2 column3 column4" | awk '{print $4}' = select & keep only the 4th column of the text

For a full `awk` program example, see the "eRCaGuy_dotfiles/useful_scripts/git-diffn.sh" program, which is written almost entirely in awk!


== Limit CPU usage: ==
[throttle cpu usage]
Limit CPU usage of a process in Linux: https://linoxide.com/linux-how-to/limit-cpu-usage-processes-linux/; ex:
    cpulimit -p 3185 -l 40 = limit Process ID (PID) 3185 to 40% ***of 1 CPU*** max CPU usage; so, for a multi-core machine (ex: 8 cores), to get a total of 40% of all cores you would need to use 0.4*(100/core * 8 cores) = 0.4*800 = 320, like this:
    cpulimit -p 3185 -l 320 = limit PID 3185 to 320% out of 800% (on an 8-core machine) = 320/800 = 40% overall on an 8-core machine!
OR
    cpulimit -e vmware-vmx -l 40 = limit the process named "vmware-vmx" to 40% ***of 1 CPU*** max CPU usage
    cpulimit -e vmware-vmx -l 320 = limit PID 3185 to 320% out of 800% (on an 8-core machine) = 320/800 = 40% overall on an 8-core machine!
So, to limit to 80% on an 8-core machine, use 0.8*800 = 640, like this:
    cpulimit -p 3185 -l 640
Limit to 62.5% on an 8-core machine:
    cpulimit -p 3185 -l 500

This is very useful to limit your CPU usage being used by Bazel, for instance, when it is building for dozens of minutes, or even hours. Note that the Bazel build server JVM is usually just called "java", and can easily be viewed with `ps`, `top`, `htop`, or the `gnome-system-monitor` GUI (my preferred choice).

    sudo apt update
    sudo apt install cpulimit
    # Start your bazel build in one terminal, then in a separate terminal, run the following.
    # Replace <pid> with the Process ID number for your bazel build server process (usually
    # just called "java" when you look at it with `ps`, `top`, `htop`, or `gnome-system-monitor`).
    cpulimit -p <pid> -l 500 # limit your bazel build to 62.5% max CPU usage on an 8-core machine <=====

Leave the `cpulimit` process running as long as you want this limiting effect in place. You don't need to restart it each time you begin a new bazel build, as the bazel build server continues running in the background even after a build completes.


== Set process priority: ==
An ALTERNATIVE TO (OR PARTNER TECHNIQUE to use in conjunction with) the `cpulimit` command above:

nice
    "run a program with modified scheduling priority"; ie: modify process priority in Linux to give one process priority over another
    For help, tutorial, and examples, see: https://www.tecmint.com/set-linux-process-priority-using-nice-and-renice-commands/

renice
    See: https://www.tecmint.com/set-linux-process-priority-using-nice-and-renice-commands/

- For `chrt` (Change Real-time) help, see my answer here!: https://stackoverflow.com/a/71757858/4561887

sudo chrt --rr 1 my_prog
    <============
    call `my_prog` with SCHED_RR with lowest priority of 1
    See my answer here: https://stackoverflow.com/a/71757858/4561887
sudo chrt --rr 99 my_prog
    call `my_prog` with SCHED_RR with highest priority of 99
    See my answer here: https://stackoverflow.com/a/71757858/4561887
sudo chrt --fifo 1 my_prog
    call `my_prog` with SCHED_FIFO with lowest priority of 1
    See my answer here: https://stackoverflow.com/a/71757858/4561887
sudo chrt --fifo 99 my_prog
    call `my_prog` with SCHED_FIFO with highest priority of 99
    See my answer here: https://stackoverflow.com/a/71757858/4561887
chrt -p 12345
    <============
    Read what the current real-time scheduler and priority are for process ID (PID) 12345. 
    Sample calls and their output:
            $ chrt -p 1431
            pid 1431's current scheduling policy: SCHED_OTHER
            pid 1431's current scheduling priority: 0

            $ chrt -p 1433
            pid 1433's current scheduling policy: SCHED_RR
            pid 1433's current scheduling priority: 1


== Mosh: ==
An ssh-replacement program for better connections over wifi, cellular, and long-distance links. It is free software (GNU GPLv3)!
It can decrease response time by a factor of 30~50 on lossy networks (see Wikipedia article below)! Ex: 16.8 seconds response time --> 0.33 seconds, or 5.9 --> 0.19 sec.

References:
1. https://mosh.org/#getting
2. https://en.wikipedia.org/wiki/Mosh_(software)


== Find files and replace text in files: ==
[find and replace, text replacement in files]

1)
which <some_executable>
    show the path to the executable in your path; ex:
        $ which locate
        /usr/bin/locate
2)
locate <some_name>
    find all files with "some_name" in their path or filename, searching EVERYWHERE, starting at the root dir (/)! Note: to search just in the current dir and below, use `find` instead:
        find | grep <some_name>
3)
find
    recursively find and print the relative path to all files and directories in the current directory and below

find -type f
    recursively find only files (NOT directories)
find some_dir -not -type d | sort -V
    Recursively find anything that is NOT a directory (`-not -type d`), then sort the output list of files. This essentially just finds files and file symlinks and things.    
    Keywords: find only files; find exclude directories; find exclude things; find not; not find; exclude find

find | grep "my_file"
    find any file with "my_file" in its name
find -L | grep "my_file"
    same as above, but also follow symbolic links when searching

find | grep ".*\.txt$"
    find any file which MUST END WITH .txt (the $ searches for an "end of line" character to ensure what's just before it is only at the very end of a string)

find | grep -E ".*(\.ino|\.cpp|\.c|\.h|\.hpp|\.hh)"
    find any file with one of these extensions

find -L build/bin | grep -ni some_filename
    quickly find a newly-built output file (such as an auto-generated source file created by some Bazel `genrule()`) inside of Bazel's output build dir, "build/bin". Note the `-L` to force `find` to follow symbolic links. This is required since Bazel makes all dirs in "build", such as "bin", simlinks. <======== VERY HELPFUL TO QUICKLY FIND A BAZEL BUILD OUTPUT FILE! ==========

`sed`:
sed -i "s|regex_pattern_to_match|replacement_string|g" my_file.txt
    'g'lobally replace (ie: replace all matching occurrences) of "regex_pattern_to_match" 'i'n place in my_file.txt, replacing the matching pattern with "replacement_string"

PUTTING IT ALL TOGETHER:
References:
1. https://linuxize.com/post/how-to-use-sed-to-find-and-replace-string-in-files/
1. https://unix.stackexchange.com/questions/159367/using-sed-to-find-and-replace/159369#159369 (also see my comment under this answer!)
1. *****https://stackoverflow.com/questions/10445934/change-multiple-files/30717770#30717770
1. *****Really good sed reference! https://www.grymoire.com/Unix/Sed.html

find some/path -type f | grep -E ".*(\.ino|\.cpp)" | xargs sed -i "s|regex_pattern|replacement_string|g"
    find all files in some/path which end in .ino or .cpp and pipe them to sed. sed will then find and replace all matches of "regex_pattern" with "replacement_string" in these files. <======= BEST NON-WHOLE-WORD MULTI-FILE SEARCH & REPLACE =====
    EXAMPLE:
        find src/arduino -type f | grep -E ".*" | xargs sed -i "s|printf|sprintf|g"

To match whole words, use the regex `\b` word boundaries!
- See: https://www.oreilly.com/library/view/regular-expressions-cookbook/9781449327453/ch02s06.html
find some/path -type f | grep -E ".*(\.ino|\.cpp)" | xargs sed -i "s|\bregex_pattern\b|replacement_string|g"
    same as above, except with `\b` `\b` to make it a whole word search! <======= BEST WHOLE-WORD MULTI-FILE SEARCH & REPLACE =====
    EXAMPLE:
        find src/arduino -type f | grep -E ".*" | xargs sed -i "s|\bprintf\b|sprintf|g"

Ripgrep can find and replace too!
[rg, ripgrep, rip-grep, ripgrep replace in-place, rg replace]
See "Andrew Gallant's Blog", the post titled [ripgrep is faster than {grep, ag, git grep, ucg, pt, sift}](https://blog.burntsushi.net/ripgrep/). Ex:
rg '([A-Z][a-z]+)\s+([A-Z][a-z]+)' --replace '$2, $1'
    Find all strings which match the pattern in single quotes (''), and replace them with the matching groups in the format '$2, $1', where `$2` is the 2nd matching group (2nd set of parenthesis in the main regular expression), and `$1` is the 1st matching group (1st set of parenthesis in the main regular expression).
    - See: https://blog.burntsushi.net/ripgrep/
    - Note that this does NOT do the replacement in the file! It does the replacement in the stdout output only. To replace actual contents of a file, see here: https://learnbyexample.github.io/substitution-with-ripgrep/#in-place-workaround
      Ex:
            # same as: `sed -i 's/blue/red/g' ip.txt` 
            #       or `sed -i 's|blue|red|g' ip.txt`
            rg --passthru 'blue' -r 'red' ip.txt > tmp.txt && mv tmp.txt ip.txt
sed -i 's|blue|red|g' ip.txt
    Replace all instances of "blue" in file "ip.txt" with "red".
rg --passthru 'blue' -r 'red' ip.txt > tmp.txt && mv tmp.txt ip.txt
    Same as above, but using `rg` ripgrep instead of `sed`! This technique uses an intermediate temporary file.
file_contents="$(rg --passthru 'blue' -r 'red' ip.txt)" && printf "%s" "$file_contents" > ip.txt
    <========= MY APPROACH; BETTER THAN JUST ABOVE I think ==========
    Same as above, but use `rg` and do NOT use an intermediate temporary file!

eRCaGuy_dotfiles/useful_scripts/find_and_replace.sh: usage:
find_and_replace <path> <filename_regex> <string_regex> <replacement_str> [-w]
    find and replace `string_regex` with `replacement_str` for all filenames which match `filename_regex` in path `path`. See `gs_find_and_replace -h` for help and more examples!

== sed: ==
sed = "'s'tream 'ed'itor for filtering and transforming text" [stream editor]
See also the `sed -i` examples just above!

References:
See also the 4 References for sed just above, underneath "PUTTING IT ALL TOGETHER"!
1. *****[explains how to use regex groups () and \1 \2 \3 etc to reference those groups!] https://unix.stackexchange.com/questions/78625/using-sed-to-find-and-replace-complex-string-preferrably-with-regex/78626#78626
1. How to use sed to find and replace text in files in Linux / Unix shell - https://www.cyberciti.biz/faq/how-to-use-sed-to-find-and-replace-text-in-files-in-linux-unix-shell/

Basic usage:
sed -E 's/regexp_search/replacement_str/g' my_file.txt = in my_file.txt, do a 'g'lobal 's'tring replacement, replacing all matches of regular expression regexp_search with "replacement_str".


== wc: ==
wc = 'w'ord 'c'ount

find | wc -l = count and return the number of 'l'ines returned by find, which corresponds to the number of files and folders in a directory and its sub-directories.


== tr: ==
tr = 'tr'anslate or delete characters
<your_command> | tr -d ',' = remove all commas from the output of `your_command`; see: https://stackoverflow.com/questions/12668020/removing-characters-from-grep-output/12668078#12668078

echo $PATH
    View all paths in your system path, in order. These are the directory paths, in this order, in which Linux searches for your executables to run on the command-line. 
echo $PATH | tr ':' '\n'
    <==============
    View all paths in your PATH, in order, on their own unique line! 
    Note that `tr ':' '\n'` replaces all ':' chars with a newline ('\n') char.
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc && . ~/.bashrc
    <==============
    Add the ~/bin dir to your PATH and then re-source it to ensure it has been added. Useful for manually installing things (executables) in Linux! 
    See the top of my answer: https://stackoverflow.com/a/61997003/4561887

== Basic Process profiling in Linux: ==

cat /proc/<process_ID>/sched = show some profiling/scheduler stats for this process ID (PID) on Linux, including how many threads it has!
ls /proc/<process_ID>/task/ = list the threads in this process!
ls /proc/*/task = list the threads in all multi-threaded processes!


== ==

qpdf --decrypt in.pdf out.pdf
    "decrypt"/unlock (cannot truly decrypt/unlock if it requires a password, but works perfectly for "soft locked" documents which do not!) in.pdf, saving its unlocked/"decrypted" form as out.pdf so that you can now edit it with Foxit Reader or whatever! Nice! Now I can create bookmarks, highlight, underline, take notes, and then save these markups!
    - Once I do this, I like to rename "out.pdf" to "some useful name [`qpdf --decrypt`ed]" so I can remember right in the name itself how I did this!
    [pdf decrypt pdf --decrypt pdf unlock pdf remove pw from pdf remove password from pdf]

[keywords: file password encryption, document password encryption; encrypt decrypt; encryption decryption; document encryption; encrypt document; encrypt file; document encryption; file encryption; pgp]
gpg -c myfile.txt
    <===========
    encrypt myfile.txt with a passphrase (symmetric 'c'ipher); a GUI window will pop up, asking you for a password to encrypt the file; enter a password, then it will ask you again; once you enter the password again it will encrypt the file and create a new file called myfile.txt.gpg. You will need to manually delete the old file.
gpg myfile.txt.gpg
    decrypt myfile.txt.gpg back into myfile.txt; it will ask you for the password which was originally used to encrypt it!
    - See here for details and where I learned this! https://www.lifewire.com/encrypt-decrypt-password-protect-files-linux-4582604
    [gpg extract gpg decrypt]

timeout [options] <duration> <command>
    "Start COMMAND, and kill it if still running after DURATION." 
    See `man timeout`.
    Example usage: search this document for `timeout 0.2`. See also my answer here: https://stackoverflow.com/a/73297645/4561887
timeout 0.5s sleep 5
    Kill `sleep 5` after 0.5 sec, causing it to return early!
time timeout 0.5s sleep 5
    <=======
    Same as above, except also prove that it was killed after almost exactly 0.5 sec.

binwalk
[keywords: extract compressed zip .tar.gz file too; extract unzip binary; extract binary]
- See also: search this document for "tar -xf".
- useful for reverse engineering, hacking, and penetration testing, as well as just extracting zip files and other compressed images whose format you may not easily recognize!
- "Binwalk is a tool for searching a given binary image for embedded files and executable code. Specifically, it is designed for identifying files and code embedded inside of firmware images." (https://www.kali.org/tools/binwalk/)
---
sudo apt install binwalk
    Install it.
binwalk path/to/file.bin
    Search binary file "file.bin" for "binay images" of "embedded files and executable code." ie: Show what files can be extracted from within this binary file.
    See:
    1. `man binwalk` and
    1. https://programmingwithstyle.com/posts/howihackedmycar/
binwalk -e path/to/file.bin
    <========== VERY USEFUL! ==========
    Same as above, but actually extract (`-e`, or `--extract`) files from within binary file "file.bin"! This automatically creates an appropriately-named folder it places all extracted contents into!
    See:
    1. `man binwalk` and
    1. https://programmingwithstyle.com/posts/howihackedmycar/
binwalk --dd='.*' path/to/file.bin
    <========== VERY USEFUL! ==========
    Ex: `binwalk --dd='.*' music.mp3`
    Extract contents from non-compressed binary files, such as a Windows executable (.exe) file, a .mp3 music file, etc. 
    See: https://stackoverflow.com/a/36635022/4561887
    TODO: study what the `--dd='.*'` part above means!
    NB: use this cmd in conjunction with the Gnome "Archive Manager" GUI (`file-roller`) to extract contents and .data, .rdata. .reloc, .text, etc. sections from a Windows .exe files, as well as resources like bitmaps (images), icons, version numbers, etc.! <========== VERY USEFUL! Extract contents from a Windows .exe file ==========

[address to line; address 2 line; find address of exception handler in C or Cpp C++ source code]

addr2line -e path/to/binary 0xabcdef
    Map address 0xabcdef in binary file /path/to/binary to a line number in the source code which generated this binary file.
    See: 
    ```
    man addr2line 
    addr2line -h
    ```
addr2line path/to/my_binary.elf 0xabcdef
    Map address 0xabcdef in binary file /path/to/my_binary.elf to a line number in the source code which generated this binary file.
    See just above. 

[Mount/remount/unmount/umount filesystem or file image; mount remount]
> If no part of your filesystem is writable by default, then you may need to unmount it and remount it as read-writable (rw) first, as shown below. ... When done, you can mount it back as read-only (ro) as shown here:
See my answer: https://serverfault.com/a/1105451/357116
---
mount -o remount,rw /
    <======== REMOUNT AS READ-WRITE ========
    Remount your root dir (/) as read-writable (rw)
    - Useful for embedded Linux boards.
    - See my answer: https://serverfault.com/a/1105451/357116
mount -o remount,ro /
    <====== REMOUNT BACK AS READ-ONLY ======
    Remount your root dir (/) as read-only (ro)
    - Useful for embedded Linux boards.
    - See my answer: https://serverfault.com/a/1105451/357116

`compgen` References:
[Note: "compgen" apparently stands for (auto)-"completion generator"]
1. [my answer & links] https://unix.stackexchange.com/a/715426/114401
1. https://unix.stackexchange.com/a/120825/114401
   `compgen -A <cmd>`
1. https://unix.stackexchange.com/a/23919/114401
1. Manual pages
    ```bash
    compgen --help
    help compgen  # same output as above.
    man bash      # and search for "compgen"; see especially the "-A action"
                  # documentation section under the "complete" command
                  # under "compgen"; all of the "complete -A action" commands
                  # apply equally to `compgen` too!
    ```
---
[tab tab replacement; tab tab autocompletion]
compgen -c gs_
    Run (auto) "completion generator" on partial command "gs_" to output all possible commands as though you had typed "gs_" and then pressed Tab Tab to auto-complete the list of possible commands! This is useful to script things or to pipe to `grep`, for instance. See:
    1. https://unix.stackexchange.com/a/23919/114401 - Unix & Linux: How to pipe the list of commands displayed by "tab complete"?
    1. `help compgen`
    1. `man bash` and search for "compgen"
compgen -c gs_ | grep git
    Search all commands/executables in my PATH for commands which begin with "gs_" and contain the word "git" in them! See: 
    1. https://unix.stackexchange.com/a/23919/114401 - Unix & Linux: How to pipe the list of commands displayed by "tab complete"?
compgen -A command <cmd>
    Same as `compgen -c <cmd>`.
    See: `man bash` and search for "compgen" and "-A action".
compgen -f /etc/
    Auto-complete lists of **file names** (`-f`) as though you had typed `/etc/` and then pressed Tab Tab (tab twice).
compgen -A file /etc/
    Same as above.  
    See: `man bash` and search for "compgen" and "-A action".
compgen -c | sort -V
    <====== VERY USEFUL =======
    List ALL possible executable commands and aliases, sorted. 
compgen -A command | sort -V
    Same as above. 
    See: `man bash` and search for "compgen" and "-A action".
compgen -a | sort -V
    <=======
    List all possible aliases only, sorted. See also `compgen -c`, which lists executable commands **plus** aliases. 
compgen -A alias | sort -V
    Same as above.
    See: `man bash` and search for "compgen" and "-A action".
compgen -b | sort -V
    <=======
    List all possible shell builtin commands, sorted. 
compgen -A builtin | sort -V
    Same as above. 
    See: `man bash` and search for "compgen" and "-A action".
OTHER `compgen -A <cmd>` COMMANDS FROM `man bash`:
    -A action
          The action may be one of the following to generate a list of possible completions:
          alias   Alias names.  May also be specified as -a.
          arrayvar
                  Array variable names.
          binding Readline key binding names.
          builtin Names of shell builtin commands.  May also be specified as -b.
          command Command names.  May also be specified as -c.
          directory
                  Directory names.  May also be specified as -d.
          disabled
                  Names of disabled shell builtins.
          enabled Names of enabled shell builtins.
          export  Names of exported shell variables.  May also be specified as -e.
          file    File names.  May also be specified as -f.
          function
                  Names of shell functions.
          group   Group names.  May also be specified as -g.
          helptopic
                  Help topics as accepted by the help builtin.
          hostname
                  Hostnames, as taken from the file specified by the HOSTFILE shell variable.
          job     Job names, if job control is active.  May also be specified as -j.
          keyword Shell reserved words.  May also be specified as -k.
          running Names of running jobs, if job control is active.
          service Service names.  May also be specified as -s.
          setopt  Valid arguments for the -o option to the set builtin.
          shopt   Shell option names as accepted by the shopt builtin.
          signal  Signal names.
          stopped Names of stopped jobs, if job control is active.
          user    User names.  May also be specified as -u.
          variable
                  Names of all shell variables.  May also be specified as -v.


END OF = Linux (General): =


====================================================================================================
= syslog-ng: =
====================================================================================================
[and logrotation log rotation logrotate.d; = logrotate: =]

Features & Notes:
1. `syslog-ng` is a Linux logging replacement alternative for `syslog`. It is apparently more-powerful and can automatically send Linux logs to remote logging servers for remote storage, viewing, and retrieval. 
1. It is available on Buildroot for embedded Linux boards.
    1. Its default configuration file on Buildroot is here, for instance: https://github.com/buildroot/buildroot/blob/master/package/syslog-ng/syslog-ng.conf. Notice that the kernel logs are collected in the source via the `/proc/kmsg` file. Read more about that file here: https://unix.stackexchange.com/a/585922/114401. 
        ```
        @version: 3.37

        source s_sys {
            file("/proc/kmsg" program_override("kernel"));
            unix-stream ("/dev/log");
            internal();
        };

        destination d_all {
            file("/var/log/messages");
        };

        log {
            source(s_sys);
            destination(d_all);
        };
        ```
1. Note that if using syslog-ng to forward logs to a remote server, you should probably forward both the kernel logs from `/proc/kmsg` or `/dev/kmsg` (see: https://unix.stackexchange.com/questions/585919/what-is-the-difference-between-proc-kmsg-and-dev-kmsg/585922#585922) **and** whatever custom daemon or custom process logs your programs produce. 
1. Apparently (I need to research this some more) systemd, a modern Linux kernel startup service, and alternative to SysvInit and Runit, can also push and manage remote logging? 
    1. Research what systemd service can do this, and how it works!
1. For log rotation, see, for instance, here: 
    1. https://www.networkworld.com/article/3218728/how-log-rotation-works-with-logrotate.html
    1. https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.17/administration-guide/32
        > When using this destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large.
        > 
        > Also, after rotating the log files, reload syslog-ng OSE using the `syslog-ng-ctl reload` command [GS: see below], or use another method to send a `SIGHUP` to syslog-ng OSE.
    1. See logrotated (log rotate daemon) configuration files in the "/etc/logrotate.d" dir via: `ls /etc/logrotate.d`. Ex: 
        ```bash
        cat /etc/logrotate.d/rsyslog  # on Ubuntu
        # OR perhaps:
        cat /etc/logrotate.d/syslog   # perhaps on an embedded Linux device
        ```

Logrotate/Log rotation:
References:
    1. `man logrotate` - see also the example files here
        1. https://linux.die.net/man/8/logrotate
        1. https://man7.org/linux/man-pages/man8/logrotate.8.html
    1. `cat /etc/logrotate.conf` - see what's in the master logrotate file on your Ubuntu or embedded Linux machine.
    1. `ls -1 /etc/logrotate.d` - list all logrotate files which will be included by the main "/etc/logrotate.conf" file.

1. Sample main logrotate file on Ubuntu:
    Notice that the `include /etc/logrotate.d` line below is what includes all other custom logrotate configuration files from the "/etc/logrotate.d/" dir!

    `cat /etc/logrotate.conf`:
    ```bash
    # see "man logrotate" for details
    # rotate log files weekly
    weekly

    # use the syslog group by default, since this is the owning group
    # of /var/log/syslog.
    su root syslog

    # keep 4 weeks worth of backlogs
    rotate 4

    # create new (empty) log files after rotating old ones
    create

    # uncomment this if you want your log files compressed
    #compress

    # packages drop log rotation information into this directory
    include /etc/logrotate.d

    # no packages own wtmp, or btmp -- we'll rotate them here
    /var/log/wtmp {
        missingok
        monthly
        create 0664 root utmp
        rotate 1
    }

    /var/log/btmp {
        missingok
        monthly
        create 0660 root utmp
        rotate 1
    }

    # system-specific logs may be configured here
    ```
1. Sample rsyslog logrotate file on Ubuntu:
    `cat /etc/logrotate.d/rsyslog`:
    ```bash
    /var/log/syslog
    {
        rotate 7
        daily
        missingok
        notifempty
        delaycompress
        compress
        postrotate
            /usr/lib/rsyslog/rsyslog-rotate
        endscript
    }

    /var/log/mail.info
    /var/log/mail.warn
    /var/log/mail.err
    /var/log/mail.log
    /var/log/daemon.log
    /var/log/kern.log
    /var/log/auth.log
    /var/log/user.log
    /var/log/lpr.log
    /var/log/cron.log
    /var/log/debug
    /var/log/messages
    {
        rotate 4
        weekly
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
        postrotate
            /usr/lib/rsyslog/rsyslog-rotate
        endscript
    }
    ```
1. Sample configuration of an "/etc/logrotate.d/syslog-ng" file for **`syslog-ng`** on an embedded Linux board. 
    This will keep 7 rotated log files (ex: "/var/log/messages" + ["/var/log/messages.1", "/var/log/messages.2", etc., through "/var/log/messages.7", inclusive]), rotating them and manually restarting `syslog` every time the size of the active log file ("/var/log/messages") hits 20 MB. 
    Sample "/etc/logrotate.d/syslog-ng" logrotate config file:
    See my notes & example here: https://github.com/syslog-ng/syslog-ng/issues/1774#issuecomment-1270517815
    ```bash
    /var/log/auth.log 
    /var/log/user.log
    /var/log/messages  
    {
        rotate 7
        size 20M
        delaycompress
        missingok
        # Required for syslog-ng after each rotation, to cause it to reopen log files so it can begin
        # logging to the new log file under a new file descriptor, rather than to the old log file
        # which has now been rotated and renamed. 
        postrotate
            # After rotating the log files, cause syslog-ng to reopen the destination log files so it
            # will log into the newly-created log files rather than into the now-rotated and renamed 
            # ones.
            #
            # This ensures, for example, that syslog-ng will move its file descriptor to begin logging
            # into the main "/var/log/messages" log file again, instead of into the
            # now-rotated "/var/log/messages.1" file, which the old file descriptor (fd) is now
            # pointing to since that fd's filename was just renamed from "/var/log/messages"
            # to "/var/log/messages.1" during the log rotation.

            # Option 0 (no longer recommended): call the heavier `reload` command after log rotation
            # syslog-ng-ctl reload

            # Option 1 (recommended): call the new `reopen` command after log rotation
            syslog-ng-ctl reopen

            # Option 2 (same thing as Option 1 above): send the `SIGUSR1` kill signal to the 
            # running `syslog-ng` process
            # pid="$(cat /var/run/syslog-ng.pid)" kill -SIGUSR1 $pid
        endscript
    }
    ```
    See `man 8 logrotate` for some example configuration files, similar to the above. 
    See that manual page online here: https://linux.die.net/man/8/logrotate. 
    All of the above logrotate.d/ configuration file parameters are described in the manual pages above.
1. See also the default Buildroot configuration file for the logrotate daemon for the syslog (or syslog-ng) "/var/log/messages" file, here!: https://github.com/buildroot/buildroot/blob/master/package/logrotate/logrotate.conf :
    /etc/logrotate.conf:
    ```
    compress

    include /etc/logrotate.d

    /var/log/messages /var/log/auth.log /var/log/user.log {
        rotate 7
        daily
        delaycompress
        missingok
        sharedscripts
        postrotate
            /usr/bin/killall -HUP syslogd
        endscript
    }
    ```

(Gernally Paid), Remote-logging Servers:  
Possible paid-as-a-service log servers you can log to include, for example:
1. Humio: https://www.humio.com/
    1. If I ever want to try logging my Arduino sensor smart home data or something, Humio Community Edition offers FREE logging indefinitely (no limited trial period), with the following features and limitations. See: https://www.humio.com/getting-started/:
        > Humio Community Edition  
        > Unleash the power of streaming observability at no cost.
        > 
        > Ingest up to 16GB per day  
        > 7-day retention  
        > Ongoing usage with no trial period and no credit card required  
1. Sumo Logic: https://www.sumologic.com/
1. (Maybe free if you host your own Redwood server?) RedwoodJS logging server: https://redwoodjs.com/docs/logger

Syslog-ng References:
1. Main website/manual ex. pg: https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.17/administration-guide/32 
1. logrotate and "/etc/logrotate.d/<config_files>": https://linux.die.net/man/8/logrotate


Commands:

syslog-ng-ctl --help
    See the "syslog-ng control" help menu on any Linux system running syslog-ng for internal logging, such as on an embedded Linux board. 
syslog-ng-ctl reload
    Reload the syslog-ng service. This must be called each time your log rotate daemon rotates the logs in the "/var/log/messages" files, for instance. 
    See: 
    https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.17/administration-guide/32
    Update: use the lighter-weight `syslog-ng-ctl reopen` after log rotation instead! See my comments:
    https://github.com/syslog-ng/syslog-ng/issues/1774#issuecomment-1270517815
syslog-ng-ctl reopen
    <=============
    Reopen log files being written to by `syslog-ng`. Call this after each `logrotate` log rotation! See my notes here:
    https://github.com/syslog-ng/syslog-ng/issues/1774#issuecomment-1270517815
syslog-ng-ctl export-config-graph | jq .
    View the syslog-ng configuration graph of all settings and source to destination logs configured. Pipe it to JQuery (`jq`) to view it in a pretty, human-readable JSON format. 
    See: `syslog-ng-ctl --help`
syslog-ng-ctl config
    View the currently-loaded syslog-ng.conf configuration file. It will likely match what is in "/etc/syslog-ng.conf", since that is where the configuration file is stored. See:
    1. `syslog-ng-ctl --help`
    1. `cat /etc/syslog-ng.conf`

sv restart my-runit-started-process
    Tell `runsv`, the runit server (apparently), to restart the "my-runit-started-process" service, which was previously started by runit!
    See also: `man sv`.
sv status my-runit-started-process
    See the PID and status of the runit-managed-and-started service named "my-runit-started-process". Example output:
    ```
    run: my-runit-started-process: (pid 1319) 1381s; run: log: (pid 1276) 1381s
    ```
    TODO: find out: what is the meaning of the "log pid" above?? Why is one PID 1276 and the other is 1319?
    See also: `man sv`.


====================================================================================================
= rsync: =
====================================================================================================
[keywords: copy, copies, copying, copying with progress bar]

References:
1. [my ans 1] https://askubuntu.com/questions/17275/how-to-show-the-transfer-progress-and-speed-when-copying-files-with-cp/1275972#1275972
1. [my ans 2] https://superuser.com/questions/1271882/convert-ntfs-partition-to-ext4-how-to-copy-the-data/1464264#1464264 - includes info. on FreeFileSync (FFSync; Free File Sync) too!

1. BASICS:

time rsync -rah --dry-run --info=progress2 --stats source destination
    <========= MY FAVORITE BASIC **DRY-RUN** RSYNC COMMAND ==========
    My favorite `--dry-run` command; do a **dry run** "archival" copy (ie: including all Linux file/folder permissions) from source to destination. 
    See: [my ans] https://askubuntu.com/a/1275972/327339
time rsync -rah --dry-run --info=progress2 --stats source/ destination/
    [version WITH trailing slashes! (`/`)] Dry-run copy the **contents of** "source/" dir to be within the **contents of** "destination/" dir, rather than creating a new folder in the destination dir at path "destination/source", as would be done with_out_ the trailing slashes (`/`)!
time rsync -rah --info=progress2 --stats source destination
    <================ MY FAVORITE BASIC RSYNC COMMAND =================
    Do an "archival" copy (ie: including all Linux file/folder permissions) from source to destination.
    (Important! Do a dry run first, as shown above, and read the output summary to ensure you're copying what you intend!)
    My favorite command, AFTER running the `--dry-run` version just above first!; do a **real copy**.  
    - See my ans: 
      https://askubuntu.com/questions/17275/how-to-show-the-transfer-progress-and-speed-when-copying-files-with-cp/1275972#1275972
time rsync -rah --compress --info=progress2 --stats source destination
    <======== WITH COMPRESSION (DEFAULT COMPRESSION LEVEL IS 6)! USE THIS! ==========
    Also does the default level of compression (6 of 9) during the send in order to save bandwidth over a slow network, at the cost of CPU cycles on each end to compress and decompress. 
    I'm not sure whether level 6 (default compression) or level 9 (maximum compression) is faster over a network of 20 Mbps to 200 Mbps, but I think the default level 6 is probably fastest, so probably just stick to it for now!
    See: 
    1. https://serverfault.com/a/1055177/357116
    2. `man rsync` and search for "compress-level".
time rsync -rah --compress-level=9 --info=progress2 --stats source destination
    <======== WITH MAXIMUM COMPRESSION (SETTING TO LEVEL 9)! ==========
    Does the maximum level of compression during the send in order to save bandwidth over a slow network, at the cost of CPU cycles on each end to compress and decompress.
    I'm not sure whether level 6 (default compression) or level 9 (maximum compression) is faster over a network of 20 Mbps to 200 Mbps, but I think the default level 6 is probably fastest, so probably just stick to it for now!
    See: 
    1. https://serverfault.com/a/1055177/357116
    2. `man rsync` and search for "compress-level".
time rsync -rah --compress --info=progress2 --stats my_username@192.168.0.1:~/some_dir ~
    <========================= ALSO COMPRESS, AND SEND OVER NETWORK ===========================
    Copy the "~/some_dir" directory over ssh from some remote target PC to my local PC's home dir, while using compression to reduce network bandwidth usage!

2. ADVANDED:

--delete --delete-excluded [--dry-run]
    CAREFUL!: Add the `--delete --delete-excluded` flags to also delete files and folders in the destination that are *not* in the source. This produces a true **image** from left to right rather than just an **update** or whatever from left to right. 
    Always run with `--dry-run` first, to ensure you don't accidentally delete stuff in the destination which you'd like to keep.
    See my notes here: https://superuser.com/a/1464264/425838

3. MISC. NOTES:

Started 10 June 2019.

TODO


====================================================================================================
= zip file compression, incl. gzip, tar, xz file and folder compression, etc.: =
====================================================================================================

References:
1. *** Proves xz is best: https://www.privex.io/articles/which-compression-algorithm-tool
1. **** How to use xz: https://www.baeldung.com/linux/xz-compression
1. ***** great `xz` compress and decompress examples in Linux!: https://www.rootusers.com/13-simple-xz-examples/
1. See also `binwalk`! Search this document for that tool! <======

TODO: ADD A Q&A ON HOW TO DO THIS TO UNIX & LINUX STACK EXCHANGE!---NOPE! ON PERSONAL WEBSITE INSTEAD!

TODO: improve these descriptions below, test all the commands below, and continue working on documenting the best xz compression commands, below.
time xz -9 -v -T0 "CFFFP_IMG_20201027_183202_cropped 1 [10 vectors per pixel].3mf"
    regular replace
    See: https://www.rootusers.com/13-simple-xz-examples/
time xz -9e -v -T0 "CFFFP_IMG_20201027_183202_cropped 1 [10 vectors per pixel].3mf"
    extreme replace
    See: https://www.rootusers.com/13-simple-xz-examples/
time xz -9e -v -T0 -k "CFFFP_IMG_20201027_183202_cropped 1 [10 vectors per pixel].3mf"
    extreme keep
    See: https://www.rootusers.com/13-simple-xz-examples/
time xz -9e -v -T0 -c "CFFFP_IMG_20201027_183202_cropped 1 [10 vectors per pixel].3mf" > out.3mf.xz
    extreme keep and save output in custom output file
    See: https://www.rootusers.com/13-simple-xz-examples/
TODO: integrity test
tar .......... [TODO]
    See:
    1. *****https://www.rootusers.com/13-simple-xz-examples/
    1. *****+ [better article for this **one** `tar` example is all!, since it shows hot to use the `tar --use-compress-program='some_program'` option!] 
       https://www.baeldung.com/linux/xz-compression

------------
GNU `tar`: compression and decompression algorithm. 
[decompress .tar.gz decompress .tar.xz decompress tar decompress xz decompress gz files tar xz tar -xz tar gz tar -gz, xz compression xz decompression]
------------
See:
    1. *****+ https://askubuntu.com/a/107976/327339 - How do I uncompress a tarball that uses .xz?
    1. ***** `man tar`
    1. ***** GNU tar user manual: https://www.gnu.org/software/tar/manual/tar.html
    1. https://www.cyberciti.biz/faq/how-to-extract-tar-xz-files-in-linux-and-unzip-all-files/
    1. Extract contents to an alternate target directory via `-C`: 
        1. Google search for "tar extract single file to new location": https://www.google.com/search?q=tar+extract+single+file+to+new+location&oq=tar+extract+single+file+to+new+location&aqs=chrome.0.69i59.208j0j9&sourceid=chrome&ie=UTF-8
        1. https://www.tecmint.com/extract-tar-files-to-specific-or-different-directory-in-linux/
    1. https://unix.stackexchange.com/questions/61461/how-to-extract-specific-files-from-tar-gz
A few common options of interest, from `man tar`:
       -x, --extract, --get
              Extract files from an archive.  Arguments are optional.  When given, they specify names of the archive members to be extracted.
       -c, --create
              Create a new archive.  Arguments supply the names of the files to be archived.  Directories are archived recursively, unless the --no-recursion option is given.
       -f, --file=ARCHIVE
           [GS: Specify the file or archive]
       -J, --xz
              Filter the archive through xz(1).
       -v, --verbose
              Verbosely list files processed.
       -z, --gzip, --gunzip, --ungzip
              Filter the archive through gzip(1).
       -t, --list
              List the contents of an archive.  Arguments are optional.  When given, they specify the names of the members to list.
       -C, --directory=DIR
              Change to DIR before performing any operations.  This option is order-sensitive, i.e. it affects all options that follow.
              [GS: use this option to save to a new directory. See: https://stackoverflow.com/a/9249779/4561887]

sudo apt install xz-utils
    Install the xz compression utilities used by `tar`.
    See: 
    1. https://askubuntu.com/a/107976/327339
    1. https://www.cyberciti.biz/faq/how-to-extract-tar-xz-files-in-linux-and-unzip-all-files/

time tar --xz -cf myarchive.tar.xz path/to/my/dir
    <====== COMPRESS =======
    <================ MOST COMMON ARCHIVE/COMPRESSION USAGE =================
    Use the 'xz' compression algorithm to compress all contents of directory "path/to/my/dir" into archive "myarchive.tar.xz"!
    See:
    1. `man tar`
    1. https://stackoverflow.com/a/18855909/4561887
time tar --gzip -cf myarchive.tar.gz path/to/my/dir
    <============ about 12x faster than .xz format (when compressing, per my testing) while taking up only ~10% more space! =============
    Same as above, but create a .tar.gz "gzip"-compressed file instead!
    See: https://linuxize.com/post/how-to-create-tar-gz-file/
    Same as:
    ```
    time tar -cfz myarchive.tar.gz path/to/my/dir
    ```
    ...since `-z` is equal to `--gzip`.
tar -xf path/to/file.tar.xz  
    <====== EXTRACT ========
    <============ MOST COMMON EXTRACTION/DECOMPRESSION USAGE =============
    Extract (`-x`) this file (`-f path/to/file`). Works with any file compression type (ex: .tar, .tar.gz, .tar.xz, etc.) since GNU tar automatically tries to identify the compression type! [Extract .tar.gz; unzip .tar.gz] 
    See: https://askubuntu.com/a/107976/327339
    See also:
        - `binwalk`--search this document for that! <========
tar -xf path/to/file.tar.xz --directory my_custom_output_dir
    <====== EXTRACT ========
    Same as above, but force the extraction of all files in the archive into directory "my_custom_output_dir".
    NB: watch the output directory grow, as a sort of "progress bar" or indicator, with:
    ```bash
    # In a **separate** terminal, watch the extraction progress by watching the output folder grow with:
    watch -n 1 'du -sh my_custom_output_dir'
    ```
tar -xf path/to/file.tar.xz -C my_custom_output_dir
    Same as above (`-C` means `--directory`).
tar -xf archive.tar
tar -xf archive.tar.gz
tar -xf archive.tar.xz  
    (x3) same as above.

tar -tf path/to/file.tar.xz
    <===== LIST CONTENTS ======
    List (`-t`, `--list`) all file contents of this archive file!
    See: 
    1. `man tar`
    1. https://www.cyberciti.biz/faq/how-to-extract-tar-xz-files-in-linux-and-unzip-all-files/

tar -xf file.tar.xz file1 file2 file3
    <===== EXTRACT SPECIFIED FILES ======
    Extract only file1, file2, and file3 from archive file file.tar.xz! See `man tar`:
    ```
    tar -x [-f ARCHIVE] [OPTIONS] [MEMBER...]
    ```
    Note: run `tar -tf path/to/file.tar.xz` first to list all files and directories inside this archive!
tar -xf git-filter-repo-2.38.0.tar.xz git-filter-repo-2.38.0/git-filter-repo
    <===== EXTRACT SPECIFIED FILES ======
    [Example of the command above] Extract only file "git-filter-repo-2.38.0/git-filter-repo" from the "git-filter-repo-2.38.0.tar.xz" xz-compressed archive file!
    See just above.


====================================================================================================
= Images and videos, incl. image and video compression and conversion: =
====================================================================================================
Was: = Image and video compression and conversion: =
[keywords: compressing videos, compressing images, compressing pictures, image/picture compression, compress images, compress imgs, compress photos, compressing photos, photo compression, compress videos, video compression, convert videos, converting videos, video conversion, image conversion, picture conversion, converting videos, converting images, converting pictures, convert pictures, convert images, convert videos, shrink pictures, shrink images]

== media info: ==
exiftool image.jpg
    <========== VERY USEFUL ==========
    Print out all metadata of an image, video, etc., including geo-tagging/geo-location info. for the image or media file
    See: https://askubuntu.com/a/249966/327339
exiftool image.jpg | grep 'GPS'
    Find GPS-based geo-tagging/geo-location info. for the image or media file!
    See: https://superuser.com/a/1370421/425838
mediainfo <image.jpg|song.mp3|video.mp4>
    <========== VERY USEFUL ==========
    Show various media info. (image/picture/sound/song/video, etc.) / metadata. 
    See: https://askubuntu.com/a/252775/327339.

== find large files: ==
[this is adjacently related to video conversion, as GitHub doesn't allow files > 100 MB in size (see: https://stackoverflow.com/questions/38768454/repository-size-limits-for-github-com/59479166#59479166), so you may need to find all files > 100 MB, then convert them down to a smaller size using `ffmpeg` as shown below if they are videos!]

find . -type f -size +100M
    find all files in the current directory that are larger than 100 MB! See: https://superuser.com/questions/204564/how-can-i-find-files-that-are-bigger-smaller-than-x-bytes/204571#204571

== Image resizing: ==
[resize image, resize picture, picture resizing]

convert in.png -resize 600x400 out.jpg
    resize to make the dimensions max 600x400, while still retaining proportional dimensions to the original image, while also converting from the (uncompressed I think?) PNG format to the compressed JPEG format. See: https://askubuntu.com/questions/271776/how-to-resize-an-image-through-the-terminal/271797#271797
convert in.png -resize 800x800 out.jpg
    same as above, but make the max dimension on either the x or y axis 800 pixels
convert in.png -resize 1920x1920 out.jpg
    same as above, but make the max dimension on either the x or y axis 1920 pixels
convert in.png -resize 1920x1080 out.jpg
    same as above, but make the max dimension on the x axis 1920 pixels and on the y axis 1080 pixels, like a standard, modern-day HD monitor or laptop!

== Image to monochrome (1-bit), for faxing: ==

Online Fax services:
1. https://faxzero.com/ - free for low-usage; or 1-time paid with Paypal for bigger or more faxes
1. https://www.fax.plus/ - low monthly fee
1. https://www.faxprices.com/ - tool to compare online fax services and prices; recommended by faxzero here: https://faxzero.com/faq.php

convert in.jpg -monochrome out1.jpg
    <===========
    <==== best overall (mild dithering, large file, to produce gray-scale effect) ======
    Produce a monochrome (1-bit) image for faxing.
    See: https://superuser.com/a/893488/425838
convert in.jpg -remap pattern:gray50 out2.jpg
    <==== highest quality (heavy dithering, huge file, to produce high-resolution gray-scale effect) ======
    Produce a monochrome (1-bit) image for faxing.
    See: https://superuser.com/a/893488/425838
convert in.jpg -threshold 50% out3.jpg
    <===========
    <==== cleanest and highest-contrast (NO DITHERING!, small file, uses threshold instead, no gray-scale effect; may lose data) ======
    Produce a monochrome (1-bit) image for faxing.
    See: https://superuser.com/a/405688/425838

== Image compression: ==
[picture compression, img compression]

REFERENCES:
1. https://github.com/ElectricRCAircraftGuy/PDF2SearchablePDF

convert -units PixelsPerInch in.jpg -resample 75 out3.jpg
    <========== COMPRESS/RESIZE/LOWER DPI OF IMAGE =========
    Resample the image to change the DPI to only 75 dots per inch. 
    See my answer here: https://superuser.com/a/1774209/425838

jpegoptim --size=500k dir_of_imgs/*.jpg
    compress a whole dir of images!
convert in.png -resize 1920x1080 out.jpg \
 && cp out.jpg out2.jpg \
 && jpegoptim --size=250k out2.jpg
    <========== VERY USEFUL ==========
    Resize in.png to a max of 1920x1080 pixels (while keeping correct dimensions and convering it to out.jpg), then copy out.jpg to out2.jpg, then optimize out2.jpg to be ~250KB!

Compress all the images, then convert all of them to a single, searchable PDF:
See: https://github.com/ElectricRCAircraftGuy/PDF2SearchablePDF

    jpegoptim --size=500k dir_of_imgs/*.jpg # compress the whole dir of images!
    pdf2searchablepdf dir_of_imgs           # now make 1 searchable pdf out of all of them!

For my particular case, with 7 jpeg images originally in the 2.5 to 3MB size range, the end result withOUT running jpegoptim first was a 20 MB PDF, which is too large to email! By calling `jpegoptim --size=500k` as shown above first, it shrunk the image size to approx. 500kB each, which meant the final PDF size was about 3.5MB instead of 20MB! Big improvement! Now I can email the file, and the images still look pretty good!

== Video compression: ==

sudo apt install ffmpeg
    install ffmpeg (required below)
sudo apt install vlc
    install the VLC media player GUI application to play the converted videos below

SUMMARY:
- libx265 (H.265) format crf values may be as high as 24 to 30 (higher values are lower quality).
- Note that HIGHER crf settings below yield SMALLER files because they are *lower* quality!

    # For "large" output files (usu. < 100 MB):
    time ffmpeg -i input.mp4 -vcodec libx265 -crf 24 output.mp4   <====== BEST FOR SLIGHTLY HIGHER QUALITY =======

    # For "small" output files (usu. < 50 MB):
    time ffmpeg -i input.mp4 -vcodec libx265 -crf 28 output.mp4   <=========== BEST FOR SMALLER FILES ============

DETAILS:
See: https://unix.stackexchange.com/questions/28803/how-can-i-reduce-a-videos-size-with-ffmpeg/38380#38380
ex:
time ffmpeg -i input.mp4 -vcodec libx265 -crf 28 output.mp4 = [PRODUCE "SMALL" VIDEO OUTPUT FILES!] convert input.mp4 to output.mp4 using the modern H.265 video format, which has EXCELLENT size vs quality! Reasonable compression (-crf) values for this libx265 (H.265) format may be as high as 24 to 30 (28 is good to make very small videos, but to get a touch more quality, use 24 instead!), with LOWER CRF values yielding HIGHER bitrates, and hence HIGHER quality videos! <============= WORKS REALLY WELL! ==============
- Using the above command: <============= MY FAVORITE TO GET VERY SMALL SIZES IN VIDEO OUTPUTS! ==================
    - a 110 MB 15 min video might take 25 minutes to convert (1/0.6 time factor to convert), and drop to as little as 35 MB!, and
    - a 125 MB 1min40sec video might take 5~6 minutes to convert (1/0.3 time factor to convert) and drop to as little as 5 MB!
    - a 503 MB 6 min .mov video might take 60 minutes to convert (on a slow computer [2-core/4-thread, Pentium i3 or similar], ~1/0.1, or 10x time factor to convert) and take as little as 32 MB when done! 32MB/503MB = ~6% of original size, or about 100% - 6% = 94% compression ratio!
        - Note: on a faster, modern computer [4-core/8-thread or 6-core/12-thread, Pentium i7 or similar] the whole conversion process might take only 4 to 10 minutes instead of 60 minutes! So, buy a nice computer.
time ffmpeg -i input.mp4 -vcodec libx265 -crf 24 output.mp4 = [PRODUCE "LARGE" VIDEO OUTPUT FILES!] exact same as above except with CRF of 24 instead of 28 in order to get a touch **higher quality** out of the video! <============ MY FAVORITE FOR SLIGHTLY HIGHER QUALITY! ===========

== QR codes: ==
[QR code generators; qr code generation; qr code readers; create qr code in Linux; linux create qr code]

References:
1. See my answer here: https://stackoverflow.com/a/70934014/4561887
1. See my demo here: "eRCaGuy_hello_world/bash/qrencode_send_text_to_phone.sh"
1. Where I first learned about `qrencode`: 
   https://www.linux-magazine.com/Online/Features/Generating-QR-Codes-in-Linux

sudo apt update && sudo apt install qrencode
    Install it.
qrencode -m 4 -o /tmp/qr.png "www.google.com" \
&& ((eog /tmp/qr.png &); sleep 1; rm /tmp/qr.png)
    <======= BEST CMD FROM A URL ========
    A 1-line cmd to make, open, and delete a QR code image from a URL.
    See my answer here: https://stackoverflow.com/a/70934014/4561887
cat "path/to/file.txt" | qrencode -m 4 -o /tmp/qr.png \
&& ((eog /tmp/qr.png &); sleep 1; rm /tmp/qr.png)
    <======= BEST CMD FROM A FILE ========
    A 1-line cmd to make, open, and delete a QR code image from an entire file.
    See my answer here: https://stackoverflow.com/a/70934014/4561887


====================================================================================================
= PDFs and PDF Manipulation: =
====================================================================================================
[PDFs:, pdf combine, combine pdfs, merge pdfs, make PDFs have searchable text, PDF OCR, PDF Optical Character Recognition, OCR in PDFs, OCR pdfs; split pdfs, extract pages from pdf, extract pgs from pdf; convert image to pdf]


FULL DEMO:
Convert a bunch of images into PDFs, then those PDFs into 1 combined PDF, then resize all pages to be "letter" (8.5 x 11 in) size, then make the whole thing searchable. This is how I converted all of my college transcripts & diplomas into a single, searchable PDF, for instance:
1. Optionally, manually create a .md markdown table of contents table at this point.
   Example contents:
   **table_of_contents.md:**
    ```markdown
    # Name of this document

    | Page  | Document              |
    | ----  | --------              |
    | 1     | Table of Contents     |
    | 2     | Image 1               |
    | 3     | Image 2               |
    | 4-5   | Some other pdf 1      |
    | 6     | Some other pdf 2      |
    ```
    Then, open up the .md file in Chrome using the "Markdown Viewer" app (https://chrome.google.com/webstore/detail/markdown-viewer/ckkdlimhmcjmikdlpkmbgfkaikojcbjk), and use it to convert the markdown file into a PDF by printing the output in Chrome to a PDF!
2. Convert all of the images to pdfs, combine them, make it searchable, etc.
    ```bash
    # 0. Convert any necessary images (ex: jpg or png, etc.) to PDF
    #    See `img2pdf`: https://stackoverflow.com/a/8955457/4561887
    img2pdf "img1.jpg" -o "img1.pdf"
    img2pdf "img2.jpg" -o "img2.pdf"

    # OR, a hacky work-around that works right now in pdf2searchablepdf version
    # 0.5.0:
    # See my issue/comment: 
    # https://github.com/ElectricRCAircraftGuy/PDF2SearchablePDF/issues/23
    mkdir -p temp \
        && cp "img1.jpg" temp \
        && pdf2searchablepdf temp \
        && mv "temp_searchable.pdf" "img1.pdf"
    mkdir -p temp \
        && cp "img2.jpg" temp \
        && pdf2searchablepdf temp \
        && mv "temp_searchable.pdf" "img2.pdf"
    # then manually delete the "temp" dir when done

    # 1. Generate the combined pdf from all of your pdfs
    #    See `pdfunite`: https://stackoverflow.com/a/11280219/4561887
    pdfunite \
    table_of_contents.pdf \
    img1.pdf \
    img2.pdf \
    'some other PDF1.pdf' \
    'some other PDF2.pdf' \
    combined.pdf

    # 2. resize all pages to "letter" (8.5 x 11 in) size
    # See `pdfjam`: https://superuser.com/a/1432848/425838
    pdfjam --outfile combined_resized.pdf --paper letter "combined.pdf"

    # 3. Make the combined and resized PDF searchable
    # See my `pdf2searchablepdf` repo: 
    # https://github.com/ElectricRCAircraftGuy/PDF2SearchablePDF
    pdf2searchablepdf combined_resized.pdf

    # 4. compress the PDF to be smaller
    # See my ans: https://askubuntu.com/a/1303196/327339
    gs -sDEVICE=pdfwrite -dPDFSETTINGS=/printer -dNOPAUSE -dBATCH -sOutputFile=combined_resized_searchable_1-large.pdf  combined_resized_searchable.pdf
    gs -sDEVICE=pdfwrite -dPDFSETTINGS=/printer -dNOPAUSE -dBATCH -sOutputFile=combined_resized_searchable_2-medium.pdf combined_resized_searchable.pdf
    gs -sDEVICE=pdfwrite -dPDFSETTINGS=/printer -dNOPAUSE -dBATCH -sOutputFile=combined_resized_searchable_3-small.pdf  combined_resized_searchable.pdf
    # OR:
    ps2pdf -dPDFSETTINGS=/printer combined_resized_searchable.pdf combined_resized_searchable_1-large.pdf
    ps2pdf -dPDFSETTINGS=/ebook   combined_resized_searchable.pdf combined_resized_searchable_2-medium.pdf
    ps2pdf -dPDFSETTINGS=/screen  combined_resized_searchable.pdf combined_resized_searchable_3-small.pdf
    ```

== PDF to images: ==

pdftoppm
    - See: [MY OWN ANS!] 
      https://stackoverflow.com/questions/43085889/how-to-convert-a-pdf-into-jpg-with-commandline-in-linux/61700520#61700520
    - Examples:
pdftoppm -jpeg -r 300 input.pdf output 
    The basic command format to convert a PDF to a bunch of images! The `-jpeg` sets the output image format to JPG, `-r 300` sets the output image resolution to 300 DPI, and the word `output` will be the prefix to all pages of images, which will be numbered and placed into your current directory you are working in.
    Other examples:   
mkdir -p images && pdftoppm -jpeg -r 300 mypdf.pdf images/pg
    [Produces ~1MB-sized files per pg] Output in **.jpg** format at **300 DPI**.
mkdir -p images && pdftoppm -jpeg -jpegopt quality=100 -r 300 mypdf.pdf images/pg
    [Produces ~2MB-sized files per pg] Output in **.jpg** format **at highest quality (least compression)** and still at **300 DPI**.
mkdir -p images && pdftoppm -jpeg -r 600 mypdf.pdf images/pg
    If you need more resolution, you can try 600 DPI.
mkdir -p images && pdftoppm -jpeg -r 1200 mypdf.pdf images/pg
    ...or 1200 DPI.

== images to PDF: ==

See:
1. *****[my answer] https://askubuntu.com/a/1385947/327339
   It includes:
    1. images to pdf
    1. text to pdf
    1. pdf to single pdf
1. Use ImageMagick's `convert`
    1. To fix the broken convert program: https://stackoverflow.com/questions/52998331/imagemagick-security-policy-pdf-blocking-conversion/53180170#53180170
    1. https://averagelinuxuser.com/convert-images-to-pdf-on-linux/
    1. https://stackoverflow.com/questions/8955425/how-can-i-convert-a-series-of-images-to-a-pdf-from-the-command-line-on-linux

sudo apt update && sudo apt install img2pdf
    Install img2pdf
img2pdf img1.png -o out.pdf
    <=============
    Convert img1.png to out.pdf. 
    See: https://stackoverflow.com/a/8955457/4561887
img2pdf img1.png img2.jpg -o out.pdf
    <=============
    Convert img1.png and img2.jpg to out.pdf. 
    See: https://stackoverflow.com/a/8955457/4561887

See also some of my hacky work-arounds here: https://github.com/ElectricRCAircraftGuy/PDF2SearchablePDF/issues/23


== text to pdf: ==

enscript -p file.ps file.txt && ps2pdf file.ps file.pdf
    Convert file.txt to file.ps and then file.ps to file.pdf.
    See: 
    - https://stackoverflow.com/questions/20129029/a-light-solution-to-convert-text-to-pdf-in-linux/20129300#20129300
    - `ps2pdf` documentation: https://linux.die.net/man/1/ps2pdf


== Combine PDFs: ==

pdfunite in1.pdf in2.pdf in3.pdf out.pdf
    Combine multiple PDFs into one! CAUTION: the last pdf argument MUST BE a new pdf name, such as out.pdf, or else you'll be accidentally overwriting an input, ruining it! Source for this cmd: 
    See: https://stackoverflow.com/a/11280219/4561887

== Make PDFs Searchable/OCR PDFs: ==

pdf2searchablepdf <input.pdf | dir_of_imgs> [lang]`
    [My own project] "If the 1st argument is to an input pdf, then convert input.pdf to input_searchable.pdf using language"lang" for OCR. Otherwise, if the 1st argument is a path to a directory containing a bunch of images, convert the whole directory of images into a single PDF, using language "lang" for OCR!" See: https://github.com/ElectricRCAircraftGuy/PDF2SearchablePDF.
pdf2searchablepdf -h
    Show the help menu for this program!

== Split PDFs/extract pgs: ==

pdftk input.pdf cat 10-12 output output.pdf
    Extract pgs 10 to 12, inclusive, from input.pdf and save them into output.pdf. Works great!
    - See: https://askubuntu.com/a/282455/327339
    - Install (tested in Ubuntu 20.04): `sudo apt install pdftk-java`.
    [keywords: extract pgs from pdf, extract pages from pdf, split pdf]

== Compress PDFs: ==
[pdf compression; compress pdfs]

For Ghostscript (`gs`) commands, or `ps2pdf` commands (part of Ghostscript), see:
1. `gs`:        https://askubuntu.com/questions/113544/how-can-i-reduce-the-file-size-of-a-scanned-pdf-file/256449#256449
2. `ps2pdf`:    https://askubuntu.com/questions/113544/how-can-i-reduce-the-file-size-of-a-scanned-pdf-file/243753#243753
1. [MY ANSWER]: https://askubuntu.com/questions/113544/how-can-i-reduce-the-file-size-of-a-scanned-pdf-file/1303196#1303196

[3 Main levels of compression:]
[Use Ghostscript (`gs`) to compress input.pdf into output.pdf.]
[You may also add `-dQUIET` to suppress all output to stdout. See: https://www.ghostscript.com/doc/current/Use.htm]

gs -sDEVICE=pdfwrite -dPDFSETTINGS=/printer -dNOPAUSE -dBATCH -sOutputFile=output.pdf input.pdf
    <==== BEST FOR PDFS W/HIGH-RES. IMAGES, SUCH AS MY RESUMES ====
    1: LOW compression: **300 dpi** (large file size)
    See my answer: https://askubuntu.com/a/1303196/327339
gs -sDEVICE=pdfwrite -dPDFSETTINGS=/ebook -dNOPAUSE -dBATCH -sOutputFile=output.pdf input.pdf
    2: MEDIUM compression (recommended): **150 dpi** (medium file size)
    <========= BEST ^^^ ========
    See my answer: https://askubuntu.com/a/1303196/327339
gs -sDEVICE=pdfwrite -dPDFSETTINGS=/screen -dNOPAUSE -dBATCH -sOutputFile=output.pdf input.pdf
    3: HIGH compression: **72 dpi** (small file size)
    See my answer: https://askubuntu.com/a/1303196/327339

[You can also use `ps2pdf`, which is a wrapper around `gs`, and produces very similar, but not exactly identical, results:]
ps2pdf -dPDFSETTINGS=/printer input.pdf output.pdf
    1: LOW compression: **300 dpi** (large file size)
ps2pdf -dPDFSETTINGS=/ebook   input.pdf output.pdf
    2: MEDIUM compression (recommended): **150 dpi** (medium file size)
ps2pdf -dPDFSETTINGS=/screen  input.pdf output.pdf
    3: HIGH compression: **72 dpi** (small file size)


====================================================================================================
= flowcharts and drawing tools, graphics, emojis, unicode chars & icons, etc.: =
====================================================================================================

Every piece of software is benefited by flowcharts, diagrams, and drawings to show how it works and how the data flows. Here are a few popular options:

1. *****LucidChart: https://www.lucidchart.com
    1. It is paid/professional (probably the industry standard), but has a free light version--sign up with just an email address
1. ****Google Slides/Docs/Drawings: docs.google.com
    1. A bit simplistic, but works
1. ***LibreOffice Draw
1. *****+AsciiFlow: http://asciiflow.com/; and on GitHub: https://github.com/lewish/asciiflow2
    1. Probably my favorite!
    1. Super simple, ASCII-text-based drawing tool for easily pasting ASCII flow chart drawings into text files such as readmes or as comments/documentation inside actual code files.
    1. Looks great inside GitHub markdown readmes when pasted as though it was a code snippet!
    1. For inserting symbols, emojis, specialty icons, etc, as unicode chars, just copy and paste from one of the nice lists shown below:
1. *****For other ASCII-based drawing options, see here! https://unix.stackexchange.com/questions/126630/creating-diagrams-in-ascii
1. Dot (a scripted flow-chart drawing tool) & GraphViz

== Unicode icons/chars/emojis: ==

1. Graphics available on GitHub, apparently: https://gist.github.com/rxaviers/7360908
    Ex: `:goat:`, `:rooster:`, `:+1:`, etc.
2. A ton of unicode chars, including with color graphics: https://gist.github.com/endolith/157796
    Ex:
    🎃 Jack-O-Lantern
    🎄 Christmas Tree
    🎅 Father Christmas
    🎆 Fireworks
    🎇 Firework Sparkler
    🎈 Balloon
    🎉 Party Popper
    etc.
3. Just some very basic ASCII graphics and symbols: https://gist.github.com/spudbean/1558257
    Ex:
    ◔̯◔ [sad]
    ⊙︿⊙ [sad]
    ◕︵◕ [sad]
    ●︵• [sad]
    ◉︵◉ [really sad]
    ಡ_ಡ [misty eyes]
    ಥ_ಥ [crying]
    ಢ_ಢ [crying]
    ಢ_ಥ [heavily distraught]
    ⊙﹏⊙ [embarrassed]
    ( ﾟoﾟ) [surprised]
    ⋋_⋌ [frustrated]
    〴⋋_⋌〵[angry]


====================================================================================================
= ros: =
====================================================================================================
ROS = Robot Operating System
https://www.ros.org/
For more of my information on ROS, see my ROS folder here: [eRCaGuy_dotfiles/ros](ros).

References:
1. https://www.ros.org/
    1. *****+http://wiki.ros.org/
1. https://github.com/ros
    1. https://github.com/ros/ros
1. https://en.wikipedia.org/wiki/Robot_Operating_System
1. *****+[VERY USEFUL!]rosbag command line: http://wiki.ros.org/rosbag/Commandline
1. rosbag/Tutorials/Recording and playing back data - http://wiki.ros.org/rosbag/Tutorials/Recording%20and%20playing%20back%20data
1. rosbag intro video: https://youtu.be/pwlbArh_neU
1. http://wiki.ros.org/rxbag [WX Widgets-based ROS GUI tool--deprecated, replaced by rqt_bag]
1. http://wiki.ros.org/rqt
    1. http://wiki.ros.org/rqt_bag [QT-based ROS GUI tool--replaces rxbag]
1. *****++[CODE SAMPLES & STUFF!] http://wiki.ros.org/rosbag/Cookbook
1. http://wiki.ros.org/rospy
        sudo apt install python-rospy
   See: https://zoomadmin.com/HowToInstall/UbuntuPackage/python-rospy
1. pyrosbag; see:
    1. https://pyrosbag.readthedocs.io/en/latest/installation.html
    1. https://pyrosbag.readthedocs.io/en/latest/usage.html
            pip3 install pyrosbag
                import pyrosbag # in python code
1. *****rostopic: http://wiki.ros.org/rostopic
1. *****++ EXCELLENT CHEAT SHEET:
    1. Google search for "ros cheat sheet" - https://www.google.com/search?q=ros+cheat+sheet&oq=ros+chea&aqs=chrome.0.69i59j69i57j69i60l3.1626j0j4&sourceid=chrome&ie=UTF-8
    1. EXCELLENT CHEAT SHEET! - https://w3.cs.jmu.edu/spragunr/CS354_S19/handouts/ROSCheatsheet.pdf

== roscore ==
- See:
    - http://wiki.ros.org/rosbag/Tutorials/Recording%20and%20playing%20back%20data#Recording_data_.28creating_a_bag_file.29
    - http://wiki.ros.org/roscore

roscore -h
    help menu
roscore
    start up a "ROS core", which includes a ROS master node; this program is REQUIRED to be running for any ROS nodes to be up and running, for ROS params to be accessed, and for ROS topics to be published or subscribed to. `roslaunch` apparently launches a roscore process as part of its startup.

== roslaunch ==
- http://wiki.ros.org/roslaunch
- a higher-level command to roscore; starts up a roscore process as part of its startup; see: http://wiki.ros.org/roslaunch#roscore

roslaunch -h
    help menu
[I'm not really sure how to use this program yet]

== rosbag info ==
- http://wiki.ros.org/rosbag/Commandline#info
- show info about the bag file
- does NOT require a master node, via `roscore`, to be running first.

rosbag info -h
    help menu
rosbag info myfile.bag
    display a summary of the contents of the bag file(s) myfile.bag, including showing a list of all message types in the bag file, and a list of all topics published to, with their message types, and the number of times each topic was published to! This is very useful if you need to just see if a certain topic exists (was published to *at all*) in a given bag file! Ex:
rosbag info myfile.bag | grep -E "(my_topic_2|my_topic_1)"
    show if my_topic_1 and my_topic_2 exist at all (were published to at all) in this bag file, and if so, how many times and what are their message types in these topics

== rosbag play ==
- http://wiki.ros.org/rosbag/Commandline#play
- plays back a recorded bag file in the same time span it was originally recorded
- DOES require a master node, via `roscore`, to be running first.
NB: *NOT* all of the CLI options are described on the website! See `rosbag play -h` for additional options! Ex:
  --try-future-version  still try to open a bag file, even if the version
                        number is not known to the player
  --topics              topics to play back
  --pause-topics        topics to pause on during playback
  --bags=BAGS           bags files to play back from

rosbag play -h
    help menu
rosbag play myfile.bag
    play back the contents of bag file(s) myfile.bag, in a time-synchronized fashion (and at the same rates/time intervals as they were originally recorded); this is very useful for spoofing a system in order to replay live data, test systems and algorithms, test a robot's response to replayed inputs, etc. See: http://wiki.ros.org/rosbag/Commandline#play
rosbag play -i myfile.bag
    play back the whole file "'i'mmediately", or as fast as possible, rather than in a time-synchronized fashion; watch out! "For large files this will often lead to exceeding your incoming buffers."
rosbag play --loop myfile.bag
    continually play myfile.bag on a loop; ie: when done playing back the file, start back over from the beginning again, repeatedly
rosbag play myfile.bag --topics topic1 topic2
    play back only topic1 and topic2 from myfile.bag! See `rosbag play -h` for where I found this. Also see this question here for where I first saw it: https://answers.ros.org/question/228676/exclude-some-topics-from-rosbag-play/
rosbag play myfile.bag --topics topic1 --topics topic2
    same as above, but using the `--topics` flag repeatedly; just use the shorter syntax above instead!

== rosbag filter ==
- http://wiki.ros.org/rosbag/Commandline#filter
- scans through a bag file and produces a new bag file containing only the content you are filtering on with your python filter command.
- does NOT require a master node, via `roscore`, to be running first.

rosbag filter -h
    help menu
rosbag filter input_file.bag new.bag "'topic1' in topic or 'topic2' in topic"
    read in the input_file.bag bag file, and store any topics with the string "topic1" or "topic2" anywhere in their name into a new output bag file called new.bag. Note: this works, but it can potentially take a long time! On a 1 GB bag file, it might take up to 5 to 10 minutes or more, and some bag files could be as large as dozens of GB, which could take up to a couple hours just to filter out some messages on a few topics. There's got to be a faster way, especially if you just want to view the first few messages on a given topic, for instance...
rosbag filter --print="'%s @ %d.%d: %s' % (topic, t.secs, t.nsecs, m.data)" input_file.bag new.bag "'topic1' in topic or 'topic2' in topic"
    print message.data (`m.data`) for any messages with topic1 or topic2 in theit topic names, while creating a new output bag file; I can't seem to get this to work quite right, but it's something like this...

== rostopic ==
- http://wiki.ros.org/rostopic

rostopic -h
    help menu

== rostopic echo ==
- http://wiki.ros.org/rostopic#rostopic_echo
- DOES require a master node, via `roscore`, to be running first.

rostopic echo -h
    help menu
rostopic echo /my/ros/topic
    echo (print to the terminal) any messages on this topic which are currently being published! (by a node, or played back by `rosbag play`)

== rostopic list ==
- http://wiki.ros.org/rostopic#rostopic_list
- DOES require a master node, via `roscore`, to be running first.

rostopic list -h
    help menu
rostopic list -v
    list full details ('v'erbose mode) about each topic currently being played/published! See: http://wiki.ros.org/rosbag/Tutorials/Recording%20and%20playing%20back%20data#Recording_all_published_topics and the `rostopic list -h` help menu.

== HOW TO READ MESSAGES FROM DESIRED TOPICS IN A BAG FILE ==
- Let's say I want to see all messages on topic1, topic2, and topic3 in a huge (could be many GB) bag file; how do I read them?

OPTION 1:
Play them live as quickly as possible, and look at the output in various terminals.
Pros: runs QUICKLY (~10 sec, for instance, once you get all the terminals set up).
Cons: requires a bunch of separate terminals and processes and a `roscore` running, and is a bit of a pain to set up.

    # 0. In any terminal, ensure you know the topic names *exactly*.
    # A) manually inspect all published topics and how many messages were published to each topic
    time rosbag info mybag.bag
    # OR, B) grep for some keywords you're looking for which you know make up the topic names
    time rosbag info mybag.bag | grep -E "(topic1|topic2|topic3)"

    # 1. In terminal 1, start up a ros core, which runs the required ROS master node
    roscore

    # 2. In terminal 2, subscribe to /topic1, echoing (printing) everything published on this topic,
    # while also teeing it to a file for later review, all in yaml format
    rostopic echo /topic1 | tee topic1.yaml

    # 3. In terminal 3, subscribe to /topic2...
    rostopic echo /topic2 | tee topic2.yaml

    # 4. In terminal 4, subscribe to /topic3...
    rostopic echo /topic3 | tee topic3.yaml

    # 5. In terminal 5, play back the bag file now as quickly as possible, publishing ONLY the
    # topics of interest. Note: on a 10GB~20GB or so sized bag file, this might take 10 or so
    # seconds on a high-speed SSD, so it is really quite fast! The underlying functionality must be
    # implemented in C++, as I think the Python implementation would take more like 1~2 minutes at
    # least.
    # Play back (publish) just these topics as quickly as possible!
    time rosbag play --immediate mybag.bag --topics /topic1 /topic2 /topic3

OPTION 2 [my preferred approach!]:
Run a short Python program to output just what you want.
See here for starters: http://wiki.ros.org/rosbag/Cookbook
Main `rosbag` API info pg. (C++ and Python): http://wiki.ros.org/rosbag/Code%20API
Python2 `rosbag` Code API documentation: https://docs.ros.org/api/rosbag/html/python/
- `read_messages()` API documentation: https://docs.ros.org/api/rosbag/html/python/rosbag.bag.Bag-class.html#read_messages
Use this short Python script: "eRCaGuy_dotfiles/useful_scripts/ros_readbagfile.py"
Pros: really easy to use; requires only 1 terminal, and NO `roscore` running.
Cons: this Python implementation runs ~13x slower than the one above, so it might take up to 1 to 2+ minutes to process an entire bag file.
TODO: convert the below Python script to a C++ program using the [C++ rosbag API](http://wiki.ros.org/rosbag/Code%20API#cpp_api).

    # 0. Do step 0 from above (OPTION 1) to ensure you know the topic names *exactly*.
    time rosbag info mybag.bag
    # OR
    time rosbag info mybag.bag | grep -E "(topic1|topic2|topic3)"

    # 1. Run this script to print all messages on the specified topics from this bag file.
    # This script can be found in the "useful_scripts" folder herein.
    python2 ros_readbagfile.py <mybagfile.bag> [topic1] [topic2] [topic3] [...]

== C++ Debugging prints in ROS: ==
[ROS debug prints, ROS logger, ROS printing, ROS console]

References (in this order):
1. https://answers.ros.org/question/108646/print-out-the-contents-of-a-string-using-ros_info/
2. http://wiki.ros.org/Verbosity%20Levels
3. http://wiki.ros.org/roscpp/Overview/Logging
4. http://wiki.ros.org/rosconsole
5. https://github.com/ros/rosconsole/tree/noetic-devel/include/ros
    1. https://github.com/ros/rosconsole/blob/noetic-devel/include/ros/console.h
    2. https://github.com/ros/rosconsole/blob/noetic-devel/include/rosconsole/macros_generated.h
6. ROS `std_msgs::`
    1. https://github.com/ros/std_msgs/tree/kinetic-devel/msg
    2. https://github.com/ros/std_msgs/tree/kinetic-devel/include/std_msgs

C++ example debug/info prints in ROS:

    // Note: this header file automatically includes `#include "rosconsole/macros_generated.h"` at
    // the end
    #include <ros/console.h>

    #include <std_msgs/String.h>
    #include <std_msgs/Header.h>

    std_msgs::String str;
    std_msgs::Header header;
    std_msgs::Header msg1;
    std_msgs::String msg2;

    // Use like C printf() with standard C types:
    ROS_INFO("my_unsigned_int = %u", my_unsigned_int);
    // Use like C++ cout with ROS messages and streams:
    ROS_INFO_STREAM("header = \n" << header);
    ROS_INFO_STREAM("msg1 = \n" << msg1);
    ROS_INFO_STREAM("msg2 = \n" << msg2);
    // ...etc.

    /*
    See:
    1. http://wiki.ros.org/Verbosity%20Levels
    2. http://wiki.ros.org/roscpp/Overview/Logging
    3. See also the table under the "Output" section here:
       http://wiki.ros.org/roscpp/Overview/Logging#Output

    The 5 options include:

    ROS_DEBUG()
    ROS_INFO() // normally use this one!
    ROS_WARN()
    ROS_ERROR()
    ROS_FATAL()

    ROS_DEBUG_STREAM()
    ROS_INFO_STREAM() // normally use this one!
    ROS_WARN_STREAM()
    ROS_ERROR_STREAM()
    ROS_FATAL_STREAM()

    DEBUG and INFO print to stdout, whereas WARN, ERRO, and FATAL all print to stderr! See the
    table under the "Output" section here: http://wiki.ros.org/roscpp/Overview/Logging#Output

    */

== ==


====================================================================================================
= Scratch Work/Work in Progress (WIP): =
====================================================================================================

WORK IN PROGRESS (WIP)
- this is a scratch work place for me to take notes as I discover them.

Trying to create a version of `git diff` which includes line numbers!
Getting there, but numbers + and - lines, thereby making the numbers waaay too long!

    git diff -U100000 --color=always --no-prefix HEAD~ | grep --color=never -m 1 -A 100000 @@ | tail -n +2 | grep --color=never -n .

    git diff -U100000 --color=always --no-prefix HEAD~ | grep --color=never -m 1 -A 100000 @@ | tail -n +2

    git diff -U100000 --color=always --no-prefix HEAD~ | grep -E "@@.{0,20}@@"

GOT ONE! The left-hand (-) side:

WORKS:
    git diff -U100000 --color=always --no-prefix HEAD~..HEAD | grep --color=never -m 1 -A 100000 @@ | tail -n +2 | grep --color=never -v -E $'^\e\[32m\+' | grep --color=never -n .

And now the right-hand (+) side:

WORKS:
    git diff -U100000 --color=always --no-prefix HEAD~..HEAD | grep --color=never -m 1 -A 100000 @@ | tail -n +2 | grep --color=never -v -E $'^\e\[31m-' | grep --color=never -n .

NEXT:
Now, store them into two separate variables, recombine them into one variable, sort them, and delete duplicate lines (lines which are *exactly* identical!) Then display the output. Make it a git alias. Done.

Update: use this as a starting point instead!
  1. https://stackoverflow.com/questions/24455377/git-diff-with-line-numbers-git-log-with-line-numbers/33249416#33249416
  1. See also my question here: https://stackoverflow.com/questions/61932427/git-diff-with-line-numbers-and-proper-code-alignment-indentation