Hacker News new | past | comments | ask | show | jobs | submit login
Hidden manuals: gittutorial, giteveryday, gitglossary, gitworkflow
182 points by divbzero 11 months ago | hide | past | favorite | 39 comments
Today I discovered a set of wonderful and slightly hidden manuals on git:

  man gittutorial
  man giteveryday
  man gitglossary
  man gitworkflow
Actually they aren’t all that well hidden if an observant user just started poking at git:

  $ man git
  
  GIT(1)
  
  ...
  
  
  DESCRIPTION
         Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals.
  
         See gittutorial(7) to get started, then see giteveryday(7) for a useful minimum set of commands. The Git User’s Manual[1] has a more in-depth introduction.
  
  ...
  
  
  SEE ALSO
         gittutorial(7), gittutorial-2(7), giteveryday(7), gitcvs-migration(7), gitglossary(7), gitcore-tutorial(7), gitcli(7), The Git User’s Manual[1], gitworkflows(7)
  
  ...



This is a reason why I love BSD (specifically Net-; but it doesn't matter). The system as a whole is complete, and that includes documentation. The man pages of the BSDs are nothing but excellent, and plenty. The base install is so small that you can comprehend all of it in one go.

You want to learn about UNIX? Start by visiting /{,usr}/{,s}bin of a base install (the beauty of the split), and look at what each present binary does by reading its manpage and actually following those SEE ALSO mentions.

And suddenly you'll feel well equipped to cough out a lot more one-liners without having to drop down to bashisms...


Tangential but sometimes I use dman [1] script that loads manpages on demand from Debian servers. Would be nice to hook it up to BSD manpages as well!

[1]: packaged in `debian-goodies` on Debian, `bikeshed` on Ubuntu, or I have this version patched for macOS (might work on BSD or other Unices, too): https://gist.github.com/notpushkin/6e9b2e232b9cd5e1e35600c5e...


Chiming in with tangentially related TIL for Git help (on Windows):

    git <command> -h
is usually what one needs: it prints abbreviated description with available parameters right into terminal.

    git <command> --help
    git help <command>
on the other hand opens local html help pages (there is no other option in Windows, or in other words, I haven't got `man` to work there). Opening web browser with local html page might feel like overkill for some (most) situations. (Don't get me wrong, html help pages are also neat, just most of the times I am looking just for parameters and brief description, so switching to different window is unwanted distraction.)

For me this is the only known instance where single-dash single-char argument (-h) does something different than its double-dash verbose counterpart (--help).


Some other useful man pages:

hier - Explains the filesystem layout

ascii - An ASCII table

builtins - Things your shell does without external binaries

signal - Includes a table of all the signal numbers


I consider myself quite proficient on the command line; intermediate would be fair to say.

However, I just can’t really parse man pages. I’ve never sat down and just figured out the numbering scheme and how to efficiently read/parse them.

Occasionally I’ll read a man page online, but a quick blog post seems to be an easier reach, or even GPT these days.

For example, hier: https://linux.die.net/man/7/hier

—

Also, a good opportunity to complain about -h/--help flags not being universally recognized by bins.


Look at `man man`, the numbers are explained:

https://www.man7.org/linux/man-pages/man1/man.1.html


The source of the manpages on die.net is always questionable to me. I've found they're often out of date or for questionable versions of software. https://manpages.debian.org/ has all the relevant man pages and is always up to date. (and it allows you to pick between different providers of the page)


Do you feel the same way about reading technical documentation or specifications vs. digested explanations and instructions in general? Most man pages are probably closer to the former in spirit.


Nope. I enjoy reading the official docs for languages like Python (narrative or API). For Java I'm fine reading signatures; it's OK. I've not found a lot of good docs in that language, TBH. Even TypeScript can be alright, though I find myself navigating to definition a lot. That said, it's highly proj. dependent. E.g. fp-ts is hard to parse, though perhaps rewarding and succinct when you make progress.

I've written my fair share of documentation, too. E.g.: http://python-forge.readthedocs.io

It might be that manpages lack links, and it's hard to hop back and forth, as I can't set markers like in vim, so my controls are just up/down.


I've found the pager search function useful in some cases when navigating man pages. At least in less, '/' does forward search, and '?' does backward search.

Navigating longer man pages does seem to be somewhat clumsy, though, and finding things in something massive such as the gcc man page takes work. I'm probably just used to it enough that I don't always even realize it.


There's also man(1) for the table of what the (#) section numbers mean.

>builtins - Things your shell does without external binaries

My OpenSUSE install doesn't have builtins. I just look in bash(1).

>signal - Includes a table of all the signal numbers

Specifically signal(7)


I consider the linux-man-pages project (usually simply "man-pages" in most linux distributions) to be the single best reference manual for UNIX C programming. It has extensive descriptions, examples, warns about libc/platform differences, and allows discovery of new/similar functions through the SEE ALSO section at the end of the page.

https://man7.org/linux/man-pages/dir_section_3.html


Not useful exactly but I occasionally enjoy typing `man -a tee` into my terminal. Not even an Easter egg but it usually cheers me up (jury's out on du ./gong)


`man ascii` changed my life. No more ad-ridden ascii table websites. Glorious.


The problem with man pages is that they are hard to discover if you don't know the name.


The canonical answer to your problem is APROPOS(1). It searches man pages for keywords. Say you remember there was a man page describing the filesystem hierarchy, you'd run:

    $ apropos "filesystem hierarchy"
    hier (7)             - description of the filesystem hierarchy
    $ man 7 hier
    # you're off!
now you "just" need to remember that apropos is a thing...


> The canonical answer to your problem is APROPOS(1). It searches man pages for keywords.

`apropos` only searches short descriptions. But `man -K` let's you search all conent of man pages.

> now you "just" need to remember that apropos is a thing...

man has apropos built-in (`man -k`) and calls out `apropos` directly in its help message and its man page, so `man man` will reveal that as well as `man --help`.


The only problem with `apropos` is that it returns so many irrelevant results:

  $ apropos 'count lines' | wc -l
     167

  $ apropos 'count lines' | head
  AllPlanes(3), BlackPixel(3), WhitePixel(3), ConnectionNumber(3), DefaultColormap(3), DefaultDepth(3), XListDepths(3), DefaultGC(3), DefaultRootWindow(3), DefaultScreenOfDisplay(3), DefaultScreen(3), DefaultVisual(3), DisplayCells(3), DisplayPlanes(3), DisplayString(3), XMaxRequestSize(3), XExtendedMaxRequestSize(3), LastKnownRequestProcessed(3), NextRequest(3), ProtocolVersion(3), ProtocolRevision(3), QLength(3), RootWindow(3), ScreenCount(3), ScreenOfDisplay(3), ServerVendor(3), VendorRelease(3) - Display macros and functions
  EVP_PKEY_asn1_find(3ssl), EVP_PKEY_asn1_find_str(3ssl), EVP_PKEY_asn1_get_count(3ssl), EVP_PKEY_asn1_get0(3ssl), EVP_PKEY_asn1_get0_info(3ssl) - enumerate public key ASN.1 methods
  EVP_PKEY_meth_get_count(3ssl), EVP_PKEY_meth_get0(3ssl), EVP_PKEY_meth_get0_info(3ssl) - enumerate public key methods
  OCSP_REQUEST_new(3ssl), OCSP_REQUEST_free(3ssl), OCSP_request_add0_id(3ssl), OCSP_request_sign(3ssl), OCSP_request_add1_cert(3ssl), OCSP_request_onereq_count(3ssl), OCSP_request_onereq_get0(3ssl) - OCSP request functions
  OCSP_resp_find_status(3ssl), OCSP_resp_count(3ssl), OCSP_resp_get0(3ssl), OCSP_resp_find(3ssl), OCSP_single_get0_status(3ssl), OCSP_resp_get0_produced_at(3ssl), OCSP_resp_get0_signature(3ssl), OCSP_resp_get0_tbs_sigalg(3ssl), OCSP_resp_get0_respdata(3ssl), OCSP_resp_get0_certs(3ssl), OCSP_resp_get0_signer(3ssl), OCSP_resp_get0_id(3ssl), OCSP_resp_get1_id(3ssl), OCSP_check_validity(3ssl), OCSP_basic_verify(3ssl) - OCSP response utility functions
  OPENSSL_malloc_init(3ssl), OPENSSL_malloc(3ssl), OPENSSL_zalloc(3ssl), OPENSSL_realloc(3ssl), OPENSSL_free(3ssl), OPENSSL_clear_realloc(3ssl), OPENSSL_clear_free(3ssl), OPENSSL_cleanse(3ssl), CRYPTO_malloc(3ssl), CRYPTO_zalloc(3ssl), CRYPTO_realloc(3ssl), CRYPTO_free(3ssl), OPENSSL_strdup(3ssl), OPENSSL_strndup(3ssl), OPENSSL_memdup(3ssl), OPENSSL_strlcpy(3ssl), OPENSSL_strlcat(3ssl), CRYPTO_strdup(3ssl), CRYPTO_strndup(3ssl), OPENSSL_mem_debug_push(3ssl), OPENSSL_mem_debug_pop(3ssl), CRYPTO_mem_debug_push(3ssl), CRYPTO_mem_debug_pop(3ssl), CRYPTO_clear_realloc(3ssl), CRYPTO_clear_free(3ssl), CRYPTO_malloc_fn(3ssl), CRYPTO_realloc_fn(3ssl), CRYPTO_free_fn(3ssl), CRYPTO_get_mem_functions(3ssl), CRYPTO_set_mem_functions(3ssl), CRYPTO_get_alloc_counts(3ssl), CRYPTO_set_mem_debug(3ssl), CRYPTO_mem_ctrl(3ssl), CRYPTO_mem_leaks(3ssl), CRYPTO_mem_leaks_fp(3ssl), CRYPTO_mem_leaks_cb(3ssl), OPENSSL_MALLOC_FAILURES(3ssl), OPENSSL_MALLOC_FD(3ssl) - Memory allocation functions
  PKCS5_PBKDF2_HMAC(3ssl), PKCS5_PBKDF2_HMAC_SHA1(3ssl) - password based derivation routines with salt and iteration count
  RSA_set0_key(3ssl), RSA_set0_factors(3ssl), RSA_set0_crt_params(3ssl), RSA_get0_key(3ssl), RSA_get0_factors(3ssl), RSA_get0_crt_params(3ssl), RSA_get0_n(3ssl), RSA_get0_e(3ssl), RSA_get0_d(3ssl), RSA_get0_p(3ssl), RSA_get0_q(3ssl), RSA_get0_dmp1(3ssl), RSA_get0_dmq1(3ssl), RSA_get0_iqmp(3ssl), RSA_get0_pss_params(3ssl), RSA_clear_flags(3ssl), RSA_test_flags(3ssl), RSA_set_flags(3ssl), RSA_get0_engine(3ssl), RSA_get_multi_prime_extra_count(3ssl), RSA_get0_multi_prime_factors(3ssl), RSA_get0_multi_prime_crt_params(3ssl), RSA_set0_multi_prime_params(3ssl), RSA_get_version(3ssl) - Routines for getting and setting data in an RSA object
  TIFFFieldPassCount(3tiff) - get whether to pass a count to TIFFGetField/TIFFSetField
  TIFFFieldReadCount(3tiff) - get number of values to be read from field


Well, staple utilities typically have short names, so sorting the results by name length might help:

    $ apropos count lines | awk '{print length($1), $0}' | sort -n | head
    2 gc (1)               - count graph components
    2 nl (1)               - number lines of files
    2 rg (1)               - recursively search the current directory for lines matching a pattern
    2 sa (8)               - summarizes accounting information
    2 wc (1)               - print newline, word, and byte counts for each file
    3 box (3x)             - create curses borders, horizontal and vertical lines
    3 cvt (1)              - calculate VESA CVT mode lines
    3 gtf (1)              - calculate VESA GTF mode lines
    3 rev (1)              - reverse lines characterwise
    3 sum (1)              - checksum and count the blocks in a file
Side-note, there are a bunch of neat utilities here I didn't know about!


some BSD ones:

sysexits(3) - meaningful exit codes

style(9) - C coding style

style.Makefile(9) - other coding styles (here, Makefile)


dang definitely woulda loved this 20 years ago when i was just starting out with linux. very neat thanks


also man bash. you will learn what >() and <() mean

I was never able to read the entirety of man bash though


Maybe I'm using the wrong search regex, but I can't find an explanation for >() or <() in `man bash`, `man builtins` or `man bash-builtins`.


It's in bash(1) under "Process Substitution" — https://manpages.debian.org/bookworm/bash/bash.1.en.html#Pro...


If your MANPAGER is less, you can type ^R (CTRL+R) in the search prompt (/) to make it interpret the search string literally (disable regular expressions). As noted in less(1).


If you don't have a terminal at hand: https://www.mankier.com/7/gittutorial https://www.mankier.com/7/giteveryday https://www.mankier.com/7/gitglossary https://www.mankier.com/7/gitworkflows


why use some 3rd party site when you have the official and always up-to-date https://git-scm.com/docs/giteveryday ?


I too just discovered these a few days ago! I've been trying to work out a satisfactory way to combine multiple repositories into a monorepo at work. Since I'm building a new repo, I'm free to rewrite history, so I've used `git-filter-branch` to modify the sub-repositories into a form suitable for merging (moved all files to subdirectories, matching the final monorepo structure). Merging them with `--allow-unrelated-histories` is... Okay. No conflicts, the linear git log looks good, and I also prepended the module name to commit messages before merging, so it reads well. But the graph is super ugly (Merges with many years of commits in between, because I just merged the repos in one by one). What I'd really like to do is to "zip" all the histories together into a single, linear history, with all the commits in chronological order. Thus far I haven't found a way to do this with git. I'm probably missing some obvious reason why that couldn't work, but I haven't come up with any.


Funny, I did just exactly that at work yesterday. If your branches have linear histories, here's what to do:

1. Make sure all branches touch separate files. I would strongly recommend git-filter-repo over git-filter-branch. It's way simpler to use and orders of magnitudes faster.

2. Generate the list of commits in the correct order:

git rev-list --date-order --reverse branchA BranchB BranchC > revisions.txt

3. Go to any branch and: git rebase -i --root --force-rebase

Paste the contents of revisions.txt into the sequence editor and add "p " at the bigging of every line. Run the rebase and you are done.


I figured out a way to not have to paste in manually to the sequence editor. I wrote a script like this:

-----

#!/bin/bash

if [[ ! -f "$1" ]]; then

exit 1

fi

git rev-list --no-merges --date-order --reverse $(git branch -a | grep -v '*' | grep master) | awk '{print "p " $0}' > $1

exit 0

-----

Then I can just:

-----

pushd monorepo

GIT_SEQUENCE_EDITOR=../inject_reflist.sh git rebase -i --root --force-rebase

popd

-----

And off we go! Apparently there were a few branches + merges, and we have some ongoing feature branches, so I need to find a way to bring in branches other than master as well, preferably while conserving the merges as-is, instead of skipping them like I do above.


Thank you! This looks like exactly what I want. I actually am already using `git-filter-repo` - I just confused the two names in my comment there. Super useful tool!


Have you seen reposurgeon? It’s not something I’ve personally used, but it might be able to help you out!

http://www.catb.org/esr/reposurgeon/


That's cool, I didn't know about any of those, despite having read the git man page a few times. I think my brain skips over / ignores whole sections of man pages. Something to do with the order they are written in, and the fact that I'm always after something halfway down. A lot of /<search> <n> <n> for me.

If, like I often am, you are just after examples for a command you've used many times but forgotten common flags for (-r or -R?!), the online resource:

  $ curl cheat.sh/grep.    # or replace grep with <command>
will work in your terminal, minimum of fuss. There's the option of self-hosting it (docker based) if you are regularly working in an offline/lab environment.


This web page cheat.sh manages to minimize contrast even in a terminal. Well done, you've brought the accessibility nightmares of the modern web to the terminals of the world.


The Section 7 manuals a great. It's worth perusing the list

    man -s 7 -k ''
and reading through the ones that catch your fancy. Some that I like: ascii(7), boot(7), and standards(7).

Section 5 also has some gems: elf(5), termcap(5), etc.


You can also use git help, e.g. "git help gittutorial". On Windows it opens a browser with html man pages, quite useful.

(also note that it's "gitworkflows", with an s at the end)


And it is quite easy to get there the "intuitive" way, especially if you are an avid reader [1]: `git help` lists "common Git commands" and mentions that

    'git help -a' and 'git help -g' list available subcommands and some
    concept guides.
`git help -g` (what is an alias for `git help --guides`, as I've found out in `git help -h`) gives me:

    The Git concept guides are:
       core-tutorial    A Git core tutorial for developers
       credentials      Providing usernames and passwords to Git
       cvs-migration    Git for CVS users
       diffcore         Tweaking diff output
       everyday         A useful minimum set of commands for Everyday Git
       faq              Frequently asked questions about using Git
       glossary         A Git Glossary
       namespaces       Git namespaces
       remote-helpers   Helper programs to interact with remote repositories
       submodules       Mounting one repository inside another
       tutorial         A tutorial introduction to Git
       tutorial-2       A tutorial introduction to Git: part two
       workflows        An overview of recommended workflows with Git
where as you can see "core-tutorial", "everyday", "glossary", and "workflows" are all listed.

[1] I am definitely not, so I've missed it myself.


PSA: Rudimentary completion in Zsh (enabled by a trivial walk through the wizard that runs in the absence of ~/.zshrc) completes man page names. man git<TAB> FTW!


I like offline documentation a lot. Thanks for sharing this!




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: