inxi/README.txt

README for inxi - a command line system information tool

The new Perl inxi is now here! File all issue reports with the master
branch. All support for versions prior to 3.0 is now ended, sorry. 

Make sure to update to the current inxi from the master branch before 
filing any issue reports. The code in pre 2.9 versions literally no 
longer exists in inxi 3. Bugs from earlier versions cannot be solved 
in the new version since the pre 2.9 and the 2.9 and later versions 
are completely different internally.

inxi strives to support the widest range of operating systems and 
hardware, from the most simple consumer desktops, to the most advanced
professional hardware and servers. 

The issues you post help maintain or expand that support, and are 
always appreciated since user data and feedback is what keeps inxi 
working and supporting the latest or not so latest hardware and 
operating systems. See the BSD section below for qualifications re 
BSDs and OSX.

=====================================================================
MASTER BRANCH:

This is the only supported branch, and the current latest commit is
the only supported 'release'. There are no 'releases' of inxi beyond 
the current commit to master. All past commits are not supported. 

git clone https://github.com/smxi/inxi --branch master --single-branch

OR direct fast and easy install:
wget -Nc https://github.com/smxi/inxi/raw/master/inxi

OR easy to remember shortcut (which redirects to github):
wget -Nc https://smxi.org/inxi
wget -Nc smxi.org/inxi

'Tagging' is purely a formality that certain distros can't figure out 
how to do without, that's all. A tag is a pointer to a commit, and has 
no further meaning. 

NOTE: Just because github calls tagged commits 'Releases' does not 
mean they are releases! I can't change the words on the tag page. 
They are tagged commmits, period. I did not want to use tags precisely 
to avoid the idea that inxi has any release that exists that is other 
than it's current master version, but I decided that it was less pain 
to add tags than to argue this point any further. 

=====================================================================
DEVELOPMENT BRANCH:
All active development is now done on the inxi-perl branch (pinxi):

git clone https://github.com/smxi/inxi --branch inxi-perl --single-branch

OR direct fast and easy install:
wget -Nc https://github.com/smxi/inxi/raw/inxi-perl/pinxi

OR easy to remember shortcut (which redirects to github):
wget -Nc https://smxi.org/pinxi
wget -Nc smxi.org/pinxi

Once new features have been debugged, tested, and are stable, they 
will move to the master branch.

=====================================================================
LEGACY BRANCH:
If you'd like to look at or check out the Gawk/Bash version of inxi, 
you can find it here, at the inxi-legacy branch (binxi):

git clone https://github.com/smxi/inxi --branch inxi-legacy --single-branch

OR direct fast and easy install:
wget -Nc https://github.com/smxi/inxi/raw/inxi-legacy/binxi

OR easy to remember shortcut (which redirects to github):
wget -Nc https://smxi.org/binxi

This version will not be maintained, and it's unlikely that any time
will be spent on it in the future, but it is there in case it's of
use or interest to anyone.

=====================================================================
SUPPORT INFO:

Do not ask for basic help that reading the inxi -h / --help menus, or 
man page would show you, and do not ask for features to be added that
inxi already has. Also do not ask for support if your distro won't 
update its inxi version, some are bad about that.

DOCUMENTATION: https://smxi.org/docs/inxi.htm 
(smxi.org/docs/ is easier to remember, and is one click away from 
inxi.htm). The one page wiki on github is only a pointer to the real 
resources.

https://github.com/smxi/inxi/tree/inxi-perl/docs
Contains specific Perl inxi documentation, of interest mostly to 
developers. Includes internal inxi tools, values, configuration items.
Also has useful information about Perl version support, including the 
list of Core modules that _should_ be included in a distribution's
core modules, but which are unfortunately sometimes removed. 

HTML MAN PAGE: https://smxi.org/docs/inxi-man.htm 
INXI OPTIONS PAGE: http://smxi.org/docs/inxi-options.htm 
NOTE: These may not always be up to date, but generally track the most 
recent inxi commits.

ISSUES: https://github.com/smxi/inxi/issues
No issues accepted for non current inxi releases. See below for more on 
that. Unfortunately as of 2.9, no support or issues can be accepted for 
older inxi's because inxi 2.9 (Perl) and newer is a full rewrite, and 
legacy inxi is not being supported since our time here on earth is 
finite (plus of course, one reason for the rewrite was to never have 
to work with Gawk->Bash again!).

SUPPORT FORUMS: https://techpatterns.com/forums/forum-33.html
This is the best place to place support issues that may be complicated.

If you are developer, use:
DEVELOPER FORUMS: https://techpatterns.com/forums/forum-32.html

SOURCE VERSION CONTROL: https://github.com/smxi/inxi
MAIN BRANCH: master
DEVELOPMENT BRANCHES: inxi-perl, one, two
inxi-perl is the dev branch, the others are rarely if ever used. inxi 
itself has the built in feature to be able to update itself from 
anywhere, including these branches, which is very useful for development 
and debugging on various user systems.

PULL REQUESTS: Please talk to me before starting to work on patches of 
any reasonable complexity. inxi is hard to work on, and you have to 
understand how it works before submitting patches, unless it's a trivial 
bug fix. Please: NEVER even think about looking at or using previous 
inxi commits, previous to the current master version, as a base for a 
patch. If you do, your patch / pull request will probably be rejected. 
Developers, get your version from the inxi-perl branch, pinxi, otherwise 
you may not be current to actual development versions. inxi-perl pinxi 
is always equal to or ahead of master branch inxi.

Man page updates, doc page updates, etc, of course, are easy and will 
probably be accepted, as long as they are properly formatted and 
logically coherent. 

inxi releases early, and releases often, when under development. 

PACKAGERS: inxi has one and only one 'release', and that is the current 
commit to master branch (plus pinxi inxi-perl branch, of course, but 
those should never be packaged). 

=====================================================================
ABOUT INXI - CORE COMMITMENT TO LONG TERM STABILITY

inxi is a command line system information tool. It was forked from the 
ancient and mindbendingly perverse yet ingenius infobash, by locsmif. 

That was a buggy, impossible to update or maintain piece of software, 
so the fork fixed those core issues, and made it flexible enough to 
expand the utility of the original ideas. Locmsif has given his thumbs 
up to inxi, so don't be fooled by legacy infobash stuff you may see 
out there.

inxi is lower case, except when I create a text header here in a file 
like this, but it's always lower case. Sometimes to follow convention 
I will use upper case inxi to start a sentence, but i find it a bad 
idea since invariably, someone will repeat that and type it in as the 
command name, then someone will copy that, and complain that the 
command: Inxi doesn't exist...

The primary purpose of inxi is for support, and sys admin use. inxi 
is used widely for forum and IRC support, which is I believe it's most 
common function.

If you are piping output to paste or post (or writing to file), inxi 
now automatically turns off color codes, so the old suggestion to 
use -c 0 to turn off colors is no longer required.

inxi should always show you your current system state, as far as 
possible, and should be more reliable than your own beliefs about 
what is in your system, ideally. In other words, the goal in inxi 
is to have it be right more than it is wrong about any system that 
it runs on. And not to rely on non current system state data if at 
all possible. Some things, like memory/ram data, rely on radically 
unreliable system self reporting based on OEM filling out data
correctly, which doesn't often happen, so in those cases, you want to 
confirm things like ram capacity with a reputable hardware source, 
like crucial.com, which has the best ram hardware tool I know of.

The core mission of inxi is to always work on all systems all the 
time. Well, all systems with the core tools inxi requires to operate 
installed. Ie, not Android, yet. What this means is this: you can 
have a 10 year old box, or probably 15, not sure, and you can install 
today's inxi on it, and it will run. It won't run fast, but it will 
run. I test inxi on a 200 MHz laptop from about 1998 to keep it 
honest. That's also what was used to optimize the code at some 
points, since differences appear as seconds, not 10ths or 100ths 
of seconds on old systems like that.

inxi is being written, and tested, on Perl as old as 5.08, and will 
work on any system that runs Perl 5.08 or later. Pre 2.9.0 Gawk/Bash 
inxi will also run on any system no matter how old, within reason, 
so there should be no difference.

=====================================================================
BSD SUPPORT

BSD support is not as complete as GNU/Linux support due to the fact 
some of the data simply is not available, or is structured in a way 
that makes it unique to each BSD. This fragmentation makes supporting 
BSDs far more difficult than it should be in the 21st century. The 
BSD support in inxi is an ongoing process, with more features being 
added as new data sources and types are discovered.

All BSD issue reports unless trivial and obvious will require 1 of 
two things:

1. a full --debug 21 data dump so I don't have to spend days trying 
to get the information I need to resolve the issue file by painful 
file from the issue poster. This is only the start of the process, 
and realistically requires 2. to complete it.

2. direct SSH access to at least a comparable live BSD version/system, 
that is, if the issue is on a laptop, access has to be granted to the 
laptop, or a similar one. 

Option 2 is far preferred because in terms of my finite time on this 
planet of ours, the fact is, if I don't have direct (or SSH) access, 
I can't get much done, and the little I can get done will take 10 to 
1000x longer than it should. That's my time spent (and sadly, with 
BSDs, largely lost), not yours. 

I decided I have to adopt this much more strict policy with BSDs 
after wasting untold hours on trying to get good BSD support, only 
to see that support break a few years down the road as the data inxi 
relied in changed structure or syntax, or the tools changed, or 
whatever else makes the BSDs such a challenge to support. In the end, 
I realized, the only BSDs that are well supported are ones that I have 
had direct access to for debugging and testing. 

I will always accept patches that are well done, if they do not break 
GNU/Linux, and extend BSD support, or add new BSD features, and follow 
the internal inxi logic, and aren't too long. inxi sets initial internal 
flags to identify that it is a BSD system vs a GNU/Linux system, and 
preloads some data structures for BSD use, so make sure you understand 
what inxi is doing before you get into it.

inxi will also start on Darwin, OSX's mutated version of a BSD, but 
my conclusion about Darwin is that it is Unix in name only, and I will 
not spend any of my finite time adding any further support for OSX.

=====================================================================
INXI FEATURES AND FUNCTIONALITY

inxi's functionality continues to grow over time, but it's also 
important to understand that each core new feature usually requires 
about 30 days work to get it stable. So new features are not trivial 
things, nor is it acceptable to submit a patch that works only on your 
personal system. One inxi feature (-s, sensors data), took about 
2 hours to get working in the alpha test on the local dev system, but 
then to handle the massive chaos that is actual user sensors output 
and system variations, it took several rewrites and about 30 days to 
get somewhat reliable for about 98% or so of inxi users. So if your
patch is rejected, it's likely because you have not thought it through 
adequately, have not done adequate testing cross system and 
platform, etc.

=====================================================================
INXI RELEASE/SUPPORT/ISSUES/BUGS INFORMATION:

Important: the only version of inxi that is supported is the latest 
current master branch release. No issue reports or bug reports will be 
accepted for anything other than current master branch. No merges, 
attempts to patch old code from old releases, will be considered or 
accepted. If you are not updated to the latest inxi, do not file a 
bug report since it's probably been fixed ages ago. If your distro 
isn't packaging a current inxi, then file a bug report with them, not 
here. The only valid working code base for inxi is the current 
release of inxi. 

Distributions should never feel any advantage comes from using old 
inxi releases because inxi has as a core promise to you, the end user, 
that it will NEVER require new tools to run. New tools may be required 
for a new feature, but that will always be handled internally by inxi, 
and will not cause any operational failures. This is a promise, and I 
will never as long as I run this project violate that core inxi 
requirement. Old inxi is NOT more stable than current inxi, it's just 
old, and lacking in bug fixes and features. For pre 2.9 releases, it's 
also significantly slower, and with fewer features.

inxi is a rolling release codebase, just like Debian Sid, Gentoo, or 
Arch Linux are rolling release GNU/Linux distributions, with no 
'release points'.

Your distro not updating inxi ever, then failing to show something 
that is fixed in current inxi is not a bug, and please do not post it 
here. File the issue with your distro, not here. Updating inxi in a 
package pool will NEVER make anything break or fail, period. It has no 
version based dependencies, just software, like Perl 5.xx, lspci, etc. 
There is never a valid reason to not update inxi in a package pool of 
any distro in the world (with one single known exception, the Slackware 
based Puppy Linux release, which ships without the full Perl language. 
The Debian based one works fine).

Sys Admin type inxi users always get the first level of support. ie, 
convince us you run real systems and networks, and your issue shoots 
to the top of the line. As do any real bugs. Failure to supply 
requested debugger data will lead to a distinct lack of interest on 
our part to help you with a bug. ie, saying, oh, x doesn't work, 
doesn't cut it, unless it's obvious why. 

=====================================================================

INXI VERSION NUMBERING:

inxi uses 'semantic' version numbering, where the version numbers 
actually mean something.

The version number follows these guidelines:
Using example 3.2.28-6

The first digit(s), "3", is a major version, and almost never changes. 
Only a huge milestone, or if inxi reaches 3.9.xx, when it will simply 
move up to 4.0.0 just to keep it clean, would cause a change. 

The second digit(s), "2", means a new real feature has been added. 
Not a tweaked existing feature, an actual new feature, which usually 
also has a new argument option letter attached. The second number goes 
from 0 to 9, and then rolls over the first after 9. It could also be 
adding a very complicated expansion of existing features, like Wayland. 
It depends.

The third, "28", is for everything small, can cover bug fixes, tweaks 
to existing features to add support for something, pretty much anything 
where you want the end user to know that they are not up to date. The 
third goes from 0 to 99, then rolls over the second.

The fourth, "6", is extra information about certain types of inxi 
updates. I don't usually use this last one in master branch, but you 
will see it in branches one,two, inxi-perl, inxi-legacy since that is 
used to confirm remote test system patch version updates.

The fourth number, when used, will be alpha-numeric, a common version 
would be, in say, branch one: 2.2.28-b1-02, in other words, a branch 1 
release, version 2.

In the past, now and then the 4th, or 'patch', number, was used in 
trunk/master branches of inxi, but I've pretty much stopped doing that 
because it's confusing.

inxi does not use the fiction of date based versioning because that 
imparts no useful information to the end user, when you look at say, 
2.2.28, and you last had 2.2.11, you can know with some certainty that 
inxi has no major new features, just fine tunings and bug fixes. And 
if you see one with 2.3.2, you will know that there is a new feature, 
almost, but not always, linked to one or more new line output items. 
Sometimes a fine tuning can be quite significant, sometimes it's a 
one line code fix. 

A move to a new full version number, like the rewrite of inxi to Perl,
would reflect in first version say, 2.9.01, then after a period of 
testing, where most little glitches are fixed, a move to 3.0.0. These 
almost never happen. I do not expect for example version 4.0 to ever 
happen after the 3.0 release of early 2018, unless so many new 
features are added that it actually hits 3.9, then it would roll 
over to 4.

### EOF ###