Browse Source

More markdownification of READMEs

master
Matteo Cypriani 1 year ago
parent
commit
d9fd78cdee
8 changed files with 253 additions and 254 deletions
  1. 0
    54
      archivers/README
  2. 55
    0
      archivers/README.md
  3. 0
    32
      backup/README
  4. 35
    0
      backup/README.md
  5. 0
    79
      file_utils/README
  6. 81
    0
      file_utils/README.md
  7. 0
    89
      git/README
  8. 82
    0
      git/README.md

+ 0
- 54
archivers/README View File

@@ -1,54 +0,0 @@
1
-# lz.sh (lz and uz) #
2
-
3
-The lz.sh script emulates and extends commands lz and uz from the
4
-mtools.
5
-
6
-NOTE: although lz.sh is more powerful than mtools' lz and uz, you should
7
-probably use als and aunpack from the atool package instead; they are
8
-much better and atool provides several other useful commands as well.
9
-This script is still useful when you can't install Perl (atool is
10
-written in Perl).
11
-
12
-This script handles the following archive formats through the standards
13
-options of GNU Tar:
14
-- tar
15
-- tar.gz (tgz)
16
-- tar.bz2 (tbz, tb2)
17
-- tar.xz (txz)
18
-- tar.lzma (tlz)
19
-- tar.Z (taz)
20
-
21
-Note that you need GNU Tar, at least version 1.20 to support LZMA
22
-compressed archives, and version 1.22 for XZ compressed ones.
23
-
24
-If the script name is "lz", the archive content is displayed. If the
25
-name is "uz", it is extracted.
26
-
27
-To install lz and uz, move put script in a directory in the PATH (for
28
-instance /usr/local/bin) and hard link it to uz:
29
-  cp lz.sh /usr/local/bin/lz
30
-  ln /usr/local/bin/{lz,uz}
31
-
32
-Alternatively, you can use directly the symbolic links provided along
33
-with the repository by adding the "bin" directory to your PATH, as
34
-explained in the main README file.
35
-
36
-
37
-# xzize.sh #
38
-
39
-The xzize script compresses an uncompressed file, or recompresses a
40
-compressed file to xz (with default compression level).
41
-
42
-Known compression formats are GZip (.gz), BZip2 (.bz2), LZMA (.lzma),
43
-and Lempel-Ziv (.Z). Short tar compressed suffixes are also allowed:
44
-.tgz, .tbz, .tb2, .tlz, .taz.
45
-
46
-In case of recompression, the original compressed file is kept. In
47
-case of compression (i.e. when the suffix of the file does not
48
-correspond to a known compression format), the original uncompressed
49
-file is removed.
50
-
51
-NOTE: the atool package provides the arepack command, which can
52
-recompress to several formats and not only to xz. xzize has the
53
-advantage to recompress on the fly rather than unpacking the archive
54
-entirely on the file system and repacking it afterwards.

+ 55
- 0
archivers/README.md View File

@@ -0,0 +1,55 @@
1
+lz.sh (lz and uz)
2
+=================
3
+
4
+The `lz.sh` script emulates and extends commands `lz` and `uz` from the mtools.
5
+
6
+**Note**: although `lz.sh` is more powerful than mtools' `lz` and `uz`, you
7
+should probably use `als` and `aunpack` from the atool package instead; they
8
+are much better and atool provides several other useful commands as well. This
9
+script is still useful when you can't install Perl (atool is written in Perl).
10
+
11
+This script handles the following archive formats through the standards options
12
+of GNU Tar:
13
+
14
+- tar
15
+- tar.gz (tgz)
16
+- tar.bz2 (tbz, tb2)
17
+- tar.xz (txz)
18
+- tar.lzma (tlz)
19
+- tar.Z (taz)
20
+
21
+Note that you need GNU Tar, at least version 1.20 to support LZMA compressed
22
+archives, and version 1.22 for XZ compressed ones.
23
+
24
+If the script is called as `lz`, the archive content is displayed. When called
25
+as `uz`, it is extracted.
26
+
27
+To install `lz` and `uz`, move the script as `lz` in a directory in your `PATH`
28
+(for instance `/usr/local/bin` or `$HOME/bin`) and hard link it to `uz`:
29
+
30
+    cp lz.sh /usr/local/bin/lz
31
+    ln /usr/local/bin/{lz,uz}
32
+
33
+Alternatively, you can use the symbolic links provided along with the
34
+repository by adding the `bin` directory to your `PATH`, as explained in the
35
+main `README.md` file.
36
+
37
+
38
+xzize.sh
39
+========
40
+
41
+The `xzize.sh` script compresses an uncompressed file, or recompresses a
42
+compressed file to XZ (with default compression level).
43
+
44
+Known compression formats are GZip (.gz), BZip2 (.bz2), LZMA (.lzma), and
45
+Lempel-Ziv (.Z). Short tar compressed suffixes are also allowed: .tgz, .tbz,
46
+.tb2, .tlz, .taz.
47
+
48
+In case of recompression, the original compressed file is kept. In case of
49
+compression (i.e. when the suffix of the file does not correspond to a known
50
+compression format), the original uncompressed file is removed.
51
+
52
+**Note**: the atool package provides the `arepack` command, which can
53
+recompress to several formats and not only to XZ. `xzize` has the advantage to
54
+recompress on the fly rather than unpacking the archive entirely on the file
55
+system and repacking it afterwards.

+ 0
- 32
backup/README View File

@@ -1,32 +0,0 @@
1
-# obstinate-rsync.sh #
2
-
3
-obstinate-rsync.sh is a simple script that transfers a single directory
4
-(your home directory, by default) to a remote host, using rsync. You can
5
-specify exclude patterns in a file (~/.backup-excludes by default). The
6
-transfer will be reattempted until it succeeds.
7
-
8
-Edit the script to configure the protocol, host, directories, etc.
9
-
10
-
11
-# btrfs_snapshot_date.sh #
12
-
13
-This script is a wrapper to btrfs subvolume snapshot, that creates a
14
-snapshot of a subvolume, the snapshot's name being the subvolume name
15
-with the current date and time appended to it.
16
-
17
-It is supposed that the subvolume to snapshot resides in a directory
18
-which needs to be mounted before to make the snapshot (for example if
19
-you defined your default subvolume to your system's root, and mount the
20
-volume 0 on /media/pool).
21
-
22
-Edit the script to configure the directories (and to understand what is
23
-being done).
24
-
25
-
26
-# backup_sites_mysql.sh #
27
-
28
-The script backup_sites_mysql.sh is designed to save websites data files
29
-and the associated MySQL databases.
30
-
31
-You need to edit the script to configure the databases you want to backup
32
-and the directory containing all your websites.

+ 35
- 0
backup/README.md View File

@@ -0,0 +1,35 @@
1
+obstinate-rsync.sh
2
+==================
3
+
4
+`obstinate-rsync.sh` is a simple script that transfers a single directory (your
5
+home directory, by default) to a remote host, using rsync. You can specify
6
+exclude patterns in a file (`~/.backup-excludes` by default). The transfer will
7
+be reattempted until it succeeds.
8
+
9
+Edit the script to configure the protocol, host, directories, etc.
10
+
11
+
12
+btrfs_snapshot_date.sh
13
+======================
14
+
15
+This script is a wrapper to `btrfs subvolume snapshot`, that creates a snapshot
16
+of a subvolume, the snapshot's name being the subvolume name with the current
17
+date and time appended to it.
18
+
19
+It is assumed that the subvolume to snapshot resides in a directory which needs
20
+to be mounted before making the snapshot (for example if you defined your
21
+default subvolume to your system's root, and mount the volume 0 on
22
+`/media/pool`).
23
+
24
+Edit the script to configure the directories (and to understand what is being
25
+done).
26
+
27
+
28
+backup_sites_mysql.sh
29
+=====================
30
+
31
+This script is designed to save websites data files and the associated MySQL
32
+databases.
33
+
34
+You need to edit the script to configure the databases you want to backup and
35
+the directory containing all of your websites' files (the “document root”).

+ 0
- 79
file_utils/README View File

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

+ 81
- 0
file_utils/README.md View File

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

+ 0
- 89
git/README View File

@@ -1,89 +0,0 @@
1
-# git-changelog #
2
-
3
-git-changelog allows one to build a changelog file from the tag
4
-messages. The tags considered are those whose names follow the format
5
-vX.Y[.Z[...]] (for example v1.2, v0.0.1, v4.3.2.1, etc.).
6
-
7
-One can edit the options into the script to change the message displayed
8
-at the top of the changelog, and the number of line to separate two tag
9
-messages.
10
-
11
-The changelog is displayed on the standard output, in reverse order
12
-(higher version numbers first), whereas the error output displays the
13
-included or skipped tag names (i.e. those which do not correspond to the
14
-pattern).
15
-
16
-Note that if there is no tag at all in the repository, no particular
17
-warning will be displayed.
18
-
19
-You can make this script a Git command by putting it in a directory
20
-within your PATH (e.g. /usr/local/bin) and add an alias in your Git
21
-configuration:
22
-
23
- git config --global alias.changelog "\!sh -c 'git-changelog'"
24
-
25
-
26
-# git-cherry-move #
27
-
28
-git-cherry-move is like git cherry-pick, but it moves the commit
29
-instead of copying it.
30
-
31
-It is designed to move a single commit from a branch head to another
32
-branch head. It is the equivalent of git cherry-pick followed by git
33
-reset.
34
-
35
-Usage:
36
- git-cherry-move source_branch destination_branch [ reset-arg ]
37
-
38
-reset-arg is passed as the first argument of reset, so please be careful!
39
-
40
-To move the last commit of source_branch on top of destination_branch,
41
-you can type the following:
42
- git-cherry-move source_branch destination_branch
43
-After this, you will be on source_branch, the HEAD being on the parent
44
-of the old source_branch head. The changes introduced by the moved
45
-commit are not deleted from the file system (soft reset).
46
-
47
-If you want these changes to be deleted (hard reset), use --hard as the
48
-*last* argument:
49
- git-cherry-move source_branch destination_branch --hard
50
-
51
-To activate the git cherry-move command, put the git-cherry-move script
52
-in a directory in the PATH (for instance /usr/local/bin) and add an
53
-alias:
54
-
55
- git config --global alias.cherry-move "\!sh -c 'git-cherry-move'"
56
-
57
-
58
-# git-merge-ff-only #
59
-
60
-git-merge-ff-only main_branch topic_branch is the equivalent of the
61
-following commands:
62
-
63
- git checkout main_branch && git merge --ff-only topic_branch
64
-
65
-except that main_branch is not checked out. The reference is updated
66
-directly (if possible), and HEAD stays on whatever branch was checked
67
-out before running the command.
68
-
69
-To activate the git merge-ff-only command, put the git-merge-ff-only
70
-script in a directory in the PATH (for instance /usr/local/bin) and
71
-add an alias:
72
-
73
- git config --global alias.merge-ff-only "\!sh -c 'git-merge-ff-only'"
74
-
75
-
76
-# git-tag-update #
77
-
78
-git-tag-update allows one to update a tag message while automatically
79
-keeping its original date. It takes the name of the tag to update as an
80
-argument.
81
-
82
-Beware that the tag's author will be changed to whatever is the current
83
-author. You can change it temporarily with git config if you need to
84
-update commits with different authors.
85
-
86
-To activate the git tag-update command, put the git-tag-update script in
87
-a directory in the PATH (for instance /usr/local/bin) and add an alias:
88
-
89
- git config --global alias.tag-update "\!sh -c 'git-tag-update'"

+ 82
- 0
git/README.md View File

@@ -0,0 +1,82 @@
1
+The scripts in this directory are designed to be installed as new git
2
+sub-commands. To do so, install the scripts in a directory within your `PATH`
3
+(or add the repository's `bin` directory to your `PATH`, see the main
4
+`README.md`), and use `git config` to add aliases:
5
+
6
+    git config --global alias.changelog "\!sh -c 'git-changelog'"
7
+    git config --global alias.cherry-move "\!sh -c 'git-cherry-move'"
8
+    git config --global alias.merge-ff-only "\!sh -c 'git-merge-ff-only'"
9
+    git config --global alias.tag-update "\!sh -c 'git-tag-update'"
10
+
11
+
12
+git-changelog
13
+=============
14
+
15
+`git-changelog` allows one to build a changelog file from the tag messages. The
16
+tags considered are those whose names follow the format `vX.Y[.Z[...]]` (for
17
+example v1.2, v0.0.1, v4.3.2.1, etc.).
18
+
19
+One can edit the options into the script to change the message displayed at the
20
+top of the changelog, and the number of lines that will separate two tag
21
+messages.
22
+
23
+The changelog is displayed on the standard output, in reverse order (higher
24
+version numbers first), whereas the error output displays the included or
25
+skipped tag names (i.e. those that don't correspond to the pattern).
26
+
27
+Note that if there is no tag at all in the repository, no particular warning
28
+will be displayed.
29
+
30
+
31
+git-cherry-move
32
+===============
33
+
34
+`git-cherry-move` is like `git cherry-pick`, but it moves the commit instead of
35
+copying it.
36
+
37
+It is designed to move a single commit from a branch head to another branch
38
+head. It is the equivalent of git cherry-pick followed by git reset.
39
+
40
+Usage:
41
+
42
+    git-cherry-move source_branch destination_branch [ reset-arg ]
43
+
44
+`reset-arg` is passed as the first argument of `reset`, so please be careful!
45
+
46
+So to move the last commit of `source_branch` on top of `destination_branch`,
47
+simply type:
48
+
49
+    git-cherry-move source_branch destination_branch
50
+
51
+After this, you will be on `source_branch`, the HEAD being on the parent of the
52
+old `source_branch` head. The changes introduced by the moved commit are not
53
+deleted from the file system (soft reset).
54
+
55
+If you want these changes to be deleted (hard reset), use `--hard` as the
56
+*last* argument:
57
+
58
+    git-cherry-move source_branch destination_branch --hard
59
+
60
+
61
+git-merge-ff-only
62
+=================
63
+
64
+`git-merge-ff-only main_branch topic_branch` is the equivalent of the following
65
+commands:
66
+
67
+    git checkout main_branch && git merge --ff-only topic_branch
68
+
69
+except that `main_branch` is not checked out. The reference is updated directly
70
+(if possible), and HEAD stays on whichever branch was checked out before
71
+running the command.
72
+
73
+
74
+git-tag-update
75
+==============
76
+
77
+`git-tag-update` allows one to update a tag message while automatically keeping
78
+its original date. It takes the name of the tag to update as an argument.
79
+
80
+Beware that the tag's author will be changed to whoever is the current author.
81
+You can change it temporarily with `git config` if you need to update commits
82
+with different authors.

Loading…
Cancel
Save