Skip to content

gotchas.adoc

Latest commit

 

History

History
380 lines (261 loc) · 7.19 KB

gotchas.adoc

File metadata and controls

380 lines (261 loc) · 7.19 KB

ChELL Gotchas and Known Issues

1. Overview

This document describes known limitations, edge cases, and potential pitfalls when using chell. These are important for users and developers to understand to avoid data loss or unexpected behavior.

2. Critical: Directory Rename Orphans Files

2.1. The Problem

CRITICAL: Renaming a directory that contains files will orphan those files in the ChRIS backend.

When you rename a directory using mv, the directory path is updated in the ChRIS database, but the paths of all files and subdirectories inside it are not automatically updated. This causes the contents to become inaccessible.

2.2. Example Scenario

# Initial state: directory with files
$ ls uploads/
file1.txt  file2.txt  subdir/

# Move/rename the directory
$ mv uploads backup

# Contents are now orphaned!
$ cd backup
$ ls
# Shows nothing - files still have path /home/user/uploads/file1.txt
# but directory is now /home/user/backup

2.3. Root Cause

This is a ChRIS backend limitation, not a chell bug. The ChRIS filesystem stores absolute paths for all resources. When a directory is renamed:

  1. The directory resource path is updated: /home/user/uploads → /home/user/backup

  2. File resources inside still reference old path: /home/user/uploads/file1.txt

  3. Files become orphaned because their parent path no longer exists

2.4. Recovery

If you accidentally rename a directory with contents:

# Rename back to original name
$ mv backup uploads

# Files should reappear
$ cd uploads
$ ls -f  # Force cache refresh
file1.txt  file2.txt  subdir/

Important: Recovery only works if you remember the exact original name.

2.5. Workarounds

2.5.1. Option 1: Move Files Individually

Instead of renaming the directory, move the files inside:

# Create new directory
$ mkdir backup

# Move files (not the directory)
$ mv uploads/* backup/

# Remove empty directory
$ rm -rf uploads

2.5.2. Option 2: Copy Instead of Move

# Copy preserves originals
$ cp -r uploads/ backup/

# Verify contents
$ ls backup/

# Only then remove original
$ rm -rf uploads/

2.6. Future Improvements

Potential solutions:

  1. Detect and warn: Make mv check if source directory has contents and warn before renaming

  2. Prevent operation: Disallow renaming non-empty directories

  3. Backend fix: Update ChRIS backend to cascade path updates (requires backend changes)

3. Spaces in Filenames

3.1. The Problem

Files and directories with spaces in their names require special handling in chell, just like Unix shells.

3.2. Solution: Use Quotes

# Wrong - treats as multiple arguments
$ mv uploads/Feed for file.dcm backup/

# Correct - use quotes
$ mv "uploads/Feed for file.dcm" backup/

# Also correct - use single quotes
$ mv 'uploads/Feed for file.dcm' backup/

# Also correct - escape spaces
$ mv uploads/Feed\ for\ file.dcm backup/

3.3. Special Case: cd Command

The cd command has a special workaround - it joins all arguments with spaces:

# This works without quotes for cd
$ cd Feed for file directory

# But other commands still need quotes
$ rm "Feed for file directory"

Recommendation: Always use quotes for paths with spaces to be consistent.

4. Files Starting with Dashes

4.1. The Problem

Files starting with - or -- are interpreted as flags by command parsers.

4.2. Solution: Use -- End of Options

# This fails - thinks --file is a flag
$ rm --filename

# Correct - use -- to mark end of options
$ rm -- --filename

# Also works with paths
$ rm ./--filename
$ rm /full/path/--filename

4.3. Affected Commands

All commands that parse flags need --:

  • rm

  • mv

  • cp

  • cat

  • touch

5. Wildcard Limitations

5.1. Supported Commands

Wildcards (*, ?, […​]) are only expanded for certain commands:

  • ls

  • rm

  • cat

  • mv

  • cp

5.2. Not Expanded Elsewhere

# Wildcards work here
$ ls uploads/*.txt

# Wildcards NOT expanded in arguments to other commands
$ touch uploads/*.txt  # Creates file literally named "*.txt"

6. Cache Invalidation Edge Cases

6.1. Manual Refresh Required

If files are modified outside chell (web UI, API, another chell session), you may see stale data:

# Another user/session adds files...

# You see old data
$ ls

# Force refresh
$ ls -f

6.2. When Cache is Invalidated

Cache is automatically invalidated:

  1. When directory TTL is exceeded

  2. After successful mv, cp, rm, touch, mkdir, upload

  3. When explicitly using -f flag with ls

7. Shell Escape Limitations

7.1. Host Commands Only

The ! shell escape executes on the host system, not ChRIS:

# This lists host files
$ ! ls

# This lists ChRIS files
$ ls

7.2. No Tab Completion

Tab completion does not work for commands after !:

# No completion for host paths
$ ! cat /etc/hos<tab>  # Does not complete

8. Performance Considerations

8.1. Large Directory Listings

Directories with thousands of files may be slow:

# First ls is slow (API call)
$ ls huge_directory/  # 2-5 seconds

# Subsequent ls is fast (cached)
# cache will invalidate after timeout
# and after any fs operations that change
# files (cp/mv/etc)
$ ls huge_directory/  # < 100ms

8.2. Wildcard Expansion Cost

Wildcards require fetching directory listings:

# Must fetch and filter
$ rm uploads/*  # Slower for large directories if not cached

9. Error Messages

9.1. Internal Server Error

Generic "Internal server error" from ChRIS backend can mean:

  1. Invalid path

  2. Permission denied

  3. Directory doesn’t exist

  4. File already exists

  5. Backend bug

Workaround: Check operation carefully and retry. Use ls -f to refresh state.

9.2. Path Resolution Failures

If paths fail to resolve, check:

  1. Current working directory: pwd

  2. Path exists: ls /full/path

  3. Permissions (ChRIS access control)

10. Best Practices

10.1. Always Use Quotes for Spaces

# Best practice of all is just don't put spaces in file or dir names
mv "source with spaces" "dest with spaces"

10.2. Test Dangerous Operations

# Test with ls first
$ ls uploads/*

# Then execute
$ rm uploads/*

10.3. Never Rename Non-Empty Directories

# BAD - will orphan files
$ mv uploads backup

# GOOD - move contents first
$ mkdir backup
$ mv uploads/* backup/
$ rm -rf uploads

10.4. Use -f to Force Refresh

# After external changes
$ ls -f

10.5. Verify Before Removing

# Use -i for interactive
$ rm -i important_file.txt
rm: remove 'important_file.txt'? (y/n):

11. Getting Help

11.1. Report Issues

If you encounter bugs or unexpected behavior:

  1. Note exact command sequence

  2. Check current directory with pwd

  3. Try ls -f to refresh cache

  4. Report to: https://github.com/FNNDSC/chell/issues

11.2. Debug Mode

Enable debug output:

$ debug on
$ # Run problematic command
$ debug off

11.3. Timing Mode

See command performance:

$ timing on
$ ls large_directory/
[1250.45ms]

Last updated: 2025-12-03