Rex::Commands::Fs(3)

📦 version 1.14.3, in nixos 26.05, nixpkgs unstable

okay bestie, this is the user-contributed Perl documentation for Rex::Commands::Fs — the file-system commands module. we’re about to go through it together, and yes, it’s gonna be a lot. stay with me 🫶

💖 NAME 💖

Rex::Commands::Fs — file system commands ✨

🌸 DESCRIPTION 🌸

with this module you can do file system tasks like creating directories, deleting or moving files, and more. it’s giving filesystem glow-up energy 🦋

✨ SYNOPSIS ✨

 my @files = list_files "/etc";

 unlink("/tmp/file");

 rmdir("/tmp");
 mkdir("/tmp");

 my %stat = stat("/etc/passwd");

 my $link = readlink("/path/to/a/link");
 symlink("/source", "/dest");

 rename("oldname", "newname");

 chdir("/tmp");

 is_file("/etc/passwd");
 is_dir("/etc");
 is_writeable("/tmp");
 is_writable("/tmp");

 chmod 755, "/tmp";
 chown "user", "/tmp";
 chgrp "group", "/tmp";

👑 EXPORTED FUNCTIONS 👑

🛠️ Changing content 🛠️

okay so these ones are supposed to change what’s in the file system — literally the content-changing crew 💅

🎀 `symlink($from, $to)`

this function will create a symbolic link from $from to $to. iconic behavior, no cap 🔥

task "symlink", "server01", sub {
  symlink("/var/www/versions/1.0.0", "/var/www/html");
};

🎀 `ln($from, $to)`

ln is an alias for symlink — same vibe, shorter name 🫶

🎀 `unlink($file)`

this function will remove the given $file. bye bestie 👋

task "unlink", "server01", sub {
  unlink("/tmp/testfile");
};

🎀 `rm($file)`

this is an alias for unlink. yes, it’s that simple 💖

🎀 `rmdir($dir)`

this function will remove the given directory.

task "rmdir", "server01", sub {
  rmdir("/tmp");
};

with Rex-0.45 and newer, please use the file resource instead.

task "prepare", sub {
  file "/tmp",
    ensure => "absent";
};

🎀 `mkdir($newdir)`

this function will create a new directory.

the following options are supported:

owner — supported option 🫶
group — supported option 🫶
mode — supported option 🫶
on_change — supported option 🫶

with Rex-0.45 and newer, please use the file resource instead.

task "prepare", sub {
  file "/tmp",
    ensure => "directory",
    owner  => "root",
    group  => "root",
    mode   => 1777;
};

direct usage, bestie:

task "mkdir", "server01", sub {
  mkdir "/tmp";

  mkdir "/tmp",
    owner => "root",
    group => "root",
    mode => 1777;
};

🎀 `chown($owner, $path)`

change the owner of a file or a directory.

chown "www-data", "/var/www/html";

chown "www-data", "/var/www/html",
               recursive => 1;

real talk: this command will not be reported. if you want to use reports, please use the file resource instead 💅

🎀 `chgrp($group, $path)`

change the group of a file or a directory.

chgrp "nogroup", "/var/www/html";

chgrp "nogroup", "/var/www/html",
             recursive => 1;

heads up: this command will not be reported. if you want reports, please use the file resource instead 🫶

🎀 `chmod($mode, $path)`

change the permissions of a file or a directory.

chmod 755, "/var/www/html";

chmod 755, "/var/www/html",
         recursive => 1;

this command will not be reported. if you want to use reports, please use the file resource instead ✨

🎀 `rename($old, $new)`

this function will rename $old to $new. will return 1 on success and 0 on failure.

task "rename", "server01", sub {
  rename("/tmp/old", "/tmp/new");
};

🎀 `mv($old, $new)`

mv is an alias for rename — same thing, different little name 🦋

🎀 `cp($source, $destination)`

cp will copy $source to $destination recursively.

task "cp", "server01", sub {
   cp("/var/www", "/var/www.old");
};

🌈 Not changing content 🌈

these ones are not supposed to change the contents of the file system, bestie. very demure, very mindful 💜

🎀 `list_files("/path");`

this function lists all entries (files, directories, ...) in a given directory and returns them as an array.

task "ls-etc", "server01", sub {
  my @tmp_files = grep { /\.tmp$/ } list_files("/etc");
};

this command will not be reported 💅

🎀 `ls($path)`

just an alias for list_files. cute and convenient 🎀

🎀 `stat($file)`

this function will return a hash with the following information about a file or directory:

mode
size
uid
gid
atime
mtime

task "stat", "server01", sub {
  my %file_stat = stat("/etc/passwd");
};

this command will not be reported ✨

🎀 `is_file($path)`

this function tests if $path is a file. returns 1 if true, 0 if false.

task "isfile", "server01", sub {
  if( is_file("/etc/passwd") ) {
    say "it is a file.";
  }
  else {
    say "hm, this is not a file.";
  }
};

this command will not be reported 🫶

🎀 `is_dir($path)`

this function tests if $path is a directory. returns 1 if true, 0 if false.

task "isdir", "server01", sub {
  if( is_dir("/etc") ) {
    say "it is a directory.";
  }
  else {
    say "hm, this is not a directory.";
  }
};

this command will not be reported 💖

🎀 `is_symlink($path)`

this function tests if $path is a symbolic link. returns 1 if true, 0 if false.

task "issym", "server01", sub {
  if( is_symlink("/etc/foo.txt") ) {
    say "it is a symlink.";
  }
  else {
    say "hm, this is not a symlink.";
  }
};

this command will not be reported 🦋

🎀 `is_readable($path)`

this function tests if $path is readable. it returns 1 if true, 0 if false.

task "readable", "server01", sub {
  if( is_readable("/etc/passwd") ) {
    say "passwd is readable";
  }
  else {
    say "not readable.";
  }
};

this command will not be reported 🌸

🎀 `is_writable($path)`

this function tests if $path is writable. it returns 1 if true, 0 if false.

task "writable", "server01", sub {
  if( is_writable("/etc/passwd") ) {
    say "passwd is writable";
  }
  else {
    say "not writable.";
  }
};

this command will not be reported 💅

🎀 `is_writeable($file)`

this is only an alias for is_writable. same energy, extra e 🫶

🎀 `readlink($link)`

if $link is a symbolic link, returns the path it resolves to, and die()s otherwise.

task "islink", "server01", sub {
  my $link;
  eval {
    $link = readlink("/tmp/testlink");
  };

  say "this is a link" if($link);
};

this command will not be reported ✨

🎀 `chdir($newdir)`

this function will change the working directory to $newdir. this function currently works only locally.

task "chdir", "server01", sub {
  chdir("/tmp");
};

this command will not be reported 💖

🎀 `cd($newdir)`

this is an alias of chdir — saving your fingers, one alias at a time 🎀

🎀 `df([$device])`

this function returns a hash reference which reflects the output of df.

task "df", "server01", sub {
   my $df = df();
   my $df_on_sda1 = df("/dev/sda1");
};

this command will not be reported 🌈

🎀 `du($path)`

returns the disk usage of $path.

task "du", "server01", sub {
  say "size of /var/www: " . du("/var/www");
};

this command will not be reported 🫶

🎀 `mount($device, $mount_point, @options)`

mount devices.

task "mount", "server01", sub {
  mount "/dev/sda5", "/tmp";
  mount "/dev/sda6", "/mnt/sda6",
         ensure    => "present",
         type      => "ext3",
         options   => [qw/noatime async/],
         on_change => sub { say "device mounted"; };
  #
  # mount persistent with entry in /etc/fstab

  mount "/dev/sda6", "/mnt/sda6",
         ensure     => "persistent",
         type       => "ext3",
         options    => [qw/noatime async/],
         on_change  => sub { say "device mounted"; };

  # to umount a device
  mount "/dev/sda6", "/mnt/sda6",
         ensure => "absent";

};

real talk: in order to be more aligned with mount terminology, the previously used fs option has been deprecated in favor of the type option. the fs option is still supported and works as previously, but Rex prints a warning if it is being used. there’s also a warning if both fs and type options are specified, and in this case type will be used. iykyk 💅

🎀 `umount($mount_point)`

unmount device.

task "umount", "server01", sub {
  umount "/tmp";
};

🎀 `glob($glob)`

returns the list of filename expansions for $glob as Perl’s built-in glob at https://perldoc.perl.org/functions/glob.html would do.

task "glob", "server1", sub {
  my @files_with_p = grep { is_file($_) } glob("/etc/p*");
};

this command will not be reported 🦋

okay that’s the whole page, bestie 😭💖 this is Rex::Commands::Fs(3) from perl v5.42.3, dated 2023-08-05 — mwah, go be iconic with your filesystem 🫶✨

📦 where this page comes from

nixos 26.05: perl5.42.3-Rex 1.14.3
nixpkgs unstable: perl5.42.3-Rex 1.14.3
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

Rex::Commands::Fs(3)

💖 NAME 💖

🌸 DESCRIPTION 🌸

✨ SYNOPSIS ✨

👑 EXPORTED FUNCTIONS 👑

🛠️ Changing content 🛠️

🎀 symlink($from, $to)

🎀 ln($from, $to)

🎀 unlink($file)

🎀 rm($file)

🎀 rmdir($dir)

🎀 mkdir($newdir)

🎀 chown($owner, $path)

🎀 chgrp($group, $path)

🎀 chmod($mode, $path)

🎀 rename($old, $new)

🎀 mv($old, $new)

🎀 cp($source, $destination)

🌈 Not changing content 🌈

🎀 list_files("/path");

🎀 ls($path)

🎀 stat($file)

🎀 is_file($path)

🎀 is_dir($path)

🎀 is_symlink($path)

🎀 is_readable($path)

🎀 is_writable($path)

🎀 is_writeable($file)

🎀 readlink($link)

🎀 chdir($newdir)

🎀 cd($newdir)

🎀 df([$device])

🎀 du($path)

🎀 mount($device, $mount_point, @options)

🎀 umount($mount_point)

🎀 glob($glob)