lsRoot to dump root contents to terminal


I have written a command line executable that can quickly dump the contents of a root file to the screen w/o having to open a root session. I have placed a tarball of the code in my cern afs space:


One can simply unpack the tarball and issue make and then throw the executable into a bin directory.

Most everything that lsRoot does can be done w/i root cint, I just found some basic things could be done faster on the command line.

i.e. searching for a branch in a ttree w/ lsRoot:

lsRoot -T myfile.root:/someDir/myTree | grep myBranch
or if impatient:
lsRoot -RT myfile.root | grep -i ‘regexp’

(-R recursively search root file, -T TTree::Print(“toponly”))

TH1::GetEntries() on some hist:

lsRoot -N myfile.root:/someDir/*

will print all objects in the specified root directory and include the number of entries. There are many ways to output the information in the root file even user-defined outputs such as:

lsRoot --custom ‘\N\I\A\D\d\h’ -P ‘TPRegexp’ file.root

This last example will print all files that match the regular expression TDirectory/TKey::GetName() specified w/ the -P option and display results as specified w/ the --custom option where in the above example:

\N=TH1::GetEntries(),\I=Integral(),\A=Mean(),\D=RMS(), \d=TKey::GetPath()/\h=TKey::GetName().

This above example can be useful in conjunction w/ the ‘diff’ command to ensure that code cleanup on a large root based project did not affect the output root files.

If the TKey is not of an appropriate class then the above functions simply will not be called. One can also easily print objects in the file (TH1, TCanvas) to a ps(.pdf) file where the user can steer the desired hists w/ the -p/-P rootPath option and further specify how many hists per page. A user can use the --merge option to extract say a set of interesting histograms from a very large root-file and save them into a smaller root file. Where --merge just uses hadd.c code adapted to accept a path to the given hists.

lsRoot --merge keep=mySlimmedFile myLargeFile.root:/dir1/dir2/*

There are many more options available one just needs to start w/ ‘lsRoot --help’ to see all available options. lsRoot supports root recusrion, bash file system traversing, bash file system recursion, does not require root files to end in ‘.root’ (checks the header and ensures file is binary).

To get color formatting and other configurable options copy .lsRoot_colors to $HOME.

Lastly lsRoot will do admittedly silly things such as drawing ascii versions of TH1s and TH2s. This last option was just out of curiosity on my part and is not what I intend lsRoot to be all about.

Hope this can be useful for some.



awesome! Very nice! And I totally agree that a command line tool for listing the content of ROOT files would be good to have. Already the implementation of the ASCII hist drawing is worth a lot (e.g. for people with screen readers). Anyone interested: copy .lsRoot_colors to your home and run lsRoot --draw hsimple.root. It’s amazing!!! I had to patch a few files for Ubuntu 10.04 64bit; patch attached.

Is it possible to strip hadd.{cpp,h} out and instead call the existing binary? You said you modified it: can you suggest a patch to hadd that does what you need? If I understand correctly this patch would actually make sense also for stand-alone hadd.

I will advocate your tool over here, let’s see whether other people fall in love with it like I did :slight_smile: If they do: would you allow us to include (some of) it in ROOT, under our standard copyright and license (LGPL)? And would you help us with maintaining it for a while? Again: I am not deciding whether it will become part of ROOT. But I will try to convince the others that it should! Until then I am happy to have it so I can already use it :slight_smile:

Thank you!

Cheers, Axel.
lsRoot-Ubu1004.txt (704 Bytes)

Hi Axel,

Yes I agree it would be better to call the existing binary for hadd. Yes, as you said the I simply took the existing code for hadd and added in a statement to control what part of the file is to be added.

Yes I would be happy to allow you all to include any part of it in the main release. Unfortunately it surely would not compile in a windows environment since I use a few pseuodo c-style headers to control window size, whether input is to the terminal or pipe, reading in file-system directories <dirent.h>, etc. Perhaps all of these methods exist in TSystem?

I would be willing to help in maintainence.

Glad that you like it.



thanks for your reply! Could you try to use TSystem as much as possible? Getenv() is there, OpenDirectory() / GetDirEntry() is there - the most relevant functions should be available. For the pipe check it’s okay if it only works on non-Windows platforms; for the terminal size (width, I suppose?) you can default to 80 on Windows, and colors are simply not supported and that’s fine.

What do you think, is that worth a try?

Cheers, Axel.


Yes this sounds reasonable to me. I could probably make the changes in a couple of days. I will let you know.


Hi Axel,

Ok I made the changes to TSystem and have removed all references to DIR from <dirent.h> and am using gSystem->Getenv() instead of the pseudo c equivalent. I have also placed a few:

#ifndef WIN32


for code that should be ignored in a windows environment. So color is disabled in windows, the anticipation of a pipe is also disabled(in windows)–which was generally only used to turn off color if output was redirected to a file. I also only check the window size of a terminal if WIN32 is not defined. The window size is default at 80, but configurable in .lsRoot_colors so if a windows user wanted a larger window they could set a default value there.

So I have no idea if this will compile in Windows now. Is there a way I could test remotely on a windows machine–or is there a windows emulator that I could use? I may be able to borrow a friends computer that has a windows boot. Are there instructions on the main root page about what compiler should be used on windows? Such as visual studio etc.

For all versions I have removed ‘hadd.cpp/.h’ eventually I may make additions to hadd and suggest that this code also be implemented in hadd.

BTW the new version is here:


incorporating hopefully the ubuntu patch you gave earlier. Kind of weird that my compiler allows use of std::sort(iter,iter) w/o including .

Anyways let me know if you have any other suggestions such as less source files, coding cleanup, etc.


I’m looking forward to trying out this package.

One comment, regarding
>I have also placed a few:
> #ifndef WIN32
> #endif

I write lots of code for both windows and linux, and my understanding is the proper item to check is _WIN32 .
(with a leading underscore).



One more note about hadd. Instead of using the external command you could also consider using the class TFileMerger which has similar functionality.



I just want to voice my support for incorporating some or all of this fantastic tool’s functionality into root. Root sorely needs tools for quickly dumping tree content – using Justin’s tool to easily search through trees and dump out histogram content has been a real time saver for me.



I’m considering to include this package in gentoo science overlay, so I’m interested under what license lsroot is distributed. There is no mention of the license in the sources from /afs/ directory. But lsroot uses hadd.cpp from the ROOT source, and ROOT is licensed under LGPL-2.1. That’s why, according to LGPL-2.1, lsroot must be distributed under either LGPL-2.1 or GPL-2 and higher.

Thus lsroot is free software but with still undefined license, so it will be good if author will add a license statement to his package.


Awhile ago, I have added this package to sourceforge using this license:

GNU Library or “Lesser” General Public License version 3.0 (LGPLv3)

Please let me know if there is a problem with this. I have added many extra features since I have last update the versions in my cern afs public area.


Any news concerning lsRoot integration into ROOT?

See the new command line rootls.

Attaching the original lsRoot.
lsRoot.tgz (39.7 KB)