Command-Line Navigation for Bioinformatics Projects

Build a small project directory, practice moving through it, and inspect file operations without mistaking placeholder files for usable sequencing data. The examples use a Bash-like shell and common command-line utilities.

Format: Hands-on lab. Beginners with terminal access will create and inspect a disposable bioinformatics-style directory tree, then practice safe copy and move operations. The commands create their own zero-byte placeholder files; no sequencing data are supplied or required.

Learning objectives and prerequisites

Prerequisites: a working terminal on Linux, macOS, or Windows Subsystem for Linux (WSL). No prior shell experience required, but basic familiarity with copying and pasting text will help.

By the end of this lesson you will be able to:

Identify your current directory and list its contents.
Move between directories using absolute and relative paths.
Create, copy, move, and inspect files and directories reliably.
Use safe practices for naming and working with bioinformatics project files.

Why basic command-line navigation matters in bioinformatics

Bioinformatics workflows typically involve many files (raw reads, reference genomes, intermediate results, logs). Graphical file managers become cumbersome or unavailable when you are connected to a remote compute server or working inside a batch job. A small set of command-line skills makes you more reproducible, efficient, and less likely to accidentally lose data when running analysis pipelines.

Examples where these skills are essential:

Transferring files between a local laptop and a remote cluster with scp or rsync.
Running containerised software (Docker/Singularity) that expects file paths as inputs.
Reading and inspecting log files produced by long-running alignment or variant-calling jobs.

Reproducible, sequential workflow

We'll create a small project directory, add example files (empty placeholders for practice), and run commands that show the file system state at each step. Replace the example paths with ones appropriate for your machine. Commands assume a Bourne-like shell (bash, zsh).

1. Start from your home directory and create a project structure

Open a terminal and run the following in Bash. They create directories and three empty files under ~/projects/basic-nav; they do not create sequencing data. The brace expansion in mkdir is a Bash feature, so on another shell either switch to Bash or spell out the four directory names.

# Move to your home directory to start from a predictable location
cd ~

# Create a reproducible project directory tree
mkdir -p projects/basic-nav/{data,results,scripts,logs}

# Create placeholder files that emulate common inputs
touch projects/basic-nav/data/sample_R1.fastq.gz
touch projects/basic-nav/data/sample_R2.fastq.gz
touch projects/basic-nav/scripts/README.md

What these commands do (inputs/outputs):

cd ~ moves to your home directory (no file creation).
mkdir -p projects/basic-nav/{data,results,scripts,logs} creates a nested folder tree ~/projects/basic-nav with four subdirectories. The -p flag ensures parent directories are created as needed.
touch creates three empty files as placeholders: two compressed FASTQ names and a README. These are zero-byte files used for practice; they are not real sequencing data.

2. Check where you are and list contents

# Show the current directory (absolute path)
pwd

# List the new project folder (short and detailed views)
ls projects/basic-nav
ls -l projects/basic-nav
ls -la projects/basic-nav

Expected observations:

pwd prints a full path such as /home/yourusername or /Users/yourname.
ls projects/basic-nav shows the subdirectories created (data, results, scripts, logs).
ls -l projects/basic-nav lists the four subdirectories and their directory metadata; it does not show files nested inside them. To see the zero-byte placeholders and their sizes, run ls -l projects/basic-nav/data projects/basic-nav/scripts. Hidden entries (those starting with a dot) appear with -a.

3. Change directory into the project and use relative navigation

# Change into the project directory using a relative path
cd projects/basic-nav

# Move into the data subdirectory
cd data

# Move up to the project root using the parent shortcut
cd ..

# Quickly return to home using the tilde
cd ~

Notes on paths:

An absolute path begins with / (Linux/macOS) and names every directory from the root, for example /home/youruser/projects/basic-nav.
A relative path is interpreted from your current working directory; for example cd data only works if data is inside your current directory.
Shortcuts: . means current directory, .. means parent directory, ~ means your home directory, and - returns to the previous directory you were in (cd -).

4. Inspect files safely (viewing without modifications)

# Show a short listing with human-readable sizes
ls -lh projects/basic-nav/data

# Check the placeholders: their .fastq.gz names do not make them compressed data
file projects/basic-nav/data/sample_R1.fastq.gz
ls -lh projects/basic-nav/data/sample_R1.fastq.gz

# Preview only if this path names a real, non-empty gzip-compressed FASTQ
zcat /path/to/real_sample_R1.fastq.gz | head -n 20

# Read the text README; press q to quit
less projects/basic-nav/scripts/README.md

What these commands check:

file identifies a zero-byte placeholder here. A filename ending in .fastq.gz is only a name; touch did not compress or populate it.
zcat decompresses to standard output, and head limits the displayed lines. Replace the example path with a real compressed file. Running it on the zero-byte placeholder will produce no FASTQ records; malformed or truncated gzip input can report an error. A short preview can help inspect structure, but does not establish FASTQ validity or read pairing.
less is a pager that lets you view large files page by page.

5. Copy, move, and rename files with examples

Check the source and destination before changing files. The -i option asks before replacing an existing destination. These examples copy and move only the practice placeholders; they are not a backup strategy for irreplaceable data.

# Copy only the R1 placeholder into results; the original remains in data
cp -i projects/basic-nav/data/sample_R1.fastq.gz projects/basic-nav/results/

# Rename the README to indicate it's a template (move within the same folder)
mv -i projects/basic-nav/scripts/README.md projects/basic-nav/scripts/README.template.md

# Move both FASTQ files into a "raw" subfolder (create it first)
mkdir -p projects/basic-nav/data/raw
mv -i projects/basic-nav/data/sample_R1.fastq.gz projects/basic-nav/data/raw/
mv -i projects/basic-nav/data/sample_R2.fastq.gz projects/basic-nav/data/raw/

What to expect:

The cp command duplicates only sample_R1.fastq.gz into results/; its original remains in data/. The later moves place both original mate placeholders in data/raw/, so results/ contains only the copied R1 placeholder.
mv renames or relocates files; when used to rename it is generally fast because it alters metadata rather than copying contents (on the same filesystem).
Without an interactive or no-clobber option, a command may replace an existing destination. Here -i prompts before replacement; read the prompt and answer carefully. A prompt reduces accidental overwrites but is not a backup.

Output inspection and interpretation

After each command, inspect the file system state. Here are concrete checks and how to interpret them safely.

After creating directories with mkdir -p, run ls -la projects/basic-nav. You should see the subdirectories; if one is missing, check for typos in the path.
Use ls -lh on files. These touch-created placeholders are 0 bytes and cannot serve as reads for downstream tools. File size alone cannot establish whether a nonempty FASTQ is valid.
If file identifies gzip data, zcat or gunzip -c can write decompressed text to standard output. If the file is plain text, inspect it with text tools instead. Neither file type nor a short preview checks FASTQ record structure, sequence/quality lengths, read pairing, or biological suitability.

What a plausible result means and what it does not prove:

A FASTQ record has four lines: a header beginning with @, a sequence, a + separator, and a quality string. Seeing only a header and sequence is not enough to validate even the record structure, much less read pairing or biological suitability.
Successful cp or mv indicates the filesystem accepted the operation; it does not validate file contents or integrity. To check integrity, compute checksums (see Troubleshooting below).

Troubleshooting

Common symptoms, likely causes, and fixes.

Symptom: "No such file or directory" when running cd, cp, or mv

Cause: typo in the path or the target has not been created.
Fix: use ls -la on the parent directory to confirm names; consider tab-completion to avoid typos (press Tab in your shell).

Symptom: Files appear missing after mv

Cause: moved to a different directory than expected, or the mv command overwrote an existing file of the same name.
Fix: use cd - to return to the previous directory and run ls. Use ls -l <path> on both source and destination to confirm. If overwriting occurred, there is no general undo; restore from a backup if available.

Symptom: Unexpected file sizes or zero bytes

Cause: transfers that terminated early, placeholder files created by mistake, or mistaken redirection that truncated a file (e.g., using a single greater-than sign).
Fix: If the file came from a remote machine, re-transfer and verify checksums. Compute an MD5 or SHA256 checksum on both ends and compare:

# Create a checksum on the source machine
sha256sum sample_R1.fastq.gz > sample_R1.sha256

# After transfer, verify the checksum on the destination machine
sha256sum -c sample_R1.sha256

Symptom: Permission denied when listing or moving files

Cause: you do not own the file or lack read/write permission.
Fix: check ownership and permissions with ls -l. If appropriate and you have sudo privileges, ask an administrator to change ownership (chown) or permission (chmod), or use a group with shared access. Avoid changing permissions to 777 on production systems.

Limitations, version and reference-data caveats, and responsible-use notes

Limitations:

cd and pwd are shell built-ins; ls, cp, mv, and other file commands have platform-specific variants. Bash brace expansion is not portable to every shell, and GNU-only options such as --backup=numbered may not exist on macOS or other systems. Check your shell and local manual pages before using options from a different platform.
These examples create placeholder files with touch. Placeholder files are not representative of real biological data; downstream tools will fail or produce meaningless results if supplied with zero-byte files.

Version and reference-data caveats:

Always record the versions of key tools (bash, coreutils, samtools, etc.) and reference files (genomes, annotations) as part of project metadata. Small differences in tool versions or reference genomes can change reproducibility.

Responsible-use notes:

Be cautious with destructive commands (rm, rm -rf). Never run a remove command unless you are sure of the target path. Prefer making backups or moving files to a trash directory in the project for safe deletion workflows.
When working with sensitive biological or patient data, follow your institution's data governance policies. Do not copy or expose controlled-access files to unsecured systems.

Concise next-step checklist

Confirm that you can run pwd, ls -la, and cd without errors in your environment.
Create a new project tree under ~/projects and add at least one real small test FASTQ (or download a small public sample) rather than placeholders.
Practice cp -i and mv -i on disposable files first. For important data, use a verified backup and check the destination before any move.
Learn how to compute and check checksums (sha256sum) for file integrity after transfers.
Read the man pages for the commands covered: man ls, man cp, man mv, man mkdir.