Documentation and Software

Linux FoundationsLesson 9 of 960 minutesLessonBuilds on: Pipelines and Text SearchLab next: Linux Investigation Lab

Learning objectives

By the end of this lesson

• Identify whether a command is a shell feature or executable path.
• Use --help, man, and package metadata for different questions.
• Predict and verify one bounded package-state change.
• Recover from common apt network, lock, and package-name failures.

The question: what evidence tells you how to use or obtain a command?

When an unfamiliar command turns up, there are really several questions hiding inside “what is this?” Which implementation will this shell run? Which version is installed? What syntax does that version accept? Which package supplied it, and is a candidate available from the configured Ubuntu repositories? No single source answers all of that well.

So start as close to the running system as you can get, because that’s where the answers actually live. Local evidence describes the environment you actually have. A random web result may describe a different release, some optional implementation, or a decade-old incantation that simply refuses to die.

What type, --help, and --version each answer

Start with an installed command rather than a web search:

type grep
grep --version | head -n 1
grep --help | head -n 8

And check the resolved path, the version line, and one option that’s relevant to a task you have already carried out in an earlier lesson.

type answers the question of what the shell will actually run, and --help hands you concise invocation details straight from the installed program itself, with nothing sitting in between to interpret them. For a concept you haven’t met yet, you may also need a tutorial or a longer manual explanation.

--version identifies the implementation well enough that you can compare the documentation against what you’re seeing. --help is usually a compact reference rather than a tutorial. It lists available options, but may give little background on when to use them.

Use the local manual for a question

Local manual pages provide fuller reference documentation for installed commands. They’re divided into named sections like synopsis, description, options, files, and exit status. The synopsis uses notation rather than complete copy-and-paste commands, so read it as a description of the allowed forms. Brackets usually mark optional material rather than characters you should be typing, and that particular detail catches a lot of people out on their first few manual pages.

Open the manual:

man grep

Press /, type line number, and press Enter to search. Press n for the next match, and q when you want out.

Find the option that prefixes output with a line number. Predict the shape of the output first, then test it against the dataset from the previous lesson or this shorter input:

printf 'allow\ndeny\nallow\n' | grep -n '^allow$'

Expected output:

1:allow
3:allow

The manual supplied an option, and the command output verified that you’d read it correctly.

That two-step habit matters a lot more than it looks. Documentation tells you the intended interface, while a controlled command shows you how the installed version actually behaves when it meets your particular input. Neither one makes the other redundant.

What a package actually is

Ubuntu distributes software through signed repositories, and your VM keeps its own local package indexes describing what those repositories were offering the last time you looked (they’re a cached snapshot, and not a live view). apt update refreshes those indexes, and it does not upgrade every installed program. apt-cache only reads metadata, and it doesn’t install anything at all.

A package can contain more than an executable file. It carries versioned files and installation metadata, and it may declare dependencies on other packages. The package manager tracks all of that shared state so installation and removal stay coherent, which is exactly what you’d want it doing. Copying some mystery executable into /usr/bin bypasses the accounting entirely. That is one very good reason not to improvise system installation paths.

Inspect package metadata before changing state

Ask whether tree is already available:

type tree

If it’s missing the shell will say so directly, so refresh the package metadata first and then inspect the candidate without installing any of it:

sudo apt update
apt-cache policy tree
apt-cache show tree | grep -E '^(Package|Version|Description):'

Check the candidate version and the description, and then predict what type tree is going to report once the installation has finished.

Install only the named package:

sudo apt install tree
type tree
tree --version

Read apt’s proposed changes before you confirm anything. If it proposes unrelated removals or a surprisingly large dependency set, answer n and go find out why before you continue with any of this.

That proposal is part of the evidence, and it’s worth reading properly. Package operations touch dependencies and shared system state, so the name you typed is not always the full scope of the transaction. sudo is appropriate here because the package manager genuinely has to change system-owned locations. It would not be appropriate just because type tree came back with “not found.”

Use the APT manual to check which operation changes installed packages and which only inspects metadata. The distinction matters before you run it.

Restore the package state

Nothing later in this course needs tree, so remove it once you’ve checked it works:

sudo apt remove tree
type tree

That final type should report tree as not found again, and it’s worth actually checking rather than assuming. Don’t run autoremove as part of this exercise. Its proposed scope depends on the wider state of your VM rather than on anything we did here.

And if tree was already installed before the lesson, leave it alone. Check the baseline and change nothing.

Restoring state means getting back to the baseline you observed, and not blindly running the opposite command. If the package was there before the lesson, removing it would be a fresh change rather than cleanup. That baseline-first rule scales a long way past packages. Check what existed, change one thing, verify the result, and then restore only what you actually changed (nothing more).

Practice: choose the nearest evidence source

For each question, choose and use the nearest source:

1. What executable path will the shell use for python3?
2. Which installed Python version will run?
3. Which find predicate selects directories?
4. Which Ubuntu package provides the candidate named strace, and what candidate version is available?

Check the command and the relevant output, and not just the answer.

Common failures and recovery

• Could not get lock: another package operation is already running. Wait for it to finish, and never delete apt lock files to get around it.
• A temporary DNS or repository error: check the VM’s networking, then run sudo apt update again. Don’t keep installing from stale or partial metadata.
• Unable to locate package: check the spelling, and confirm apt update actually finished successfully.
• man: command not found: install man-db with apt, after reading the proposed change, and then try again.
• The command survives package removal: run type -a tree, because another copy or a stale shell hash may be involved. Open a fresh terminal and check again.
• The proposed change is broader than you expected: answer n, keep the output, and investigate before you approve anything.

Check your result

Check that you can find an option in the local manual and confirm the package state after your experiment. If the package was absent before the exercise, it should be absent again after cleanup.