shell_helpers 0.6.0 → 0.7.0

data/lib/shell_helpers/run.rb

@@ -7,11 +7,7 @@ module ShellHelpers
 		extend(self)
 		RunError=Class.new(StandardError)
 
-		def sudo_args(sudoarg)
-			return "" unless sudoarg
-			return sudoarg.shellsplit if sudoarg.is_a?(String)
-			["sudo"]
-		end
+		## Trivial wrappers around Open3
 
 		#the run_* commands here capture all the output
 		def run_command(*command)
@@ -44,6 +40,19 @@ module ShellHelpers
 			r
 		end
 
+		## Launching a command
+		#handle sudo arguments
+
+		def sudo_args(sudoarg)
+			if sudoarg.respond_to?(:sudo_loop)
+				sudoarg.sudo_loop
+			end
+			return [] unless sudoarg
+			return sudoarg.shellsplit if sudoarg.is_a?(String)
+			["sudo"]
+		end
+
+		# get the args, environment and spawning options
 		def process_command(*args, **opts)
 			spawn_opts={}
 			if args.last.kind_of?(Hash)
@@ -56,7 +65,7 @@ module ShellHelpers
 				env,*args=*args
 			end
 			env.merge!(opts.delete(:env)||{})
-			args=args.map {|arg| arg.to_s} if args.length > 1
+			args=args.map.with_index {|arg, i| i == 0 && arg.is_a?(Array) ? arg : arg.to_s} if args.length > 1
 			spawn_opts.merge!(opts)
 			if sudo
 				if args.length > 1
@@ -68,22 +77,32 @@ module ShellHelpers
 			return env, args, spawn_opts
 		end
 
+		## Run a command
 		#by default capture stdout and status
+		# callbacks: yield status.success?, out, err, status if block_given?
+		#   if status.success? => on_success.call(status, out, err)
+		#		else error_mode.call(status, out, error)
+		#   rescue ... => fail_mode.call(e)
+		# return status, out, error
 		def run(*args, output: :capture, error: nil, fail_mode: :error, chomp: false, sudo: false, error_mode: nil, expected: nil, on_success: nil, quiet: nil, **opts)
-			env, args, spawn_opts=Run.process_command(*args, **opts)
+			env, args, spawn_opts=Run.process_command(*args, sudo: sudo, **opts)
 
-			if args.length > 1
-				launch=args.shelljoin
+			if args.is_a?(Array)
+				if args.length > 1
+					launch=args.shelljoin
+				else
+					launch=args.first #assume it has already been escaped
+				end
 			else
-				launch=args.first #assume it has already been escaped
+				launch=args.to_s
 			end
 			launch+=" 2>/dev/null" if error==:quiet or quiet
 			launch+=" >/dev/null" if output==:quiet
-			out=error=nil
+			out=err=nil
 
 			begin
 				if error==:capture
-					out, error, status=Open3.capture3(env, launch, spawn_opts)
+					out, err, status=Open3.capture3(env, launch, spawn_opts)
 				elsif output==:capture
 					out, status=Open3.capture2(env, launch, spawn_opts)
 				else
@@ -104,8 +123,9 @@ module ShellHelpers
 				end
 			end
 			status=ProcessStatus.new(status, expected) if expected
-			yield status.success?, out, err, status if block_given?
-			if status.success?
+			status_success=status.success? if status.respond_to? :success?
+			yield status_success, out, err, status if block_given?
+			if status_success
 				# this block is called in case of success
 				on_success.call(status, out, err) if on_success.is_a?(Proc)
 			else # the command failed
@@ -117,7 +137,7 @@ module ShellHelpers
 				when :error
 					raise RunError.new("Error running command '#{launch}': #{status}")
 				when Proc
-					error_mode.call(status, out, error)
+					error_mode.call(status, out, err)
 				end
 			end
 			if chomp and out
@@ -130,18 +150,27 @@ module ShellHelpers
 				end
 			end
 
-			return out, error, status if error
-			return out, status
+			# return out, error, status if error
+			return status, out, err
 		end
 
 		#a simple wrapper for %x//
+		#return the output; the block is called in case of an error
+		#eg SH.run_simple("echo foo; false") do p "error" end
+		#=> returns "foo\n" and prints error
 		def run_simple(*command, **opts, &b)
-			# here the block is called in case of failure
+			# here the block is called in case of error
 			opts[:error_mode]=b if b
-			out, *_rest = run(*command, **opts)
+			_status, out, _error = run(*command, **opts)
 			return out
 		end
 
+		# like run, but only returns status.success?
+		def run_success(*command, **opts, &b)
+			status, _out, _error = run(*command, **opts, &b)
+			status.success?
+		end
+
 		#same as Run, but if we get interrupted once, we don't want to launch any more commands
 		module Interrupt #{{{
 			extend(self)

data/lib/shell_helpers/sh.rb

@@ -57,6 +57,42 @@ module ShellHelpers
 		end
 	end
 	# }}}
+	
+	# SudoLoop {{{
+	# extend SudoLoop.configure to run a sudo loop
+	# SH.sh("ls /", sudo: "sudo".extend(SH::SudoLoop.configure(**opts))
+	module SudoLoop
+		extend self
+		def configure(**opts)
+			return Module.new do |m|
+				m.define_method(:sudo_loop) do
+					SudoLoop.instance_method(:run_sudo_loop).bind(self).call(**opts)
+				end
+				m.define_method(:stop_sudo_loop) do
+					SudoLoop.instance_method(:stop_sudo_loop).bind(self).call
+				end
+			end
+		end
+
+		def run_sudo_loop(command: "sudo -v", interval: 30, init_command: command)
+			if @sudo_loop_thread.nil? or !@sudo_loop_thread.alive?
+				Sh.sh_or_proc(init_command, log: false)
+				#require 'pry'; binding.pry
+				@sudo_loop_thread = Thread.new do
+					loop do
+						Sh.sh_or_proc(command, log: false)
+						sleep(interval)
+					end
+				end
+				@sudo_loop_thread.run
+			end
+		end
+
+		def stop_sudo_loop
+			@sudo_loop_thread&.kill
+		end
+	end #}}}
+
 	# Sh {{{
 	# Module with various helper methods for executing external commands.
 	# In most cases, you can use #sh to run commands and have decent logging
@@ -82,10 +118,10 @@ module ShellHelpers
 	#			 # This block isn't called, since the command failed
 	#		 end
 	#
-	#		 sh 'ls -l /tmp/' do |stdout|
+	#		 sh 'ls -l /tmp/', capture: true do |status, stdout|
 	#			 # stdout contains the output of the command
 	#		 end
-	#		 sh 'ls -l /tmp/ /non_existent_dir' do |stdout,stderr|
+	#		 sh 'ls -l /tmp/ /non_existent_dir', capture: true do |status, stdout,stderr|
 	#			 # stdout contains the output of the command,
 	#			 # stderr contains the standard error output.
 	#			end
@@ -108,16 +144,18 @@ module ShellHelpers
 	end
 	# }}}
 
+	ShError=Class.new(StandardError)
 	module Sh
 		include CLILogging
 		extend self
 		attr_writer :default_sh_options
 		def default_sh_options
-			@default_sh_options||={log: true, capture: false, on_success: nil, on_failure: nil, expected:0, dryrun: false, escape: false,
+			@default_sh_options||={log: true, capture: false, on_success: nil, on_error: nil, expected:0, dryrun: false, escape: false,
 			log_level_execute_debug: :debug,
 			log_level_execute: :info, log_level_error: :error,
 			log_level_stderr: :error, log_level_stdout_success: :info,
-			log_level_stdout_fail: :warn, detach: false}
+			log_level_stdout_fail: :warn, detach: false,
+			mode: :system}
 		end
 
 		attr_writer :spawned
@@ -131,14 +169,14 @@ module ShellHelpers
 		# callback called by sh to select the exec mode
 		# mode: :system,:spawn,:exec,:capture
 		# opts: sudo, env
-		def shrun(*args,mode: :system, **opts)
+		def shrun(*args,mode: :system, block: nil, **opts)
 			env, args, spawn_opts=Run.process_command(*args, **opts)
 			# p env, args, spawn_opts
 			case mode
 			when :system
 				system(env,*args,spawn_opts)
 			when :spawn, :detach
-				pid=spawn(env,*args,spawn_opts)
+				pid=spawn(env,*args,spawn_opts, &block)
 				if mode==:detach
 					Process.detach(pid) 
 				else
@@ -151,11 +189,13 @@ module ShellHelpers
 					end
 				end
 			when :exec
-				exec(env,*args,spawn_opts)
+				exec(env,*args,spawn_opts, &block)
 			when :capture
-				Run.run_command(env,*args,spawn_opts)
+				Run.run_command(env,*args,spawn_opts, &block)
 			when :run
-				Run.run(env,*args,spawn_opts)
+				Run.run(env,*args,spawn_opts, &block)
+			else
+				raise ShError.new("In shrun, mode #{mode} not understood")
 			end
 		end
 
@@ -166,7 +206,7 @@ module ShellHelpers
 		# error output is logged at WARN.
 		#						+:expected+:: an Int or Array of Int representing error codes, <b>in addition to 0</b>, that are expected and therefore constitute success.  Useful for commands that don't use exit codes the way you'd like
 		#			name: pretty name of command
-		#			on_success,on_failure: blocks to call on success/failure
+		#			on_success,on_error: blocks to call on success/failure
 		# block:: if provided, will be called if the command exited nonzero.	The block may take 0, 1, 2, or 3 arguments.
 		#					The arguments provided are the standard output as a string, standard error as a string, and the processstatus as SH::ProcessStatus
 		#					You should be safe to pass in a lambda instead of a block, as long as your lambda doesn't take more than three arguments
@@ -180,9 +220,13 @@ module ShellHelpers
 		#				# ...
 		#			end
 		#
-		# Returns the exit status of the command.  Note that if the command doesn't exist, this returns 127.
+		# Returns the exit status of the command (Note that if the command doesn't exist, this returns 127.), stdout, stderr and the full status of the command
 
-		def sh(*command, **opts, &block)
+		# callbacks: on_success, on_error
+		# yield process_status.success?,stdout,stderr,process_status if block_given?
+		# returns success; except in capture mode where it returns success,
+		# stdout, stderr, process_status
+		def sh(*command, argv0: nil, **opts)
 			defaults=default_sh_options
 			curopts=defaults.dup
 			defaults.keys.each do |k|
@@ -191,13 +235,19 @@ module ShellHelpers
 			end
 
 			log=curopts[:log]
-			# command=command.first if command.length==1 and command.first.kind_of?(Array) #so that sh(["ls", "-a"]) works
+			command=[[command.first, argv0], *command[1..-1]] if argv0 and command.length > 1 and !curopts[:escape]
+
+			if command.length==1 and command.first.kind_of?(Array) #so that sh(["ls", "-a"]) works
+				command=command.first
+				command=[[command.first, argv0], *command[1..-1]] if argv0 and !curopts[:escape]
+			end
 			command_name = curopts[:name] || command_name(command) #this keep the options
+			# this should not be needed
 			command=command.shelljoin if curopts[:escape]
 			if log
 				sh_logger.send(curopts[:log_level_execute], SimpleColor.color("Executing '#{command_name}'",:bold))
 				p_env, p_args, p_opts= Run.process_command(*command, **opts)
-				sh_logger.send(curopts[:log_level_execute_debug], SimpleColor.color("Debug execute: '#{[p_env, *p_args, p_opts]}'", :bold))
+				sh_logger.send(curopts[:log_level_execute_debug], SimpleColor.color("Debug execute: #{[p_env, *p_args, p_opts]}", :bold))
 			end
 
 			if !curopts[:dryrun]
@@ -208,15 +258,9 @@ module ShellHelpers
 					_pid = shrun(*command,**opts, mode: mode)
 					status=0; stdout=nil; stderr=nil
 				elsif curopts[:mode]==:run
-					*res=shrun(*command,**opts,mode: :capture)
-					case res.length
-					when 2
-						stdout, status=res; stderr=nil
-					when 3
-						stdout, stderr, status=res
-					end
+					status, stdout, stderr=shrun(*command,mode: curopts[:mode], **opts)
 				else
-					mode=curopts[:mode]||:system
+					mode = curopts[:mode] || :system
 					shrun(*command,mode: mode, **opts)
 					status=$?; stdout=nil; stderr=nil
 				end
@@ -230,17 +274,26 @@ module ShellHelpers
 			if process_status.success?
 				sh_logger.send(curopts[:log_level_stdout_success], SimpleColor.color("stdout output of '#{command_name}':\n",:bold,:green)+stdout) unless stdout.nil? or stdout.strip.length == 0 or !log
 				curopts[:on_success].call(stdout,stderr,process_status) unless curopts[:on_success].nil?
-				block.call(stdout,stderr,process_status) unless block.nil?
+				# block.call(stdout,stderr,process_status) unless block.nil?
 			else
 				sh_logger.send(curopts[:log_level_stdout_fail], SimpleColor.color("stdout output of '#{command_name}':\n",:bold,:yellow)+stdout) unless stdout.nil? or stdout.strip.length == 0 or !log
 				sh_logger.send(curopts[:log_level_error], SimpleColor.color("Error running '#{command_name}': #{process_status.status}",:red,:bold)) if log
-				curopts[:on_failure].call(stdout,stderr,process_status) unless curopts[:on_failure].nil?
+				curopts[:on_error].call(stdout,stderr,process_status) unless curopts[:on_error].nil?
+			end
+			yield process_status.success?,stdout,stderr,process_status if block_given?
+			if curopts[:capture] || curopts[:mode]==:capture || curopts[:mode]==:run
+				return process_status.success?,stdout,stderr,process_status
+			else
+				return process_status.success?
 			end
-			return process_status.success?,stdout,stderr,process_status
 
 		rescue SystemCallError => ex
 			sh_logger.send(curopts[:log_level_error], SimpleColor.color("Error running '#{command_name}': #{ex.message}",:red,:bold)) if log
-			return 127
+			if block_given?
+				yield 127, nil, nil, nil
+			else
+				return 127, nil, nil, nil
+			end
 		end
 
 		# Run a command, throwing an exception if the command exited nonzero.
@@ -253,11 +306,11 @@ module ShellHelpers
 		#			sh!("rsync foo bar", :failure_msg => "Couldn't rsync, check log for details")
 		#			# => if command fails, app exits and user sees: "error: Couldn't rsync, check log for details
 		def sh!(*args,failure_msg: nil,**opts, &block)
-			on_failure=Proc.new do |*blockargs|
+			on_error=Proc.new do |*blockargs|
 				process_status=blockargs.last
 				raise FailedCommandError.new(process_status.exitstatus,command_name(args),failure_msg: failure_msg)
 			end
-			sh(*args,**opts,on_failure: on_failure,&block)
+			sh(*args,**opts,on_error: on_error,&block)
 		end
 
 		# Override the default logger (which is the one provided by CLILogging).
@@ -277,6 +330,20 @@ module ShellHelpers
 			end
 		end
 
+		# returns only the success or failure
+		def sh_or_proc(cmd, *args, **opts, &b)
+			case cmd
+			when Proc
+				cmd.call(*args, **opts, &b)
+			when Array
+				suc, _r=SH.sh(*cmd, *args, **opts, &b)
+				suc
+			when String
+				suc, _r=SH.sh(cmd + " #{args.shelljoin}", **opts, &b)
+				suc
+			end
+		end
+
 	private
 		def command_name(command)
 			if command.size == 1
@@ -369,8 +436,8 @@ ng or provide your own via #change_sh_logger." unless self.respond_to?(:logger)
 			cargs=Array(cmd_prepend) + [cmd] + dopts + Array(opts) + args + Array(cmd_postpone)
 			if !b
 				if method
-					b=lambda do |*args|
-						SH.public_send(method, *args)
+					b=lambda do |*args, **kw|
+						SH.public_send(method, *args, **kw)
 					end
 				else
 					b=lambda do |*args|

data/lib/shell_helpers/sysutils.rb

@@ -10,6 +10,8 @@ module ShellHelpers
 		SysError=Class.new(StandardError)
 
 		# wrap 'stat'
+		# @example
+		# SH.stat_file("mine") => {:access=>"700", :blocknumber=>0,...}
 		def stat_file(file)
 			require 'time'
 			opts=%w(a b B f F g G h i m n N o s u U w x y z)
@@ -37,9 +39,14 @@ module ShellHelpers
 			r[:statustime] = begin Time.parse(stats[19]) rescue nil end
 			r
 		end
+
 		# wrap stat --file-system
+		# @example
+		# SH.stat_filesystem("mine") => {:userfreeblocks=>..., fstype=>"btrfs"}
 		def stat_filesystem(file, up: true)
-			if up
+			if up #output the fs info of the first ascending path that exist
+				# usefull to get infos of the filesystem of a file we want to create
+				# but does not yet exist
 				file=Pathname.new(file)
 				file.ascend.each do |f|
 					return stat_filesystem(f, up: false) if f.exist?
@@ -47,7 +54,7 @@ module ShellHelpers
 			end
 			opts=%w(a b c d f i l n s S T)
 			stats=Run.run_simple("stat --file-system --format='#{opts.map{|o| "%#{o}\n"}.join}' #{file.shellescape}", chomp: :lines)
-			stats=stats.each_line.map {|l| l.chomp}
+			#stats=stats.each_line.map {|l| l.chomp}
 			r={}
 			r[:userfreeblocks]=stats[0].to_i
 			r[:totalblocks]=stats[1].to_i
@@ -93,6 +100,8 @@ module ShellHelpers
 		#   :type=>"swap",
 		#   :partlabel=>"swap",
 		#   :partuuid=>"f4eef373-0803-4701-bd47-b968c44065a6"}
+		# @exemple
+		# SH.blkid => {"/dev/sda1"=> {:devname=>"/dev/sda1", :sec_type=>"msdos", :label_fatboot=>"boot", :label=>"boot", :uuid=>"D906-BEB0", :partlabel=>"boot", :partuuid=>"...",:fstype=>"vfat"}, ...}
 		def blkid(*args, sudo: false)
 			# get devname, (part)label/uuid, fstype
 			fsoptions=Run.run_simple("blkid -o export #{args.shelljoin}", fail_mode: :empty, chomp: true, sudo: sudo)
@@ -100,6 +109,8 @@ module ShellHelpers
 		end
 
 		# use lsblk to get infos about devices
+		# @exemple
+		# SH.lsblk => {"/dev/sda"=>{:devname=>"/dev/sda", :devtype=>"disk"}, "/dev/sda1"=> {:devname=>"/dev/sda1", :label=>"boot", :uuid=>"D906-BEB0", :partlabel=>"boot", :partuuid=>"00000000-0000-0000-0000-000000000000", :parttype=>"c12a7328-f81f-11d2-ba4b-00a0c93ec93b", :devtype=>"part", :fstype=>"vfat"},...}
 		def lsblk(sudo: false)
 			# get devname, mountpoint, (part)label/uuid, (part/dev/fs)type
 			fsoptions=Run.run_simple("lsblk -l -J -o NAME,MOUNTPOINT,LABEL,UUID,PARTLABEL,PARTUUID,PARTTYPE,TYPE,FSTYPE", fail_mode: :empty, chomp: true, sudo: sudo)
@@ -123,6 +134,8 @@ module ShellHelpers
 		end
 
 		# use findmnt to get infos about mount points
+		# @exemple
+		# SH.findmnt => {"/dev/bcache0[/slash]"=> {:mountpoint=>"/", :devname=>"/dev/bcache0[/slash]", :fstype=>"btrfs", :mountoptions=> ["rw", "noatime", "compress=lzo", "ssd", "space_cache", "autodefrag", "subvolid=257", "subvol=/slash"], :label=>"rootleaf", :uuid=>"1db5b600-df3e-4d1e-9eef-6a0a7fda491d", :partlabel=>"", :partuuid=>"", :fsroot=>"/slash"}, ...}
 		def findmnt(sudo: false)
 			# get devname, mountpoint, mountoptions, (part)label/uuid, fsroot
 			# only looks at mounted devices (but in comparison to lsblk also show
@@ -139,6 +152,8 @@ module ShellHelpers
 			fs
 		end
 		
+		# we default to lsblk
+		# findmnt adds the subvolumes, the fsroot and the mountoptions
 		def fs_infos(mode: :devices)
 			return findmnt if mode == :mount
 			return lsblk.merge(findmnt) if mode == :all
@@ -151,6 +166,9 @@ module ShellHelpers
 		end
 
 		# find devices matching props
+		# @exemple
+		# SH.find_devices({label: "boot"})
+		# => [{:devname=>"/dev/sda1", :label=>"boot", :uuid=>"D906-BEB0", :partlabel=>"boot", :partuuid=>"...", :parttype=>"c12a7328-f81f-11d2-ba4b-00a0c93ec93b", :devtype=>"part", :fstype=>"vfat"}]
 		def find_devices(props, method: :all)
 			props=props.clone
 			return [{devname: props[:devname]}] unless props[:devname].nil?
@@ -161,6 +179,10 @@ module ShellHelpers
 			end
 
 			if method==:blkid
+				# try with UUID, then LABEL, then PARTUUID
+				# as soon as we have a non empty label, we return the result of
+				# blkid on it.
+				#
 				# Warning, since 'blkid' can only test one label, we cannot check
 				# that all parameters are valid
 				# search from most discriminant to less discriminant
@@ -174,21 +196,27 @@ module ShellHelpers
 				if props[:parttype]
 					find_devices(props, method: :all)
 				end
-			else
+			else #method=:all
 				fs=fs_infos
-				# here we check all parameters
+				# here we check all parameters (ie all defined labels are correct)
 				# however, if none are defined, this return true, so we check that at least one is defined
 				return [] unless %i(uuid label partuuid partlabel parttype).any? {|k| props[k]}
 				return fs.keys.select do |k|
 					fsprops=fs[k]
-					# the fsinfos should have one of this parameters defined
-					next false unless %i(uuid label partuuid partlabel parttype).any? {|k| fsprops[k]}
 					next false if (disk=props[:disk]) && !fsprops[:devname].start_with?(disk.to_s)
-					%i(uuid label partuuid partlabel parttype).all? do |key|
+					# all defined labels should match
+					next false unless %i(uuid label partuuid partlabel parttype).all? do |key|
 						ptype=props[key]
 						ptype=partition_type(ptype) if key==:parttype and ptype.is_a?(Symbol)
 						!ptype or !fsprops[key] or ptype==fsprops[key]
 					end
+					# their should at least be one matching label
+					next false unless %i(uuid label partuuid partlabel parttype).select do |key|
+						ptype=props[key]
+						ptype=partition_type(ptype) if key==:parttype and ptype.is_a?(Symbol)
+						ptype and fsprops[key] and ptype==fsprops[key]
+					end.length > 0
+					true
 				end.map {|k| fs[k]}
 			end
 			return []
@@ -204,6 +232,19 @@ module ShellHelpers
 			return devs.first&.fetch(:devname)
 		end
 
+		# Mount devices on paths
+		# @argument
+		# - paths: Array (or Hash) of path
+		# => path: {mountpoint: "/mnt", mountoptions: [], fstype: "ext4",
+		# subvol: ..., device_info}
+		# where device_info is used to find the device via find_device
+		# so can be set via :devname, or uuid label partuuid partlabel parttype
+		# @opts
+		# - sort: sort the mountpoints
+		# - abort_on_error: fail if a mount failt
+		# - mkpath: mkpath the mountpoints
+		# @return
+		# the paths and a lambda to unmount
 		def mount(paths, mkpath: true, abort_on_error: true, sort: true)
 			paths=paths.values if paths.is_a?(Hash)
 			paths=paths.select {|p| p[:mountpoint]}
@@ -244,6 +285,9 @@ module ShellHelpers
 			end
 		end
 
+		# by default give symbol => guid
+		# can also give symbol => hexa (mode: :hexa)
+		# or hexa/guid => symbol (mode: :symbol)
 		def partition_type(type, mode: :guid)
 			if mode==:symbol
 				%i(boot swap home x86_root x86-64_root arm64_root arm32_root linux).each do |symb|
@@ -272,6 +316,8 @@ module ShellHelpers
 			end
 		end
 
+		# @exemple
+		# SH.partition_infos("/dev/sda", sudo: true) => [{:partlabel=>"boot", :partattributes=>"0000000000000004", :partuuid=>"00000000-0000-0000-0000-000000000000", :parttype=>"c12a7328-f81f-11d2-ba4b-00a0c93ec93b"}, {:partlabel=>"swap", :partattributes=>"0000000000000000", :partuuid=>"f4eef373-0803-4701-bd47-b968c44065a6", :parttype=>"0fc63daf-8483-4772-8e79-3d69d8477de4"}, {:partlabel=>"slash", :partattributes=>"0000000000000000", :partuuid=>"31b4cd66-39ab-4c5b-a229-d5d2010d53dd", :parttype=>"0fc63daf-8483-4772-8e79-3d69d8477de4"}]
 		def partition_infos(device, sudo: false)
 			parts = Run.run_simple("partx -o NR --show #{device.shellescape}", sudo: sudo) { return nil }
 			infos=[]
@@ -295,7 +341,16 @@ module ShellHelpers
 			infos
 		end
 
-		#options: check => check that no partitions exist first
+		#@argument
+		#  A list of partitions
+		#  Note that here the device has to be specified with :disk; looking at
+		#  PARTLABEL or things like that don't make sense if the partitions
+		#  don't exist
+		#@options:
+		# - check => check that no partitions exist first
+		# - partprobe: run partprobe if we made partitions
+		# @exemple
+		# SH.make_partitions( {:boot=> {:parttype=>:boot, :partlength=>"+100M", :fstype=>"vfat", :rel_mountpoint=>"boot", :mountoptions=>["fmask=133"]}, :slash=> {:parttype=>:"x86-64_root", :fstype=>"ext4", :rel_mountpoint=>"."}, ...})
 		def make_partitions(partitions, check: true, partprobe: true)
 			partitions=partitions.values if partitions.is_a?(Hash)
 			done=[]
@@ -351,6 +406,9 @@ module ShellHelpers
 			Sh.sh("wipefs -a #{disk.shellescape}", sudo: true)
 		end
 
+		# make filesystems
+		# takes a list of fs infos (where the device is specified like before,
+		# via devname, label, ...)
 		def make_fs(fs, check: true)
 			fs=fs.values if fs.is_a?(Hash)
 			fs.each do |partfs|
@@ -378,6 +436,7 @@ module ShellHelpers
 			end
 		end
 
+		# use fallocate to make a raw image
 		def make_raw_image(name, size="1G")
 			raw=Pathname.new(name)
 			raw.touch
@@ -387,6 +446,7 @@ module ShellHelpers
 			raw
 		end
 
+		# makes a btrfs subvolume
 		def make_btrfs_subvolume(dir, check: true)
 			if check and dir.directory?
 				raise SysError("Subvolume already exists at #{dir}") if check==:raise
@@ -396,6 +456,8 @@ module ShellHelpers
 				dir
 			end
 		end
+
+		# try to make a subvolume, else fallsback to a dir
 		def make_dir_or_subvolume(dir)
 			dir=Pathname.new(dir)
 			return :directory if dir.directory?
@@ -409,6 +471,7 @@ module ShellHelpers
 			end
 		end
 
+		# runs losetup, and returns the created disk, and a lambda to close
 		def losetup(img)
 			disk = Run.run_simple("losetup -f --show #{img.shellescape}", sudo: true, chomp: true, error_mode: :nil)
 			close=lambda do