6 ms·

Hidden manuals: gittutorial, giteveryday, gitglossary, gitworkflow

182 points by divbzero 3y ago

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) ...

vaylian 3y ago
I like offline documentation a lot. Thanks for sharing this!
jap 3y ago
If you don't have a terminal at hand: https://www.mankier.com/7/gittutorial https://www.mankier.com/7/gittutorial https://www.mankier.com/7/giteveryday https://www.mankier.com/7/giteveryday https://www.mankier.com/7/gitglossary https://www.mankier.com/7/gitglossary https://www.mankier.com/7/gitworkflows https://www.mankier.com/7/gitworkflows
- plg94 3y ago
  why use some 3rd party site when you have the official and always up-to-date https://git-scm.com/docs/giteveryday https://git-scm.com/docs/giteveryday ?
LeoPanthera 3y ago
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
- lacoolj 3y ago
  dang definitely woulda loved this 20 years ago when i was just starting out with linux. very neat thanks
- tryauuum 3y ago
  also man bash. you will learn what >() and <() mean I was never able to read the entirety of man bash though
  - vaylian 3y ago
    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`.
    - lubutu 3y ago
      It's in bash(1) under "Process Substitution" — https://manpages.debian.org/bookworm/bash/bash.1.en.html#Process_Substitution https://manpages.debian.org/bookworm/bash/bash.1.en.html#Pro...
    - neuromanser 3y ago
      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).
- Arnavion 3y ago
  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)
- dfee 3y ago
  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 https://linux.die.net/man/7/hier — Also, a good opportunity to complain about -h/--help flags not being universally recognized by bins.
ephaeton 3y ago
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...
- notpushkin 3y ago
  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/6e9b2e232b9cd5e1e35600c5e79b87a6 https://gist.github.com/notpushkin/6e9b2e232b9cd5e1e35600c5e...
noedig2 3y ago
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)
- myfonj 3y ago
  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.
vkoskiv 3y ago
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.
- superb_dev 3y ago
  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/ http://www.catb.org/esr/reposurgeon/
- chronial 3y ago
  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.
  - vkoskiv 3y ago
    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!
  - 3y ago
hiisukun 3y ago
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.
- funcDropShadow 3y ago
  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.
xelxebar 3y ago
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.
myfonj 3y ago
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).
neuromanser 3y ago
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!

182 points by divbzero 3y ago

vaylian 3y ago

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

jap 3y ago

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

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

LeoPanthera 3y ago

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

lacoolj 3y ago
dang definitely woulda loved this 20 years ago when i was just starting out with linux. very neat thanks
tryauuum 3y ago
also man bash. you will learn what >() and <() mean I was never able to read the entirety of man bash though
- vaylian 3y ago
  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`.
  - lubutu 3y ago
    It's in bash(1) under "Process Substitution" — https://manpages.debian.org/bookworm/bash/bash.1.en.html#Process_Substitution https://manpages.debian.org/bookworm/bash/bash.1.en.html#Pro...
  - neuromanser 3y ago
    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).
Arnavion 3y ago
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)
dfee 3y ago
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 https://linux.die.net/man/7/hier — Also, a good opportunity to complain about -h/--help flags not being universally recognized by bins.

ephaeton 3y ago

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...

notpushkin 3y ago
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/6e9b2e232b9cd5e1e35600c5e79b87a6 https://gist.github.com/notpushkin/6e9b2e232b9cd5e1e35600c5e...

noedig2 3y ago

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)

myfonj 3y ago
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.

vkoskiv 3y ago

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.

superb_dev 3y ago
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/ http://www.catb.org/esr/reposurgeon/
chronial 3y ago
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.
- vkoskiv 3y ago
  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!
- 3y ago

hiisukun 3y ago

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.

funcDropShadow 3y ago
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.

xelxebar 3y ago

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.

myfonj 3y ago

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).

neuromanser 3y ago

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!