Browse Source

More markdownification of READMEs

master
Matteo Cypriani 4 years ago
parent
commit
d9fd78cdee
  1. 54
      archivers/README
  2. 55
      archivers/README.md
  3. 32
      backup/README
  4. 35
      backup/README.md
  5. 79
      file_utils/README
  6. 81
      file_utils/README.md
  7. 89
      git/README
  8. 82
      git/README.md

54
archivers/README

@ -1,54 +0,0 @@
# lz.sh (lz and uz) #
The lz.sh script emulates and extends commands lz and uz from the
mtools.
NOTE: although lz.sh is more powerful than mtools' lz and uz, you should
probably use als and aunpack from the atool package instead; they are
much better and atool provides several other useful commands as well.
This script is still useful when you can't install Perl (atool is
written in Perl).
This script handles the following archive formats through the standards
options of GNU Tar:
- tar
- tar.gz (tgz)
- tar.bz2 (tbz, tb2)
- tar.xz (txz)
- tar.lzma (tlz)
- tar.Z (taz)
Note that you need GNU Tar, at least version 1.20 to support LZMA
compressed archives, and version 1.22 for XZ compressed ones.
If the script name is "lz", the archive content is displayed. If the
name is "uz", it is extracted.
To install lz and uz, move put script in a directory in the PATH (for
instance /usr/local/bin) and hard link it to uz:
cp lz.sh /usr/local/bin/lz
ln /usr/local/bin/{lz,uz}
Alternatively, you can use directly the symbolic links provided along
with the repository by adding the "bin" directory to your PATH, as
explained in the main README file.
# xzize.sh #
The xzize script compresses an uncompressed file, or recompresses a
compressed file to xz (with default compression level).
Known compression formats are GZip (.gz), BZip2 (.bz2), LZMA (.lzma),
and Lempel-Ziv (.Z). Short tar compressed suffixes are also allowed:
.tgz, .tbz, .tb2, .tlz, .taz.
In case of recompression, the original compressed file is kept. In
case of compression (i.e. when the suffix of the file does not
correspond to a known compression format), the original uncompressed
file is removed.
NOTE: the atool package provides the arepack command, which can
recompress to several formats and not only to xz. xzize has the
advantage to recompress on the fly rather than unpacking the archive
entirely on the file system and repacking it afterwards.

55
archivers/README.md

@ -0,0 +1,55 @@
lz.sh (lz and uz)
=================
The `lz.sh` script emulates and extends commands `lz` and `uz` from the mtools.
**Note**: although `lz.sh` is more powerful than mtools' `lz` and `uz`, you
should probably use `als` and `aunpack` from the atool package instead; they
are much better and atool provides several other useful commands as well. This
script is still useful when you can't install Perl (atool is written in Perl).
This script handles the following archive formats through the standards options
of GNU Tar:
- tar
- tar.gz (tgz)
- tar.bz2 (tbz, tb2)
- tar.xz (txz)
- tar.lzma (tlz)
- tar.Z (taz)
Note that you need GNU Tar, at least version 1.20 to support LZMA compressed
archives, and version 1.22 for XZ compressed ones.
If the script is called as `lz`, the archive content is displayed. When called
as `uz`, it is extracted.
To install `lz` and `uz`, move the script as `lz` in a directory in your `PATH`
(for instance `/usr/local/bin` or `$HOME/bin`) and hard link it to `uz`:
cp lz.sh /usr/local/bin/lz
ln /usr/local/bin/{lz,uz}
Alternatively, you can use the symbolic links provided along with the
repository by adding the `bin` directory to your `PATH`, as explained in the
main `README.md` file.
xzize.sh
========
The `xzize.sh` script compresses an uncompressed file, or recompresses a
compressed file to XZ (with default compression level).
Known compression formats are GZip (.gz), BZip2 (.bz2), LZMA (.lzma), and
Lempel-Ziv (.Z). Short tar compressed suffixes are also allowed: .tgz, .tbz,
.tb2, .tlz, .taz.
In case of recompression, the original compressed file is kept. In case of
compression (i.e. when the suffix of the file does not correspond to a known
compression format), the original uncompressed file is removed.
**Note**: the atool package provides the `arepack` command, which can
recompress to several formats and not only to XZ. `xzize` has the advantage to
recompress on the fly rather than unpacking the archive entirely on the file
system and repacking it afterwards.

32
backup/README

@ -1,32 +0,0 @@
# obstinate-rsync.sh #
obstinate-rsync.sh is a simple script that transfers a single directory
(your home directory, by default) to a remote host, using rsync. You can
specify exclude patterns in a file (~/.backup-excludes by default). The
transfer will be reattempted until it succeeds.
Edit the script to configure the protocol, host, directories, etc.
# btrfs_snapshot_date.sh #
This script is a wrapper to btrfs subvolume snapshot, that creates a
snapshot of a subvolume, the snapshot's name being the subvolume name
with the current date and time appended to it.
It is supposed that the subvolume to snapshot resides in a directory
which needs to be mounted before to make the snapshot (for example if
you defined your default subvolume to your system's root, and mount the
volume 0 on /media/pool).
Edit the script to configure the directories (and to understand what is
being done).
# backup_sites_mysql.sh #
The script backup_sites_mysql.sh is designed to save websites data files
and the associated MySQL databases.
You need to edit the script to configure the databases you want to backup
and the directory containing all your websites.

35
backup/README.md

@ -0,0 +1,35 @@
obstinate-rsync.sh
==================
`obstinate-rsync.sh` is a simple script that transfers a single directory (your
home directory, by default) to a remote host, using rsync. You can specify
exclude patterns in a file (`~/.backup-excludes` by default). The transfer will
be reattempted until it succeeds.
Edit the script to configure the protocol, host, directories, etc.
btrfs_snapshot_date.sh
======================
This script is a wrapper to `btrfs subvolume snapshot`, that creates a snapshot
of a subvolume, the snapshot's name being the subvolume name with the current
date and time appended to it.
It is assumed that the subvolume to snapshot resides in a directory which needs
to be mounted before making the snapshot (for example if you defined your
default subvolume to your system's root, and mount the volume 0 on
`/media/pool`).
Edit the script to configure the directories (and to understand what is being
done).
backup_sites_mysql.sh
=====================
This script is designed to save websites data files and the associated MySQL
databases.
You need to edit the script to configure the databases you want to backup and
the directory containing all of your websites' files (the “document root”).

79
file_utils/README

@ -1,79 +0,0 @@
# dirpacker.py #
This scripts allows to group (pack) a bunch of files or directories into
fixed-size volumes, optimizing the occupied size of the volumes. The
original use case was to burn MP3 albums to CD-ROMs to play them in the
car, but minimize the wasted space of each disc. Of course, it can be
used to backup any kind of files to any kind of medium.
The particularity of this program, compared for example to datapacker
(from which it is loosely inspired) is that it works with directories
instead of regular files only. The files inside a directory won't be
separated on several archives, they will be on the same volume.
Note: I kept the datapacker's terminology in which a volume is also
called a bin.
The default bin size is 703 MiB, i.e. the capacity of a 80-minute
CD-ROM; note that this can lead to slightly exceed the capacity when
actually burning the disc, so if you don't want to overburn a few
hundreds KiB, choose a lower bin size (702 MiB should be fine).
By default, dirpacker displays a list of bins and the files they
would contain, along with the size of each file and some statistics.
With the option --machine-readable, this list will be printed in a
machine-readable format: each line contains a bin's name, then a
tabulation, then a file that belongs to this bin.
With the option --move, a directory will be created for each volume and
the files will be moved to the corresponding volume.
To see the full usage, call the program with -h.
# mvparent.sh #
mvparent.sh was originally written to be integrated in the ROX-Filer
directory "Send to" menu (and was named mv_here.sh). It moves the
contents of a directory into its parent directory, then deletes the
empty directory.
To install this script, just copy it in a directory which is in the
PATH, e.g. /usr/local/bin:
cp mvparent.sh /usr/local/bin
If you want to integrate it in ROX-Filer:
mkdir -p ~/.config/rox.sourceforge.net/SendTo/.inode_directory
cd ~/.config/rox.sourceforge.net/SendTo/.inode_directory
ln -s `which mvparent.sh` "Move here"
# unln.py #
I wrote this script after accidentally merging all my "duplicate" files
with the cleaning tool fslint (thanks guys for a totally confusing clear
UI!). It does the opposite than the ln command, that is separate file
names given as arguments from their respective inodes by doing the
equivalent of (cp -p file tmp && mv tmp file). Checks are done in order
to work only on regular files which have more than one hard link, so the
minimal amount of copies are done.
A summary of the file names on which errors were raised is displayed at
the end of the execution. Note that if a file is under a directory which
is not executable (i.e. the program can't cd in), it will be considered
as inexistant and ignored, and its name won't be displayed.
/!\ Warning: the copy function used is shutil.copy2(), which tries to
preserve all the metadata it can, but as of Python 3.3 it is not
guaranteed that extended attributes will be preserved. See the
documentation for details:
http://docs.python.org/3/library/shutil.html
/!\ FILE OWNER AND GROUP CANNOT BE PRESERVED, as a file is always
created with the current user's UID and GID.
Tip: if you have a file listing all the file names you want to work on,
with one name per line, you can use xargs with --delimiter='\n':
xargs --delimiter='\n' <list.txt unln.py
Without this option, you would have troubles with file names containing
spaces.

81
file_utils/README.md

@ -0,0 +1,81 @@
dirpacker.py
============
This scripts allows you to group (pack) a bunch of files or directories into
fixed-size volumes, optimizing the occupied size of the volumes. The original
use case was to burn MP3 albums to CD-ROMs to play them in the car, while
minimizing the amount of wasted space on each disc. Of course, it can be used
to backup any kind of files to any kind of medium.
The particularity of this program, compared for example to datapacker (from
which it is loosely inspired) is that it works with directories instead of
regular files only. The files inside a directory won't be separated on several
archives, they will be on the same volume.
Note: I kept the datapacker's terminology in which a volume is also called a
bin.
The default bin size is 703 MiB, i.e. the capacity of a 80-minute CD-ROM; note
that this can lead to slightly exceed the capacity when actually burning the
disc, so if you don't want to overburn a few hundreds KiB, choose a lower bin
size (702 MiB should be fine).
By default, dirpacker displays a list of bins and the files they would contain,
along with the size of each file and some statistics. With the option
`--machine-readable`, this list will be printed in a machine-readable format:
each line contains a bin's name, then a tabulation, then a file that belongs to
this bin.
With the option `--move`, a directory will be created for each volume and the
files will be moved to the corresponding volume.
To see the full usage, call the program with `-h`.
mvparent.sh
===========
`mvparent.sh` was originally written to be integrated in the ROX-Filer
directory “Send to” menu. It moves the contents of a directory into its parent
directory, then deletes the empty directory.
To install this script, just copy it in a directory which is in your `PATH`, or
use the `bin` directory provided with the repository, as explained in the main
`README.md`.
If you want to integrate it in ROX-Filer:
mkdir -p ~/.config/rox.sourceforge.net/SendTo/.inode_directory
cp mvparent.sh ~/.config/rox.sourceforge.net/SendTo/.inode_directory/"Move here"
unln.py
=======
I wrote this script after accidentally merging all my “duplicate” files with
the cleaning tool `fslint` (thanks guys for a totally confusing UI!). It does
the opposite of the `ln` command, that is it separates file names given as
arguments from their respective inodes by doing the equivalent of `cp -p file
tmp && mv tmp file`. Checks are done in order to work only on regular files
that have more than one hard link, so the minimal amount of copies are done.
A summary of the file names on which errors were raised is displayed at the end
of the execution. Note that if a file is under a directory which is not
executable (i.e. the program can't `cd` in), it will be considered as
non-existent and ignored, and its name won't be displayed.
/!\ **Warning #1**: the Python copy function used is `shutil.copy2()`, which
tries to preserve all the metadata it can, but as of Python 3.3 it is not
guaranteed that extended attributes will be preserved. See the documentation
for details: <http://docs.python.org/3/library/shutil.html>.
/!\ **Warning #2**: file owner and group cannot be preserved, as a file is
always created (upon copy, in our case) with the current user's UID and GID.
**Tip**: if you have a file listing all the file names you want to work on,
with one name per line, you can use `xargs` with `--delimiter='\n'`:
xargs --delimiter='\n' <list.txt unln.py
(Without this option, you would have troubles with file names containing
spaces.)

89
git/README

@ -1,89 +0,0 @@
# git-changelog #
git-changelog allows one to build a changelog file from the tag
messages. The tags considered are those whose names follow the format
vX.Y[.Z[...]] (for example v1.2, v0.0.1, v4.3.2.1, etc.).
One can edit the options into the script to change the message displayed
at the top of the changelog, and the number of line to separate two tag
messages.
The changelog is displayed on the standard output, in reverse order
(higher version numbers first), whereas the error output displays the
included or skipped tag names (i.e. those which do not correspond to the
pattern).
Note that if there is no tag at all in the repository, no particular
warning will be displayed.
You can make this script a Git command by putting it in a directory
within your PATH (e.g. /usr/local/bin) and add an alias in your Git
configuration:
git config --global alias.changelog "\!sh -c 'git-changelog'"
# git-cherry-move #
git-cherry-move is like git cherry-pick, but it moves the commit
instead of copying it.
It is designed to move a single commit from a branch head to another
branch head. It is the equivalent of git cherry-pick followed by git
reset.
Usage:
git-cherry-move source_branch destination_branch [ reset-arg ]
reset-arg is passed as the first argument of reset, so please be careful!
To move the last commit of source_branch on top of destination_branch,
you can type the following:
git-cherry-move source_branch destination_branch
After this, you will be on source_branch, the HEAD being on the parent
of the old source_branch head. The changes introduced by the moved
commit are not deleted from the file system (soft reset).
If you want these changes to be deleted (hard reset), use --hard as the
*last* argument:
git-cherry-move source_branch destination_branch --hard
To activate the git cherry-move command, put the git-cherry-move script
in a directory in the PATH (for instance /usr/local/bin) and add an
alias:
git config --global alias.cherry-move "\!sh -c 'git-cherry-move'"
# git-merge-ff-only #
git-merge-ff-only main_branch topic_branch is the equivalent of the
following commands:
git checkout main_branch && git merge --ff-only topic_branch
except that main_branch is not checked out. The reference is updated
directly (if possible), and HEAD stays on whatever branch was checked
out before running the command.
To activate the git merge-ff-only command, put the git-merge-ff-only
script in a directory in the PATH (for instance /usr/local/bin) and
add an alias:
git config --global alias.merge-ff-only "\!sh -c 'git-merge-ff-only'"
# git-tag-update #
git-tag-update allows one to update a tag message while automatically
keeping its original date. It takes the name of the tag to update as an
argument.
Beware that the tag's author will be changed to whatever is the current
author. You can change it temporarily with git config if you need to
update commits with different authors.
To activate the git tag-update command, put the git-tag-update script in
a directory in the PATH (for instance /usr/local/bin) and add an alias:
git config --global alias.tag-update "\!sh -c 'git-tag-update'"

82
git/README.md

@ -0,0 +1,82 @@
The scripts in this directory are designed to be installed as new git
sub-commands. To do so, install the scripts in a directory within your `PATH`
(or add the repository's `bin` directory to your `PATH`, see the main
`README.md`), and use `git config` to add aliases:
git config --global alias.changelog "\!sh -c 'git-changelog'"
git config --global alias.cherry-move "\!sh -c 'git-cherry-move'"
git config --global alias.merge-ff-only "\!sh -c 'git-merge-ff-only'"
git config --global alias.tag-update "\!sh -c 'git-tag-update'"
git-changelog
=============
`git-changelog` allows one to build a changelog file from the tag messages. The
tags considered are those whose names follow the format `vX.Y[.Z[...]]` (for
example v1.2, v0.0.1, v4.3.2.1, etc.).
One can edit the options into the script to change the message displayed at the
top of the changelog, and the number of lines that will separate two tag
messages.
The changelog is displayed on the standard output, in reverse order (higher
version numbers first), whereas the error output displays the included or
skipped tag names (i.e. those that don't correspond to the pattern).
Note that if there is no tag at all in the repository, no particular warning
will be displayed.
git-cherry-move
===============
`git-cherry-move` is like `git cherry-pick`, but it moves the commit instead of
copying it.
It is designed to move a single commit from a branch head to another branch
head. It is the equivalent of git cherry-pick followed by git reset.
Usage:
git-cherry-move source_branch destination_branch [ reset-arg ]
`reset-arg` is passed as the first argument of `reset`, so please be careful!
So to move the last commit of `source_branch` on top of `destination_branch`,
simply type:
git-cherry-move source_branch destination_branch
After this, you will be on `source_branch`, the HEAD being on the parent of the
old `source_branch` head. The changes introduced by the moved commit are not
deleted from the file system (soft reset).
If you want these changes to be deleted (hard reset), use `--hard` as the
*last* argument:
git-cherry-move source_branch destination_branch --hard
git-merge-ff-only
=================
`git-merge-ff-only main_branch topic_branch` is the equivalent of the following
commands:
git checkout main_branch && git merge --ff-only topic_branch
except that `main_branch` is not checked out. The reference is updated directly
(if possible), and HEAD stays on whichever branch was checked out before
running the command.
git-tag-update
==============
`git-tag-update` allows one to update a tag message while automatically keeping
its original date. It takes the name of the tag to update as an argument.
Beware that the tag's author will be changed to whoever is the current author.
You can change it temporarily with `git config` if you need to update commits
with different authors.
Loading…
Cancel
Save